CLI

Use the CLI to manage HeroUI dependencies and initialize projects.

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

Global Installation

To install heroui-cli globally, execute one of the following commands in your terminal:

1npm install heroui-cli@latest -g

Without Installation

Alternatively, you can use heroui-cli without a global installation by running one of the following:

1pnpm dlx heroui-cli@latest

Quick Start

Once heroui-cli is installed, run the following command to display available commands:

1heroui

This will produce the following help output:

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

Initialize a new HeroUI project using the init command. This sets up your project with the necessary configurations.

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

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

Install the dependencies to start the local server:

1cd my-heroui-app && npm install

Start the local server:

1npm run dev

Install

Install @lenso/ui and @lenso/tokens to your project, along with their peer dependencies. If they are already installed, the command does nothing.

1heroui install [options]

Options:

-p --packagePath [string] The path to the package.json file

Output:

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

Upgrade @lenso/ui and @lenso/tokens with their peer dependencies to the latest versions.

1heroui upgrade [options]

Options:

-p --packagePath [string] The path to the package.json file

Output:

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

Uninstall @lenso/ui and @lenso/tokens from your project. Peer dependencies will not be uninstalled.

1heroui uninstall [options]

Options:

-p --packagePath [string] The path to the package.json file

Output:

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

List the installed HeroUI packages (@lenso/ui, @lenso/tokens).

1heroui list [options]

Options:

-p --packagePath [string] The path to the package.json file

Output:

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

Check for issues in your project.

Check whether @lenso/ui and @lenso/tokens are installed
Check whether required peer dependencies are installed and matched minimal requirements in the project

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

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.

Otherwise, the doctor command will display the following message.

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

env

Display debug information about the local environment.

1heroui env [options]

Options:

-p --packagePath [string] The path to the package.json file

Output:

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

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.

1heroui 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 <file> [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:

1heroui agents-md

Download React docs to a specific file:

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

Download Native or migration docs:

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

How it works:

Clones documentation from the v3 branch using git sparse-checkout
Generates a compact index of doc and demo files
Injects the index into your markdown file between markers ( / , and similar for Native and Migration)
Adds .heroui-docs/ to .gitignore

Only one of --react, --native, or --migration can be selected at a time.

For more details, see 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.