heroui-cli
Advanced tools
A CLI tool that unlocks seamless HeroUI integration (Previously NextUI CLI)
The CLI offers a suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to add, remove, or upgrade HeroUI packages, assess the health of your project, and more.
Note: The HeroUI CLI requires Node.js 22+ or later
You can choose the following ways to start the HeroUI CLI.
npx heroui-cli@latest
npm install -g heroui-cli
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
add [options] Adds @heroui/react and @heroui/styles to your project
upgrade [options] Upgrades @heroui/react and @heroui/styles to the latest versions
remove [options] Removes @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
The agents-md command collects anonymous usage data.
What we collect: Selection (react/native/both), output file names, duration, success or error. No file paths, or project contents are collected.
Opt out: Set HEROUI_ANALYTICS_DISABLED=1 in your environment or shell profile.
Initialize a new HeroUI project with official templates.
heroui init [projectName] [options]
-t --template [string] The template to use for the new project e.g. app, laravel, pages, remix, vite-p --package [string] The package manager to use for the new project (default: npm)# Initialize a new HeroUI project with the app template, named my-heroui-app
heroui init my-heroui-app -t app
output:
HeroUI CLI <version>
┌ Create a new project
│
◇ Select a template (Enter to select)
│ ● App (A Next.js 15 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│ ○ Pages (A Next.js 15 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
│ ○ Vite (A Vite 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
Add @heroui/react and @heroui/styles to your project, along with their peer dependencies. If they are already installed, the command does nothing.
heroui add [options]
-p --packagePath [string] The path to the package.json fileheroui add
Output:
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 added successfully
Upgrade @heroui/react and @heroui/styles with their peer dependencies to the latest versions.
heroui upgrade [options]
-p --packagePath [string] The path to the package.json fileheroui upgrade
Output:
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.
Remove @heroui/react and @heroui/styles from your project. Peer dependencies will not be deleted.
heroui remove [options]
-p --packagePath [string] The path to the package.json fileheroui remove
Output:
HeroUI CLI <version>
❗️ Packages slated for removal:
╭──────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│──────────────────────────────────────────────────────────────────────────────────────│
│ @heroui/react │ 3.0.0 │ stable │ https://heroui.com │
│ @heroui/styles │ 3.0.0 │ stable │ https://heroui.com │
╰──────────────────────────────────────────────────────────────────────────────────────╯
? Confirm removal of these packages: › - Use arrow-keys. Return to submit.
❯ Yes
No
✅ Successfully removed: @heroui/react, @heroui/styles
List the installed HeroUI packages (@heroui/react, @heroui/styles).
heroui list [options]
-p --packagePath [string] The path to the package.json fileheroui list
Output:
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 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
Check for issues in your project.
heroui doctor [options]
- Check whether
@heroui/reactand@heroui/stylesare installed- Check whether
required peer dependenciesare installed and matched minimal requirements in the project
-p --packagePath [string] The path to the package.json fileheroui doctor
Output:
If there is a problem in your project, the doctor command will display the problem information.
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 add` to install them.
Otherwise, the doctor command will display the following message.
HeroUI CLI <version>
✅ Your project has no detected issues.
Display debug information about the local environment.
heroui env [options]
-p --packagePath [string] The path to the package.json fileheroui env
Output:
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
Download HeroUI documentation for AI coding agents (Claude, Cursor, etc.). This command downloads the latest documentation from the HeroUI repository and generates an index file that can be injected into markdown files like AGENTS.md or CLAUDE.md to help AI assistants understand your project's HeroUI setup.
heroui agents-md [options]
- Downloads latest HeroUI documentation from the
v3branch- Supports React, Native, and Migration (v2→v3) documentation
- Generates a section for the selected library (React, Native, or Migration) in the markdown file
- Automatically adds
.heroui-docs/to.gitignore
--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 cloneRun the command without any flags to enter interactive mode:
heroui agents-md
Download React docs to a specific file:
heroui agents-md --react --output AGENTS.md
Download Native docs:
heroui agents-md --native --output CLAUDE.md
Download migration docs (v2→v3):
heroui agents-md --migration --output AGENTS.md
Use SSH for cloning (useful if HTTPS fails):
heroui agents-md --react --ssh --output AGENTS.md
AGENTS.md) with special markers:
<!-- HEROUI-REACT-AGENTS-MD-START --> / <!-- HEROUI-REACT-AGENTS-MD-END --> for React docs<!-- HEROUI-NATIVE-AGENTS-MD-START --> / <!-- HEROUI-NATIVE-AGENTS-MD-END --> for Native docs<!-- HEROUI-MIGRATION-AGENTS-MD-START --> / <!-- HEROUI-MIGRATION-AGENTS-MD-END --> for Migration docsAfter running the command, you'll have:
your-project/
├── .heroui-docs/ # Downloaded documentation (gitignored)
│ ├── react/ # React documentation files (if selected)
│ ├── native/ # Native documentation files (if selected)
│ └── migration/ # Migration docs (v2→v3, if selected)
├── AGENTS.md # Your markdown file with injected index
└── .gitignore # Updated to include .heroui-docs/
v3 branch.heroui-docs/ which is automatically added to .gitignoreWe're excited to see the community adopt HeroUI CLI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!
Contributions are always welcome!
See CONTRIBUTING.md for ways to get started.
Please adhere to this project's CODE_OF_CONDUCT.
FAQs
A CLI tool that unlocks seamless HeroUI integration (Previously NextUI CLI)
We found that heroui-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Compromised intercom-client@7.0.4 npm package is tied to the ongoing Mini Shai-Hulud worm attack targeting developer and CI/CD secrets.
Research
Socket detected a malicious supply chain attack on PyPI package lightning versions 2.6.2 and 2.6.3, which execute credential-stealing malware on import.
Research
A brand-squatted TanStack npm package used postinstall scripts to steal .env files and exfiltrate developer secrets to an attacker-controlled endpoint.