# 命令行 · HeroUI

> 使用命令行管理 HeroUI 依赖并初始化项目。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/getting-started/cli
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

`heroui-cli`是官方命令行工具，提供了一整套命令，用于初始化、管理和优化你的 HeroUI 项目。你可以 `install`、`uninstall` 或 `upgrade` 单个组件，检查项目健康状况，下载用于 AI 编程助手的文档，等等。

## 安装

环境要求：

- [Node.js 22.22.0 或更高版本](https://nodejs.org/en/)


### 全局安装

要全局安装 `heroui-cli`，请在终端中执行以下命令之一：


```npm
npm install heroui-cli@latest -g
```

### 无需安装直接使用

或者，你也可以在不进行全局安装的情况下使用 `heroui-cli`，运行以下命令之一即可：


  

#### pnpm


    ```bash
    pnpm dlx heroui-cli@latest
    ```
  
  

#### npm


    ```bash
    npx heroui-cli@latest
    ```
  
  

#### yarn


    ```bash
    yarn dlx heroui-cli@latest
    ```
  
  

#### bun


    ```bash
    bunx heroui-cli@latest
    ```
  


## 快速开始

安装 `heroui-cli` 后，运行以下命令以查看可用命令：

```bash
heroui
```

将会输出如下帮助信息：

```bash
Usage: heroui [command]

Options:
  -v, --version                  Output the current version
  --no-cache                     Disable cache, by default data will be cached for 30m after the first request
  -d, --debug                    Debug mode will not install dependencies
  -h --help                      Display help information for commands

Commands:
  init [options] [projectName]   Initializes a new project
  install [options]              Installs @heroui/react and @heroui/styles to your project
  upgrade [options]              Upgrades @heroui/react and @heroui/styles to the latest versions
  uninstall [options]            Uninstall @heroui/react and @heroui/styles from the project
  list [options]                 Lists installed HeroUI packages (@heroui/react, @heroui/styles)
  env [options]                  Displays debugging information for the local environment
  doctor [options]               Checks for issues in the project
  agents-md [options]            Downloads HeroUI documentation for AI coding agents
  help [command]                 Display help for command
```

### init

使用 `init` 命令初始化一个新的 HeroUI 项目。该命令会为你的项目完成必要的配置。

```bash
heroui init [options]
```

**选项：**

- `-t --template [string]` 新项目使用的模板，例如 app、pages、vite、react-router
- `-p --package [string]` 新项目使用的包管理器

输出：

```bash
HeroUI CLI <version>

┌  Create a new project
│
◇  Select a template (Enter to select)
│  ● App (A Next.js 16 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ Pages (A Next.js 16 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with HeroUI (v3) and Tailwind CSS.)
│  ○ React Router (A React Router template pre-configured with HeroUI (v3) and Tailwind CSS.)
│
◇  New project name (Enter to skip with default name)
│  my-heroui-app
│
◇  Select a package manager (Enter to select)
│  ● npm
│  ○ yarn
│  ○ pnpm
│  ○ bun
│
◇  Template created successfully!
│
◇  Next steps ───────╮
│                    │
│  cd my-heroui-app  │
│  npm install       │
│                    │
├────────────────────╯
│
└  🚀 Get started with npm run dev
```


安装依赖以启动本地服务器：


  

#### npm


    ```bash
    cd my-heroui-app && npm install
    ```
  
  

#### pnpm


    ```bash
    cd my-heroui-app && pnpm install
    ```
  
  

#### yarn


    ```bash
    cd my-heroui-app && yarn install
    ```
  
  

#### bun


    ```bash
    cd my-heroui-app && bun install
    ```
  


启动本地服务器：

```npm
npm run dev
```

### Install

将 `@heroui/react` 和 `@heroui/styles` 及其对等依赖安装到你的项目中。若它们已安装，则该命令不会执行任何操作。

```bash
heroui install [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径


**输出：**

```bash
HeroUI CLI <version>

📦 Packages to be installed:
╭─────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version        │   Status   │   Docs                 │
│─────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0          │   stable   │   https://heroui.com   │
│   @heroui/styles   │   3.0.0          │   stable   │   https://heroui.com   │
╰─────────────────────────────────────────────────────────────────────────────╯

╭─────────────── PeerDependencies ────────────────╮
│  react@18.3.1                      latest       │
│  react-dom@18.3.1                  latest       │
│  tailwindcss@4.2.2                 latest       │
╰─────────────────────────────────────────────────╯
? Proceed with installation? › - Use arrow-keys. Return to submit.
❯   Yes
    No

✅ @heroui/react and @heroui/styles installed successfully
```

### upgrade


将 `@heroui/react` 和 `@heroui/styles` 及其对等依赖升级到最新版本。

```bash
heroui upgrade [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径

**输出：**

```bash
HeroUI CLI <version>

╭──────────────────────────── Upgrade ────────────────────────────╮
│  @heroui/react               ^3.0.0  ->  ^3.1.0                │
│  @heroui/styles              ^3.0.0  ->  ^3.1.0                │
╰─────────────────────────────────────────────────────────────────╯

? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
❯   Yes
    No

✅ Upgrade complete. All packages are up to date.
```

### uninstall

从你的项目中卸载 `@heroui/react` 和 `@heroui/styles`。对等依赖不会被卸载。

```bash
heroui uninstall [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径

**输出：**

```bash
HeroUI CLI <version>

❗️ Packages slated for uninstallation:
╭──────────────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version   │   Status   │   Docs                               │
│──────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0     │   stable   │   https://heroui.com                 │
│   @heroui/styles   │   3.0.0     │   stable   │   https://heroui.com                 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
? Confirm uninstallation of these packages: › - Use arrow-keys. Return to submit.
❯   Yes
    No

✅ Successfully uninstalled: @heroui/react, @heroui/styles
```

### list

列出已安装的 HeroUI 包（`@heroui/react`、`@heroui/styles`）。

```bash
heroui list [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径

**输出：**

```bash
HeroUI CLI <version>

Current installed packages:

╭──────────────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version          │   Status   │   Docs                        │
│──────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

### doctor

检查项目中存在的问题。
- 检查 `@heroui/react` 和 `@heroui/styles` 是否已安装
- 检查项目中是否安装了所需的 `对等依赖` 并满足最低版本要求


```bash
heroui doctor [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径

**输出：**

如果项目中存在问题，`doctor` 命令将显示问题信息。

```bash
HeroUI CLI <version>

HeroUI CLI: ❌ Your project has 1 issue that require attention

❗️Issue 1: missingHeroUIPackages

The following HeroUI packages are not installed:
- @heroui/styles

Run `heroui install` to install them.
```

否则，`doctor` 命令将显示以下消息。

```bash
HeroUI CLI <version>

✅ Your project has no detected issues.
```

### env

显示本地环境的调试信息。

```bash
heroui env [options]
```

**选项：**

- `-p --packagePath` [string] package.json 文件的路径

**输出：**

```bash
HeroUI CLI <version>

Current installed packages:

╭──────────────────────────────────────────────────────────────────────────────────────╮
│   Package          │   Version          │   Status   │   Docs                        │
│──────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
╰──────────────────────────────────────────────────────────────────────────────────────╯

Environment Info:
  System:
    OS: darwin
    CPU: arm64
  Binaries:
    Node: v25.8.1
```

### agents-md

下载用于 AI 编程助手（Claude、Cursor 等）的 HeroUI 文档。该命令会从 HeroUI 仓库克隆最新文档，并将一份精简索引注入到 `AGENTS.md` 或 `CLAUDE.md` 中，方便助手参考你项目中的 HeroUI 配置。

```bash
heroui agents-md [options]
```

**选项：**

- `--react` [boolean] 仅包含 React 文档（一次只能选择一个文档库）
- `--native` [boolean] 仅包含 Native 文档
- `--migration` [boolean] 仅包含 HeroUI v2 到 v3 的迁移文档
- `--output <file>` [string] 目标文件路径（例如 `AGENTS.md`、`CLAUDE.md`）
- `--ssh` [boolean] 使用 SSH 而非 HTTPS 进行 git clone

**示例：**

不带任何标志运行以进入交互模式：

```bash
heroui agents-md
```

将 React 文档下载到指定文件：

```bash
heroui agents-md --react --output AGENTS.md
```

下载 Native 或迁移文档：

```bash
heroui agents-md --native --output CLAUDE.md
heroui agents-md --migration --output AGENTS.md
```

**工作原理：**

1. 使用 git sparse-checkout 从 `v3` 分支克隆文档
2. 生成文档和示例文件的精简索引
3. 将该索引注入到你的 markdown 文件中，置于标记之间（`<!-- HEROUI-REACT-AGENTS-MD-START -->` / `<!-- HEROUI-REACT-AGENTS-MD-END -->`，Native 和 Migration 也有类似的标记）
4. 将 `.heroui-docs/` 添加到 `.gitignore`

`--react`、`--native` 和 `--migration` 一次只能选择其中一个。

更多详情请参阅 [AGENTS.md](/systems/heroui/docs/getting-started/agents-md)。


> 
  `agents-md` 命令会收集匿名使用数据（所选项、输出文件名、耗时、成功或错误）。设置 `HEROUI_ANALYTICS_DISABLED=1` 可以选择不参与。


## 问题反馈

如果你发现了 bug，请在 [heroui-cli Issues](https://github.com/heroui-inc/heroui-cli/issues) 中报告。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt