heroui-cli

library3.0.0jsnpmunverified

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.

devops

npm install heroui-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HEROUI-CLI

heroui-cli

devopsjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

heroui

✓ heroui init my-project

✗ node heroui-cli init my-project

Requires global installation (`npm install -g heroui-cli`) to use the `heroui` command directly.

npx heroui-cli

✓ npx heroui-cli@latest init my-project

✗ npx heroui 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.

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

heroui --version

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingVersion 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.

affects: >=2.0.0 <3.0.0

gotchaThe `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.

affects: >=3.0.0

gotchaThe `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.

affects: >=1.5.0

deprecatedThe 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.

affects: <3.0.0

Errors

Common errors & fixes

command not found: heroui

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.

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.

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`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

noderequiredRequired runtime environment for the CLI.

pnpmoptionalSpecific version recommended for package management operations, though other managers like npm, yarn, and bun are also supported by the CLI.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/heroui-inc/heroui-cli ↗

packagehttps://www.npmjs.com/package/heroui-cli ↗

homepagehttps://heroui.com ↗