# CLI · HeroUI > Use the CLI to manage HeroUI dependencies and initialize projects. - Page: https://jiguang132.com/systems/heroui/docs/getting-started/cli - Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to `install`, `uninstall`, or `upgrade` individual components, assess the health of your project, download documentation for AI coding agents, and more. ## Installation Requirements: - [Node.js version 22.22.0 or later](https://nodejs.org/en/) ### Global Installation To install `heroui-cli` globally, execute one of the following commands in your terminal: ```npm npm install heroui-cli@latest -g ``` ### Without Installation Alternatively, you can use `heroui-cli` without a global installation by running one of the following: #### 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 ``` ## Quick Start Once `heroui-cli` is installed, run the following command to display available commands: ```bash heroui ``` This will produce the following help output: ```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 Initialize a new HeroUI project using the `init` command. This sets up your project with the necessary configurations. ```bash heroui init [options] ``` **Options:** - `-t --template [string]` The template to use for the new project e.g. app, pages, vite, react-router - `-p --package [string]` The package manager to use for the new project output: ```bash HeroUI CLI ┌ 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 ``` Install the dependencies to start the local server: #### 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 ``` Start the local server: ```npm npm run dev ``` ### Install Install `@heroui/react` and `@heroui/styles` to your project, along with their peer dependencies. If they are already installed, the command does nothing. ```bash heroui install [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** ```bash HeroUI CLI 📦 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 Upgrade `@heroui/react` and `@heroui/styles` with their peer dependencies to the latest versions. ```bash heroui upgrade [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** ```bash HeroUI CLI ╭──────────────────────────── 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 Uninstall `@heroui/react` and `@heroui/styles` from your project. Peer dependencies will not be uninstalled. ```bash heroui uninstall [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** ```bash HeroUI CLI ❗️ 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 List the installed HeroUI packages (`@heroui/react`, `@heroui/styles`). ```bash heroui list [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** ```bash HeroUI CLI 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 Check for issues in your project. - Check whether `@heroui/react` and `@heroui/styles` are installed - Check whether `required peer dependencies` are installed and matched minimal requirements in the project ```bash heroui doctor [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** If there is a problem in your project, the `doctor` command will display the problem information. ```bash HeroUI CLI 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. ``` Otherwise, the `doctor` command will display the following message. ```bash HeroUI CLI ✅ Your project has no detected issues. ``` ### env Display debug information about the local environment. ```bash heroui env [options] ``` **Options:** - `-p --packagePath` [string] The path to the package.json file **Output:** ```bash HeroUI CLI 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 Download HeroUI documentation for AI coding agents (Claude, Cursor, etc.). The command clones the latest docs from the HeroUI repository and injects a compact index into `AGENTS.md` or `CLAUDE.md` so assistants can reference your project's HeroUI setup. ```bash heroui agents-md [options] ``` **Options:** - `--react` [boolean] Include React docs only (one library at a time) - `--native` [boolean] Include Native docs only - `--migration` [boolean] Include HeroUI v2 to v3 migration docs only - `--output ` [string] Target file path (e.g., `AGENTS.md`, `CLAUDE.md`) - `--ssh` [boolean] Use SSH instead of HTTPS for git clone **Examples:** Run without flags to enter interactive mode: ```bash heroui agents-md ``` Download React docs to a specific file: ```bash heroui agents-md --react --output AGENTS.md ``` Download Native or migration docs: ```bash heroui agents-md --native --output CLAUDE.md heroui agents-md --migration --output AGENTS.md ``` **How it works:** 1. Clones documentation from the `v3` branch using git sparse-checkout 2. Generates a compact index of doc and demo files 3. Injects the index into your markdown file between markers (`` / ``, and similar for Native and Migration) 4. Adds `.heroui-docs/` to `.gitignore` Only one of `--react`, `--native`, or `--migration` can be selected at a time. For more details, see [AGENTS.md](/systems/heroui/docs/getting-started/agents-md). > The `agents-md` command collects anonymous usage data (selection, output file names, duration, success or error). Set `HEROUI_ANALYTICS_DISABLED=1` to opt out. ## Reporting issues If you found a bug, please report it in [heroui-cli Issues](https://github.com/heroui-inc/heroui-cli/issues). --- Index of all JGuang resources: https://jiguang132.com/llms.txt