{"id":17015,"library":"heroui-cli","title":"HeroUI CLI","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/heroui-inc/heroui-cli","tags":["javascript","UI","CLI","Tool","NextUI","Template","Integration","Add Component","HeroUI","typescript"],"install":[{"cmd":"npm install heroui-cli","lang":"bash","label":"npm"},{"cmd":"yarn add heroui-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add heroui-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime environment for the CLI.","package":"node","optional":false},{"reason":"Specific version recommended for package management operations, though other managers like npm, yarn, and bun are also supported by the CLI.","package":"pnpm","optional":true}],"imports":[{"note":"Requires global installation (`npm install -g heroui-cli`) to use the `heroui` command directly.","wrong":"node heroui-cli init my-project","symbol":"heroui","correct":"heroui init my-project"},{"note":"The `@latest` tag ensures the most recent version is used without global installation. The CLI package name must be specified with `npx`.","wrong":"npx heroui init my-project","symbol":"npx heroui-cli","correct":"npx heroui-cli@latest init my-project"},{"note":"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.","symbol":"Types","correct":"import type { InitOptions } from 'heroui-cli';"}],"quickstart":{"code":"npm install -g heroui-cli\n\n# Initialize a new HeroUI project using the 'app' template\nheroui init my-heroui-app -t app\n\ncd my-heroui-app\n\n# Install project dependencies\nnpm install\n\n# Start the development server\nnpm run dev","lang":"bash","description":"Demonstrates global installation of the CLI, initializing a new HeroUI project with a Next.js App template, installing dependencies, and starting the development server."},"warnings":[{"fix":"Ensure your project is compatible with HeroUI v3 before upgrading heroui-cli to v3.x. Refer to HeroUI's official migration guides.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"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.","message":"The `heroui-cli` has strict Node.js engine requirements. Version 3.x requires Node.js 22.22.0 or later.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"To opt out of analytics collection, set the environment variable `HEROUI_ANALYTICS_DISABLED=1` in your shell profile or before running the command.","message":"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.","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"Always use `heroui-cli` when installing and `heroui` when executing commands. Update any scripts or documentation that refer to the old name.","message":"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.","severity":"deprecated","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install globally with `npm install -g heroui-cli` or `pnpm install -g heroui-cli`, or run it transiently using `npx heroui-cli@latest`.","cause":"The heroui-cli package is not installed globally or the `npx` prefix was omitted for transient execution.","error":"command not found: heroui"},{"fix":"Update your Node.js installation to version 22.22.0 or newer. Consider using `nvm` (Node Version Manager) for easy version management.","cause":"Your current Node.js version is older than the minimum requirement for heroui-cli v3.","error":"Error: The heroui-cli requires Node.js version 22.22.0 or higher."},{"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`.","cause":"The `init` command encountered an issue, possibly related to an outdated package manager (like pnpm < 10.x) or an invalid template name.","error":"The heroui-cli failed to initialize the project template. This might be due to an unsupported package manager version or template specific issues."}],"ecosystem":"npm","meta_description":null}