The CLI offers a comprehensive suite of commands to initialize, manage, and improve your NextUI projects. It enables you to add
, remove
, or upgrade
individual components, assess the health of your project, and more.
Note: The NextUI CLI requires Node.js 18.17.x+ or later
You can choose the following ways to start the NextUI CLI.
npx nextui-cli@latest
npm install -g nextui-cli
Usage: nextui [command]
Options:
-v, --version Output the current version
--no-cache Disable cache, by default data will be cached for 30m after the first request
-h --help Display help information for commands
Commands:
init [options] [projectName] Initializes a new project
add [options] [components...] Adds components to your project
upgrade [options] [components...] Upgrades project components to the latest versions
remove [options] [components...] Removes components from the project
list [options] Lists all components, showing status, descriptions, and versions
env [options] Displays debugging information for the local environment
doctor [options] Checks for issues in the project
help [command] Display help for command
Initialize a new NextUI project with official templates.
nextui init [projectName] [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 (default: npm
)# Initialize a new NextUI project with the app template, named my-nextui-app
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 NextUI components to your project.
- Auto add the missing required
dependencies
to your project- Auto add the required
tailwindcss.config.js
configuration to your project- Detect whether using pnpm, if so, add the required configuration to your
.npmrc
file
nextui add [components...] [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
)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
Instructions:
↑/↓: Highlight option
←/→/[space]: Toggle selection
[a,b,c]/delete: Filter choices
enter/return: Complete answer
Filtered results for: Enter something to filter
◉ accordion
◯ autocomplete
◯ avatar
◯ badge
◯ breadcrumbs
◯ button
◯ card
◯ checkbox
◯ chip
◯ code
If you want to add a specific component, you can specify the component name.
nextui add button
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 the NextUI components to the latest version.
nextui upgrade [components...] [options]
-p --packagePath
[string] The path to the package.json file-a --all
[boolean] Upgrade all the NextUI components (default: false
)-w --write
[boolean] Write the upgrade version to package.json file (default: false
)-h --help
Display help for commandUpgrade the Button component to the latest version.
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, react>=18.3.1, react-dom>=18.3.1
╭───────────────────── PeerDependencies ─────────────────────╮
│ @nextui-org/theme 2.0.1 -> 2.1.0 │
│ tailwindcss ^3.2.3 -> ^3.4.0 │
│ react Missing -> 18.3.1 │
│ react-dom Missing -> 18.3.1 │
╰────────────────────────────────────────────────────────────╯
2 major, 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 react@18.3.1 react-dom@18.3.1
dependencies:
- @nextui-org/theme 2.0.1
+ @nextui-org/theme 2.1.0 (2.2.3 is available)
+ react 18.3.1
+ react-dom 18.3.1
Done in 1.8s
✅ Upgrade complete. All components are up to date.
Remove NextUI components from your project.
Note: If there are no NextUI components after removing, the required content will also be removed
nextui remove [components...] [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
)Remove the Button component from your project.
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 all the current installed components.
nextui list [options]
-p --packagePath
[string] The path to the package.json file-r --remote
List all components available remotelynextui list
Output:
NextUI CLI v0.2.1
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @nextui-org/autocomplete │ 2.0.10 🚀latest │ stable │ 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 │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Check whether exist problem in your project by using the doctor
command.
nextui doctor [options]
- Check whether have
redundant dependencies
in the project- Check whether the NextUI components
required dependencies are installed
in the project- Check the required
tailwind.config.js
file and the content is correct- Check
.npmrc
is correct when usingpnpm
- Check
peerDependencies with required version
are installed in the project
-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
)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.
Display debug information about the local environment.
nextui env [options]
-p --packagePath
[string] The path to the package.json fileDisplay the local environment Information by using the env
command.
nextui env
Output:
NextUI CLI v0.2.1
Current installed components:
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Package │ Version │ Status │ Docs │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ @nextui-org/autocomplete │ 2.0.10 🚀latest │ stable │ 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
Visit https://nextui.org/docs/guide/cli to view the full documentation.
We're excited to see the community adopt NextUI CLI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!
Contributions are always welcome!
See CONTRIBUTING.md for ways to get started.
Please adhere to this project's CODE_OF_CONDUCT.