HeroUI CLI

3.0.0 · active · verified Wed Apr 22

heroui-cli is a command-line interface tool designed to streamline the integration and management of HeroUI components and templates into web projects. Previously known as NextUI CLI, it transitioned to HeroUI CLI to support the evolving HeroUI ecosystem. The current stable version is v3.0.0, which specifically targets and removes logic for HeroUI v2, ensuring compatibility with HeroUI v3. The CLI offers commands to initialize new projects from various templates (Next.js App/Pages, Vite, Remix, Laravel), add/remove/upgrade HeroUI packages, and perform project health checks (doctor, env). It also includes a unique feature for downloading HeroUI documentation for AI coding agents. The project maintains an active release cadence, frequently updating to support new features and versions of HeroUI and underlying frameworks. Key differentiators include its comprehensive set of project management commands tailored for HeroUI, and its support for a range of modern web project setups.

Common errors

```
command not found: heroui
```
cause The heroui-cli package is not installed globally or the `npx` prefix was omitted for transient execution.

fix Install globally with `npm install -g heroui-cli` or `pnpm install -g heroui-cli`, or run it transiently using `npx heroui-cli@latest`.
```
Error: The heroui-cli requires Node.js version 22.22.0 or higher.
```
cause Your current Node.js version is older than the minimum requirement for heroui-cli v3.

fix Update your Node.js installation to version 22.22.0 or newer. Consider using `nvm` (Node Version Manager) for easy version management.
```
The heroui-cli failed to initialize the project template. This might be due to an unsupported package manager version or template specific issues.
```
cause The `init` command encountered an issue, possibly related to an outdated package manager (like pnpm < 10.x) or an invalid template name.

fix Ensure your package manager meets the minimum version requirements (e.g., pnpm >=10.x). Verify the template name with `heroui init --help` or the official documentation. You can specify a package manager using `-p` flag: `heroui init my-app -t app -p npm`.

Warnings

breaking Version 3.0.0 of heroui-cli removes all logic related to HeroUI v2 and is exclusively designed to support HeroUI v3. Projects using older versions of HeroUI will require careful migration and potentially the use of an older heroui-cli version.
Fix: Ensure your project is compatible with HeroUI v3 before upgrading heroui-cli to v3.x. Refer to HeroUI's official migration guides.
breaking Version 2.0.0 of heroui-cli introduced breaking changes to align with HeroUI v2. Using heroui-cli v2 with HeroUI v1 projects will lead to incompatibilities.
Fix: For HeroUI v1 projects, stick to heroui-cli v1.x. For HeroUI v2 projects, use heroui-cli v2.x. For HeroUI v3, use heroui-cli v3.x.
gotcha The `heroui-cli` has strict Node.js engine requirements. Version 3.x requires Node.js 22.22.0 or later.
Fix: Upgrade your Node.js installation to version 22.22.0 or higher. Use a version manager like `nvm` to easily switch Node.js versions.
gotcha The `agents-md` command collects anonymous usage data, including selection, output file names, duration, and success/error status. No file paths or project contents are collected.
Fix: To opt out of analytics collection, set the environment variable `HEROUI_ANALYTICS_DISABLED=1` in your shell profile or before running the command.
deprecated The CLI was previously known as 'NextUI CLI' and has been renamed to 'HeroUI CLI'. Older commands or references to 'nextui-cli' may no longer function or refer to outdated versions.
Fix: Always use `heroui-cli` when installing and `heroui` when executing commands. Update any scripts or documentation that refer to the old name.

Install

npm install heroui-cli npm
yarn add heroui-cli yarn
pnpm add heroui-cli pnpm

Imports

heroui
wrong:
```
node heroui-cli init my-project
```
correct:
```
heroui init my-project
```
Requires global installation (`npm install -g heroui-cli`) to use the `heroui` command directly.
npx heroui-cli
wrong:
```
npx heroui init my-project
```
correct:
```
npx heroui-cli@latest init my-project
```
The `@latest` tag ensures the most recent version is used without global installation. The CLI package name must be specified with `npx`.
Types
```
import type { InitOptions } from 'heroui-cli';
```
While heroui-cli ships with TypeScript types, it is primarily a CLI tool; direct programmatic import of its internal modules or types is uncommon for end-user applications.

Quickstart

Demonstrates global installation of the CLI, initializing a new HeroUI project with a Next.js App template, installing dependencies, and starting the development server.

npm install -g heroui-cli

# Initialize a new HeroUI project using the 'app' template
heroui init my-heroui-app -t app

cd my-heroui-app

# Install project dependencies
npm install

# Start the development server
npm run dev

view raw JSON →