命令行

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

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

安装

环境要求：

Node.js 22.22.0 或更高版本

全局安装

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

1npm install heroui-cli@latest -g

无需安装直接使用

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

1pnpm dlx heroui-cli@latest

快速开始

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

1heroui

将会输出如下帮助信息：

1Usage: heroui [command]2
3Options:4  -v, --version                  Output the current version5  --no-cache                     Disable cache, by default data will be cached for 30m after the first request6  -d, --debug                    Debug mode will not install dependencies7  -h --help                      Display help information for commands8
9Commands:10  init [options] [projectName]   Initializes a new project11  install [options]              Installs @lenso/ui and @lenso/tokens to your project12  upgrade [options]              Upgrades @lenso/ui and @lenso/tokens to the latest versions13  uninstall [options]            Uninstall @lenso/ui and @lenso/tokens from the project14  list [options]                 Lists installed HeroUI packages (@lenso/ui, @lenso/tokens)15  env [options]                  Displays debugging information for the local environment16  doctor [options]               Checks for issues in the project17  agents-md [options]            Downloads HeroUI documentation for AI coding agents18  help [command]                 Display help for command

init

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

1heroui init [options]

选项：

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

输出：

1HeroUI CLI <version>2
3┌  Create a new project4│5◇  Select a template (Enter to select)6│  ● App (A Next.js 16 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)7│  ○ Pages (A Next.js 16 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)8│  ○ Vite (A Vite template pre-configured with HeroUI (v3) and Tailwind CSS.)9│  ○ React Router (A React Router template pre-configured with HeroUI (v3) and Tailwind CSS.)10│11◇  New project name (Enter to skip with default name)12│  my-heroui-app13│14◇  Select a package manager (Enter to select)15│  ● npm16│  ○ yarn17│  ○ pnpm18│  ○ bun19│20◇  Template created successfully!21│22◇  Next steps ───────╮23│                    │24│  cd my-heroui-app  │25│  npm install       │26│                    │27├────────────────────╯28│29└  🚀 Get started with npm run dev

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

1cd my-heroui-app && npm install

启动本地服务器：

1npm run dev

Install

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

1heroui install [options]

选项：

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

输出：

1HeroUI CLI <version>2
3📦 Packages to be installed:4╭─────────────────────────────────────────────────────────────────────────────╮5│   Package          │   Version        │   Status   │   Docs                 │6│─────────────────────────────────────────────────────────────────────────────│7│   @lenso/ui    │   3.0.0          │   stable   │   https://heroui.com   │8│   @lenso/tokens   │   3.0.0          │   stable   │   https://heroui.com   │9╰─────────────────────────────────────────────────────────────────────────────╯10
11╭─────────────── PeerDependencies ────────────────╮12│  [email protected]                      latest       │13│  [email protected]                  latest       │14│  [email protected]                 latest       │15╰─────────────────────────────────────────────────╯16? Proceed with installation? › - Use arrow-keys. Return to submit.17❯   Yes18    No19
20✅ @lenso/ui and @lenso/tokens installed successfully

upgrade

将 @lenso/ui 和 @lenso/tokens 及其对等依赖升级到最新版本。

1heroui upgrade [options]

选项：

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

输出：

1HeroUI CLI <version>2
3╭──────────────────────────── Upgrade ────────────────────────────╮4│  @lenso/ui               ^3.0.0  ->  ^3.1.0                │5│  @lenso/tokens              ^3.0.0  ->  ^3.1.0                │6╰─────────────────────────────────────────────────────────────────╯7
8? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.9❯   Yes10    No11
12✅ Upgrade complete. All packages are up to date.

uninstall

从你的项目中卸载 @lenso/ui 和 @lenso/tokens。对等依赖不会被卸载。

1heroui uninstall [options]

选项：

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

输出：

1HeroUI CLI <version>2
3❗️ Packages slated for uninstallation:4╭──────────────────────────────────────────────────────────────────────────────────────╮5│   Package          │   Version   │   Status   │   Docs                               │6│──────────────────────────────────────────────────────────────────────────────────────│7│   @lenso/ui    │   3.0.0     │   stable   │   https://heroui.com                 │8│   @lenso/tokens   │   3.0.0     │   stable   │   https://heroui.com                 │9╰──────────────────────────────────────────────────────────────────────────────────────╯10? Confirm uninstallation of these packages: › - Use arrow-keys. Return to submit.11❯   Yes12    No13
14✅ Successfully uninstalled: @lenso/ui, @lenso/tokens

list

列出已安装的 HeroUI 包（@lenso/ui、@lenso/tokens）。

1heroui list [options]

选项：

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

输出：

1HeroUI CLI <version>2
3Current installed packages:4
5╭──────────────────────────────────────────────────────────────────────────────────────╮6│   Package          │   Version          │   Status   │   Docs                        │7│──────────────────────────────────────────────────────────────────────────────────────│8│   @lenso/ui    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │9│   @lenso/tokens   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │10╰──────────────────────────────────────────────────────────────────────────────────────╯

doctor

检查项目中存在的问题。

检查 @lenso/ui 和 @lenso/tokens 是否已安装
检查项目中是否安装了所需的 对等依赖 并满足最低版本要求

1heroui doctor [options]

选项：

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

输出：

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

1HeroUI CLI <version>2
3HeroUI CLI: ❌ Your project has 1 issue that require attention4
5❗️Issue 1: missingHeroUIPackages6
7The following HeroUI packages are not installed:8- @lenso/tokens9
10Run `heroui install` to install them.

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

1HeroUI CLI <version>2
3✅ Your project has no detected issues.

env

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

1heroui env [options]

选项：

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

输出：

1HeroUI CLI <version>2
3Current installed packages:4
5╭──────────────────────────────────────────────────────────────────────────────────────╮6│   Package          │   Version          │   Status   │   Docs                        │7│──────────────────────────────────────────────────────────────────────────────────────│8│   @lenso/ui    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │9│   @lenso/tokens   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │10╰──────────────────────────────────────────────────────────────────────────────────────╯11
12Environment Info:13  System:14    OS: darwin15    CPU: arm6416  Binaries:17    Node: v25.8.1

agents-md

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

1heroui 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

示例：

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

1heroui agents-md

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

1heroui agents-md --react --output AGENTS.md

下载 Native 或迁移文档：

1heroui agents-md --native --output CLAUDE.md2heroui agents-md --migration --output AGENTS.md

工作原理：

使用 git sparse-checkout 从 v3 分支克隆文档
生成文档和示例文件的精简索引
将该索引注入到你的 markdown 文件中，置于标记之间（ / ，Native 和 Migration 也有类似的标记）
将 .heroui-docs/ 添加到 .gitignore

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

更多详情请参阅 AGENTS.md。

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

问题反馈

如果你发现了 bug，请在 heroui-cli Issues 中报告。