NextUI CLI


Here's the API reference for the NextUI CLI.

Once the CLI is installed, run the following command to display available commands:

To get a list of the available CLI commands, run the following command inside your project directory:

nextui -h

This will produce the following help output:

NextUI CLI <version>
A command line tool for seamless integration with NextUI
Usage: nextui [command]
Options:
-v, --version Show the version number
--no-cache Disable cache, by default data will be cached for 30m after the first request
-h, --help Display help for commands
Commands:
init [options] [projectName] Start a new NextUI project
add [options] [components...] Add NextUI components to your project
upgrade [options] [components...] Update NextUI components to the latest versions
remove [options] [components...] Remove NextUI components from your project
list [options] Show details of installed components
env [options] Display debug information about the local environment
doctor [options] Diagnose problems in your project
help [command] Get help on a specific command

init

To start a new project, use the init command:

nextui init [projectName] [options]

Options

  • -t --template [string] The template to use for the new project e.g. app, pages
  • -p --package [string] The package manager to use for the new project (default: npm)

Example

nextui init my-nextui-app -t app

output:

NextUI CLI v0.2.1
┌ Create a new project
◇ Select a template (Enter to select)
│ ● App (A Next.js 14 with app directory template pre-configured with NextUI (v2) and Tailwind CSS.)
│ ○ Pages (A Next.js 14 with pages directory template pre-configured with NextUI (v2) and Tailwind CSS.)
│ ○ Vite (A Vite template pre-configured with NextUI (v2) and Tailwind CSS.)
◇ New project name (Enter to skip with default name)
│ my-nextui-app
◇ Select a package manager (Enter to select)
│ ● npm
│ ○ yarn
│ ○ pnpm
│ ○ bun
◇ Template created successfully!
◇ Next steps ───────╮
│ │
cd my-nextui-app │
npm install
│ │
├────────────────────╯
└ 🚀 Get started with npm run dev

add

  1. Auto add the missing required dependencies to your project
  2. Auto add the required tailwindcss.config.js configuration to your project
  3. Detect whether using pnpm, if so, add the required configuration to your .npmrc file

To add components to your project, use the add command:

nextui add [components...] [options]

Options

  • -a --all [boolean] Add all the NextUI components (default: false)
  • -p --packagePath [string] The path to the package.json file
  • -tw --tailwindPath [string] The path to the tailwind.config file file
  • -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)

Example

Without setting a specific component, the add command will show a list of available components.

nextui add

Output:

NextUI CLI v0.2.1
? Which components would you like to add? › - Space to select. Return to submit
Filtered results for: Enter something to filter
◯ accordion
◯ autocomplete
◯ avatar
◯ badge
◯ breadcrumbs
◯ button
◯ calendar
◯ card
◯ checkbox
◯ ↓ chip

If you want to add a specific component, you can specify the component name.

nextui add button input

Output:

NextUI CLI v0.2.1
Adding the required dependencies: @nextui-org/button
pnpm add @nextui-org/button
Packages: +1
+
Progress: resolved 470, reused 462, downloaded 0, added 0, done
dependencies:
+ @nextui-org/button 2.0.24
Done in 3.4s
Tailwind CSS settings have been updated in: /project-path/tailwind.config.js
✅ Components added successfully

upgrade

Upgrade the NextUI components to the latest version.

nextui upgrade [components...] [options]

Options

  • -p --packagePath [string] The path to the package.json file.
  • -a --all [boolean] Upgrade all the NextUI components (default: false).
  • -h, --help Display help for commands.

Example

nextui upgrade button

Output:

NextUI CLI v0.2.1
╭───────────────────────── Component ─────────────────────────╮
│ @nextui-org/button ^2.0.11 -> ^2.0.31 │
╰─────────────────────────────────────────────────────────────╯
Required min version: @nextui-org/theme>=2.1.0, tailwindcss>=3.4.0
╭───────────────────── PeerDependencies ─────────────────────╮
│ @nextui-org/theme 2.0.1 -> 2.1.0 │
│ tailwindcss ^3.2.3 -> ^3.4.0 │
╰────────────────────────────────────────────────────────────╯
2 minor, 1 patch
? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
❯ Yes
No
pnpm add @nextui-org/button@2.0.31 @nextui-org/theme@2.1.0 tailwindcss@3.4.0
Already up to date
Progress: resolved 474, reused 465, downloaded 0, added 0, done
Done in 2.9s
✅ Upgrade complete. All components are up to date.

remove

Remove NextUI components from your project.

Note: If there are no NextUI components after removing, the required content will also be removed._createMdxContent

nextui remove [components...] [options]

Options

  • -p --packagePath [string] The path to the package.json file.
  • -a --all [boolean] Remove all the NextUI components (default: false).
  • -tw --tailwindPath [string] The path to the tailwind.config file file.
  • --prettier [boolean] Add prettier format in the add content which required installed prettier - (default: false).

Example

nextui remove button

Output:

NextUI CLI v0.2.1
❗️ Components slated for removal:
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│──────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @nextui-org/button │ 2.0.27 🚀latest │ stable │ https://nextui.org/docs/components/button │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
? Confirm removal of these components: › - Use arrow-keys. Return to submit.
❯ Yes
No
pnpm remove @nextui-org/button
Already up to date
Progress: resolved 474, reused 465, downloaded 0, added 0, done
dependencies:
- @nextui-org/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 NextUI components: @nextui-org/button

list

Show details of installed components.

nextui list [options]

Options

  • -p --packagePath [string] The path to the package.json file
  • -r --remote List all components available remotely

Example

nextui list

Output:

NextUI CLI v0.2.1
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @nextui-org/autocomplete │ 2.0.10 🚀latest │ newPost │ https://nextui.org/docs/components/autocomplete │
│ @nextui-org/badge │ 2.0.24 🚀latest │ stable │ https://nextui.org/docs/components/badge │
│ @nextui-org/button │ 2.0.27 🚀latest │ stable │ https://nextui.org/docs/components/button │
│ @nextui-org/chip │ 2.0.25 🚀latest │ stable │ https://nextui.org/docs/components/chip │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

doctor

Diagnose problems in your project.

  1. Check whether have redundant dependencies in the project
  2. Check whether the NextUI components required dependencies are installed in the project
  3. Check the required tailwind.config.js file and the content is correct
  4. Check .npmrc is correct when using pnpm
  5. Check peerDependencies with required version are installed in the project
nextui doctor [options]

Options

  • -p --packagePath [string] The path to the package.json file
  • -tw --tailwindPath [string] The path to the tailwind.config file file
  • -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: true)
  • -cp --checkPnpm [boolean] Open check Pnpm (default: true)

Example

nextui doctor

Output:

If there is a problem in your project, the doctor command will display the problem information.

NextUI CLI v0.2.1
NextUI CLI: ❌ Your project has 1 issue that require attention
❗️Issue 1: missingTailwind
Missing tailwind.config.(j|t)s file. To set up, visit: https://nextui.org/docs/guide/installation#tailwind-css-setup

Otherwise, the doctor command will display the following message.

NextUI CLI v0.2.1
✅ Your project has no detected issues.

env

Display debug information about the local environment.

nextui env [options]

Options

  • -p --packagePath [string] The path to the package.json file

Example

nextui env

Output:

NextUI CLI 0.2.1
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @nextui-org/autocomplete │ 2.0.10 🚀latest │ newPost │ https://nextui.org/docs/components/autocomplete │
│ @nextui-org/badge │ 2.0.24 🚀latest │ stable │ https://nextui.org/docs/components/badge │
│ @nextui-org/button │ 2.0.27 🚀latest │ stable │ https://nextui.org/docs/components/button │
│ @nextui-org/chip │ 2.0.25 🚀latest │ stable │ https://nextui.org/docs/components/chip │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Environment Info:
System:
OS: darwin
CPU: arm64
Binaries:
Node: v18.18.2