The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to add, remove, or upgrade individual components, assess the health of your project, and more.
Note: The HeroUI CLI requires Node.js 20.19.x+ or later
You can choose the following ways to start the HeroUI CLI.
npx heroui-cli@latestnpm install -g heroui-cliUsage: 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] [targets...] 1. Adds components to your project
2. Adds HeroUI Chat codebase to your project
upgrade [options] [components...] Upgrades project components to the latest versions
remove [options] [components...] Removes components from the project
list [options] Lists all components, showing status, descriptions, and versions
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 commandThe 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 appoutput:
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 (v2) and Tailwind CSS.)
│ ○ Pages (A Next.js 15 with pages directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│ ○ Vite (A Vite template pre-configured with HeroUI (v2) and Tailwind CSS.)
│ ○ Remix (A Remix template pre-configured with HeroUI (v2) and Tailwind CSS.)
│ ○ Laravel (A Laravel template pre-configured with HeroUI (v2) 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 components to your project.
- Add HeroUI Chat codebase to your project.
- Auto add the missing required
dependenciesto your project- Detect whether using pnpm, if so, add the required configuration to your
.npmrcfile- Add HeroUI Chat codebase to your project
heroui add [targets...] [options]-a --all[boolean] Add all components (default:false)-p --packagePath[string] The path to the package.json file--tw --tailwindPath[string] The path to the tailwind.config file (for backward compatibility)--app --appPath[string] The path to the App.tsx file--prettier[boolean] Add prettier format in the add content which required installed prettier - (default:false)--addApp[boolean] Add App.tsx file content which required provider (default:false)-b --beta[boolean] Add beta components (default:false)-d --directory[string] Add HeroUI Chat codebase to a specific directory
Without setting a specific component, the add command will show a list of available components.
heroui addOutput:
HeroUI CLI <version>
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
↑/↓: Highlight option
←/→/[space]: Toggle selection
[a,b,c]/delete: Filter choices
enter/return: Complete answer
Filtered results for: Enter something to filter
◉ accordion
◯ autocomplete
◯ avatar
◯ badge
◯ breadcrumbs
◯ button
◯ card
◯ checkbox
◯ chip
◯ codeIf you want to add a specific component, you can specify the component name.
heroui add buttonOutput:
HeroUI CLI <version>
Adding the required dependencies: @heroui/button
pnpm add @heroui/button
Packages: +1
+
Progress: resolved 470, reused 462, downloaded 0, added 0, done
dependencies:
+ @heroui/button 2.0.24
Done in 3.4s
Tailwind CSS settings have been updated in: /project-path/tailwind.config.js
✅ Components added successfullyUpgrade the HeroUI components to the latest version.
heroui upgrade [components...] [options]-p --packagePath[string] The path to the package.json file-a --all[boolean] Upgrade all the HeroUI components (default:false)-w --write[boolean] Write the upgrade version to package.json file (default:false)-b --beta[boolean] Upgrade beta components (default:false)-h --helpDisplay help for command
Upgrade the Button component to the latest version.
heroui upgrade buttonOutput:
HeroUI CLI <version>
╭───────────────────────── Component ─────────────────────────╮
│ @heroui/button ^2.0.11 -> ^2.0.31 │
╰─────────────────────────────────────────────────────────────╯
Required min version: @heroui/theme>=2.1.0, tailwindcss>=3.4.0, react>=18.3.1, react-dom>=18.3.1
╭───────────────────── PeerDependencies ─────────────────────╮
│ @heroui/theme 2.0.1 -> 2.1.0 │
│ tailwindcss ^3.2.3 -> ^3.4.0 │
│ react Missing -> 18.3.1 │
│ react-dom Missing -> 18.3.1 │
╰────────────────────────────────────────────────────────────╯
2 major, 2 minor, 1 patch
? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
❯ Yes
No
pnpm add @heroui/button@2.0.31 @heroui/theme@2.1.0 tailwindcss@3.4.0 react@18.3.1 react-dom@18.3.1
dependencies:
- @heroui/theme 2.0.1
+ @heroui/theme 2.1.0 (2.2.3 is available)
+ react 18.3.1
+ react-dom 18.3.1
Done in 1.8s
✅ Upgrade complete. All components are up to date.Remove HeroUI components from your project.
Note: If there are no HeroUI components after removing, the required content will also be removed
heroui remove [components...] [options]-p --packagePath[string] The path to the package.json file-a --all[boolean] Remove all the HeroUI components (default:false)--tw --tailwindPath[string] The path to the tailwind.config file (for backward compatibility)--prettier[boolean] Add prettier format in the add content which required installed prettier - (default:false)
Remove the Button component from your project.
heroui remove buttonOutput:
HeroUI CLI <version>
❗️ Components slated for removal:
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│──────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @heroui/button │ 2.0.27 🚀latest │ stable │ https://heroui.com/docs/components/button │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
? Confirm removal of these components: › - Use arrow-keys. Return to submit.
❯ Yes
No
pnpm remove @heroui/button
Already up to date
Progress: resolved 474, reused 465, downloaded 0, added 0, done
dependencies:
- @heroui/button 2.0.27
Done in 2.1s
Remove the removed components tailwind content in file:/project-path/tailwind.config.js
✅ Successfully removed the specified HeroUI components: @heroui/buttonList all the current installed components.
heroui list [options]-p --packagePath[string] The path to the package.json file-r --remoteList all components available remotely
heroui listOutput:
HeroUI CLI <version>
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @heroui/autocomplete │ 2.0.10 🚀latest │ stable │ https://heroui.com/docs/components/autocomplete │
│ @heroui/badge │ 2.0.24 🚀latest │ stable │ https://heroui.com/docs/components/badge │
│ @heroui/button │ 2.0.27 🚀latest │ stable │ https://heroui.com/docs/components/button │
│ @heroui/chip │ 2.0.25 🚀latest │ stable │ https://heroui.com/docs/components/chip │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯Check whether exist problem in your project by using the doctor command.
heroui doctor [options]
- Check whether have
redundant dependenciesin the project- Check whether the HeroUI components
required dependencies are installedin the project- Check the content of
tailwind.config.jsis correct (if it exists)- Check
.npmrcis correct when usingpnpm- Check
peerDependencies with required versionare installed in the project
-p--packagePath[string] The path to the package.json file--tw--tailwindPath[string] The path to the tailwind.config file (for backward compatibility)--app--appPath[string] The path to the App.tsx file--ca--checkApp[boolean] Open check App (default:true)--ct--checkTailwind[boolean] Open check tailwind.config file (default:trueif it exists)--cp--checkPnpm[boolean] Open check Pnpm (default:true)
heroui doctorOutput:
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: missingDependencies
You have not installed the required dependencies
The required dependencies are:
- @heroui/theme@2.4.25
See more info here: https://heroui.com/docs/guide/installation#global-installationOtherwise, 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 file
Display the local environment Information by using the env command.
heroui envOutput:
HeroUI CLI <version>
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @heroui/autocomplete │ 2.0.10 🚀latest │ stable │ https://heroui.com/docs/components/autocomplete │
│ @heroui/badge │ 2.0.24 🚀latest │ stable │ https://heroui.com/docs/components/badge │
│ @heroui/button │ 2.0.27 🚀latest │ stable │ https://heroui.com/docs/components/button │
│ @heroui/chip │ 2.0.25 🚀latest │ stable │ https://heroui.com/docs/components/chip │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Environment Info:
System:
OS: darwin
CPU: arm64
Binaries:
Node: v18.18.2Download 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 clone
Run the command without any flags to enter interactive mode:
heroui agents-mdDownload React docs to a specific file:
heroui agents-md --react --output AGENTS.mdDownload Native docs:
heroui agents-md --native --output CLAUDE.mdDownload migration docs (v2→v3):
heroui agents-md --migration --output AGENTS.mdUse SSH for cloning (useful if HTTPS fails):
heroui agents-md --react --ssh --output AGENTS.md- Downloads Documentation: Clones the HeroUI repository using git sparse-checkout to download only the documentation files
- Generates Index: Creates a compact index of all documentation files organized by directory
- Injects into Markdown: Injects the index into your specified markdown file (e.g.,
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 docs
- Single library: Only one of React, Native, or Migration can be selected at a time
After 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/
- The command always downloads the latest documentation from the
v3branch - Documentation is stored in
.heroui-docs/which is automatically added to.gitignore
Visit https://heroui.com/docs/guide/cli to view the full documentation.
We'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.