CLI
Use the NachUI CLI to initialize your project, add, update, remove, and list components directly from the terminal.
The NachUI CLI is the fastest way to manage components in your project. It connects to the official registry and installs a component together with every file it imports, in the same folder layout as the NachUI source, so the imports between files work unchanged. The installation guide covers the manual route.
Installation
You don't need to install anything globally. Use
pnpm dlx or npx to run the CLI on demand:Commands
init
Sets up NachUI in your project. This is the first command you should run. It will:
- Fetch the available themes from the registry and ask you to pick one.
- Create a
nachui.jsonconfiguration file in the root of your project. - Add the theme tokens to your stylesheet (
src/app/globals.cssfor Next.js,src/index.cssfor Vite). - Write the
cnhelper tosrc/lib/cn.ts. - Offer to install
clsxandtailwind-merge.
pnpm dlx nachui initIf your stylesheet already has styles,
init asks before replacing them. The default answer keeps them and adds the tokens at the end. Running init again replaces the tokens from the previous run instead of adding a second copy. Pass --yes to accept the defaults without prompts; it never replaces your files.After running
init, your project will contain a nachui.json file like this:add
Adds one or more components from the registry. Requires
nachui.json to exist (run init first).pnpm dlx nachui add <component>Example:
pnpm dlx nachui add buttonWhat it does:
- Fetches the component and every file it imports, like
lib/cn.ts,lib/motion.tsor another component. - Writes each file into the folder of its family inside
baseDir, so the imports between them work unchanged. - Skips files that are already identical, and asks before replacing a file you changed.
- Checks the npm packages they need and offers to install the missing ones with your package manager (npm, pnpm, yarn or bun, detected from your lockfile).
For example,
nachui add hybrids/confirm writes:| Flag | Effect |
|---|---|
-o, --overwrite | Replace files that differ from the registry without asking |
-y, --yes | Skip prompts: install missing packages, keep files that differ from the registry |
A name that exists in more than one family, like
tool, needs its family: nachui add ai/tool.Tip
Use
pnpm dlx nachui list to see all available component slugs.list
Lists all components currently available in the NachUI registry.
pnpm dlx nachui listOutput example:
Each entry shows the component name, its slug (used with
add, update and remove), and the npm packages it imports.update
Fetches the latest version of an installed component and replaces your local file.
pnpm dlx nachui update <component>Example:
pnpm dlx nachui update buttonWarning
Running
update will overwrite your local changes to that component. You will be asked to
confirm before the update is applied.The command will:
- Check that the component is installed where
addputs it, for examplesrc/components/button.tsx. - Fetch the latest code from the registry and ask before writing.
- Add any file the new version imports that you don't have yet.
- List shared files that differ from the registry, like
lib/cn.ts, and only replace them if you agree, since other components use them too.
remove
Removes an installed component by deleting its file.
pnpm dlx nachui remove <component>Example:
pnpm dlx nachui remove buttonThe command looks for the component in every family folder under
baseDir and asks for confirmation before deleting it. Shared files such as lib/cn.ts are kept, because other components may use them. Pass --yes to skip the confirmation.Warning
This action cannot be undone. Make sure you no longer need the component before confirming.
Typical workflow
Initialize NachUI in your project
pnpm dlx nachui initBrowse available components
pnpm dlx nachui listAdd a component
pnpm dlx nachui add buttonUpdate a component to the latest version
pnpm dlx nachui update buttonRemove a component you no longer need
pnpm dlx nachui remove buttonConfiguration file
The
nachui.json file is created by init and is required by the add, update, and remove commands.| Field | Description |
|---|---|
style | The color format of the theme |
baseDir | Folder that holds components/, layout/, ai/, hybrids/, icons/ and lib/. Defaults to src |
tailwind.css | Path to the stylesheet that holds the theme tokens |
Files go to
<baseDir>/<family folder>/<name>: UI elements to components/, layout elements to layout/, and AI elements, hybrids, icons and helpers to ai/, hybrids/, icons/ and lib/. That is the same layout as the NachUI source, which is why the relative imports in each file work without edits.Tailwind CSS v4 has no config file, so there is nothing else to point at: the theme lives in CSS variables in your stylesheet.
A
nachui.json from an older version of the CLI still works. It has no baseDir, so components go under src/. Components that version installed in src/components/ui/ are left where they are; move them to src/components/ if you want update to find them.To use a local or self-hosted registry, set
NACHUI_API_URL, for example NACHUI_API_URL=http://localhost:3001/api/v1 npx nachui list.Found something to improve?
Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.