https://github.com/heroui-inc/heroui-cli
⌨️ A CLI tool that unlocks seamless HeroUI integration.
https://github.com/heroui-inc/heroui-cli
cli design heroui
Last synced: 15 days ago
JSON representation
⌨️ A CLI tool that unlocks seamless HeroUI integration.
- Host: GitHub
- URL: https://github.com/heroui-inc/heroui-cli
- Owner: heroui-inc
- License: mit
- Created: 2023-09-23T17:50:16.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-06-06T03:02:22.000Z (15 days ago)
- Last Synced: 2026-06-06T04:22:30.368Z (15 days ago)
- Topics: cli, design, heroui
- Language: TypeScript
- Homepage: https://heroui.com/docs/guide/cli
- Size: 1.36 MB
- Stars: 90
- Watchers: 2
- Forks: 30
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: license
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
The CLI offers a suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to `install`, `uninstall`, or `upgrade` HeroUI packages, assess the health of your project, and more.
## Quick Start
> **Note**: The HeroUI CLI requires [Node.js](https://nodejs.org/en) _22+_ or later
You can choose the following ways to start the HeroUI CLI.
### Npx
```bash
npx heroui-cli@latest
```
### Global Installation
```bash
npm install -g heroui-cli
```
## Usage
```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 in your project
upgrade [options] Upgrades @heroui/react and @heroui/styles to the latest versions
uninstall [options] Uninstalls @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
```
## Analytics
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.
## Commands
### Init
Initialize a new HeroUI project with official templates.
```bash
heroui init [projectName] [options]
```
#### Init Options
- `-t --template [string]` The template to use for the new project e.g. app, pages, vite
- `-p --package [string]` The package manager to use for the new project
##### Example
```bash
# Initialize a new HeroUI project with the app template, named my-heroui-app using pnpm
heroui init my-heroui-app -t app -p pnpm
```
Alternatively, you can run `init` without any flags and select an option from the prompt.
```bash
heroui init
```
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.)
│
◇ 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
Install `@heroui/react` and `@heroui/styles` in your project, along with their peer dependencies. If they are already installed, the command does nothing.
```bash
heroui install [options]
```
#### Install Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui install
```
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]
```
#### Upgrade Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui upgrade
```
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 deleted.
```bash
heroui uninstall [options]
```
#### Uninstall Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui uninstall
```
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]
```
#### List Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui list
```
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.
```bash
heroui doctor [options]
```
#### Features
> 1. Check whether `@heroui/react` and `@heroui/styles` are installed
> 2. Check whether `required peer dependencies` are installed and matched minimal requirements in the project
#### Doctor Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui doctor
```
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]
```
#### Env Options
- `-p --packagePath` [string] The path to the package.json file
##### Example
```bash
heroui env
```
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.). 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.
```bash
heroui agents-md [options]
```
#### Features
> 1. Downloads latest HeroUI documentation from the `v3` branch
> 2. Supports React, Native, and Migration (v2→v3) documentation
> 3. Generates a section for the selected library (React, Native, or Migration) in the markdown file
> 4. Automatically adds `.heroui-docs/` to `.gitignore`
#### Agents-md 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
#### Example
Run the command without any 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 docs:
```bash
heroui agents-md --native --output CLAUDE.md
```
Download migration docs (v2→v3):
```bash
heroui agents-md --migration --output AGENTS.md
```
Use SSH for cloning (useful if HTTPS fails):
```bash
heroui agents-md --react --ssh --output AGENTS.md
```
#### How It Works
1. **Downloads Documentation**: Clones the HeroUI repository using git sparse-checkout to download only the documentation files
2. **Generates Index**: Creates a compact index of all documentation files organized by directory
3. **Injects into Markdown**: Injects the index into your specified markdown file (e.g., `AGENTS.md`) with special markers:
- `` / `` for React docs
- `` / `` for Native docs
- `` / `` for Migration docs
4. **Single library**: Only one of React, Native, or Migration can be selected at a time
#### File Structure
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/
```
#### Notes
- The command always downloads the latest documentation from the `v3` branch
- Documentation is stored in `.heroui-docs/` which is automatically added to `.gitignore`
### Community
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!
- [Discord](https://discord.gg/9b6yyZKmH4)
- [Twitter](https://twitter.com/hero_ui)
- [GitHub Discussions](https://github.com/heroui-inc/heroui-cli/discussions)
## Contributing
Contributions are always welcome!
See [CONTRIBUTING.md](https://github.com/heroui-inc/heroui-cli/blob/main/CONTRIBUTING.md) for ways to get started.
Please adhere to this project's [CODE_OF_CONDUCT](https://github.com/heroui-inc/heroui-cli/blob/main/CODE_OF_CONDUCT.md).
## License
[MIT](https://choosealicense.com/licenses/mit/)
