Skip to content
WunderUI
General

CLI

writes WunderUI straight into your project: the free components for everyone, UI Blocks with WunderUI Pro. The files land in your repository as ordinary source code: edit them, rename them, delete what you do not need. Nothing is loaded from a package at runtime, so nothing changes under you.

When you need it

You wantUse
Free components such as Button, Dialog or Date PickerThe CLI:
Core and Pro components such as Data Table or SidebarThe package from your plan
A whole screen: sign-in, billing, a dashboard pageThe CLI with a Pro license:
A complete app to start fromTemplates

Free components and blocks become your code. Ask the CLI for a Core or Pro component and it names the component and points to the plans instead of writing anything.

Quick start

Run these in your project root:

bash
npx wunderui-cli add button badge input
npx wunderui-cli login <license-key>
npx wunderui-cli add auth/sign-in

with component names writes them into under the folder your alias points to, installs their dependencies with your package manager and adds on first use. checks your license key and stores it, and with a block id writes every screen of the sign-in block into .

Commands

CommandWhat it does
Writes free components with every file they need, installs their dependencies and adds styles/wunderui.css on first use.
Writes a block's source into your project. The id is category/block, for example data/kanban.
Lists the free components and every block by category. --components shows only the components, --screens the screens inside each block.
Checks your license key and stores it in ~/.wunderui/config.json.
Writes wunderui.json: where blocks land and which import alias points there.

and the free components work without a key; the block previews are public on UI Blocks. Adding a block needs a WunderUI Pro license.

Reference and doctor

Since 1.1 the CLI also answers questions about the library offline, from the same data as the MCP server, and checks a project. People read the text output; agents add .

CommandWhat it does
Props with type, possible values, default and whether they are required; variants; keyboard and ARIA; an example. --list shows every component.
Ranks components, blocks, docs topics and tokens. --kind and --limit narrow it.
Tokens, theming, motion, installation, accessibility, rules and copy. Without a topic it lists them.
A playbook for a screen such as a settings page, dashboard, login or table page: components in order, loading, empty and error states, token, motion and accessibility rules, checks.
Checks the package and its edition, versions, the styles import and @source path, tokens, DESIGN.md, the MCP server, ThemeProvider, Node and duplicate React copies. --fix shows safe changes, --fix --write applies them.
bash
npx wunderui-cli component date-picker --dense
npx wunderui-cli search "confirm before delete" --json
npx wunderui-cli build "settings page"
npx wunderui-cli doctor --fix

With every command prints one object on stdout, , without colour, and exits with 0 (ok), 1 (error or failed check), 2 (usage), 3 (not found) or 4 (license required). prints the same facts on fewer lines. The public CLI carries the free components; for a Core or Pro component it names the plan, and after it loads the full entry with your key.

Options for add

OptionEffect
Replaces files that already exist. By default they are skipped, so your edits are safe.
Prints what would be written, without writing anything.
Prints the install command for the dependencies instead of running it.
A block: writes one screen instead of the whole block.
A block: writes somewhere other than the folder in wunderui.json.
A block: uses this license key instead of the stored one.
bash
npx wunderui-cli add auth/sign-in --screen 02-centered-card --dry-run

wunderui.json

json
{
  "componentsDir": "components/wunderui",
  "alias": "@/components/wunderui",
  "registry": "https://wunderui.com"
}

The file is only for blocks; free components follow your alias. Blocks import a few shared helpers. The CLI rewrites those imports to your as it writes, so the alias must point at . If your maps to , set to and keep the alias as .

License key and CI

The CLI looks for a key in this order:

SourceUse it for
A one-off command
CI and shared machines. Store it as a secret.
Your own machine, written by login

After adding a block

A block is built on the package and a few small dependencies. The package is not on the public npm registry: install it from , the private GitHub repository that comes with your plan (see Installation; the wunderui-setup agent skill does it for you). The rest come from npm, and the CLI prints the exact list for each block:

bash
npm install lucide-react cn

Then wire up the package stylesheet, if your project does not have it yet, and import the screen like any other component in your app:

css
@import "tailwindcss";
@import "@wunderui/react/styles.css";
@source "../node_modules/@wunderui/react/dist";

The CLI and the free components are MIT-licensed. The blocks it writes are covered by the WunderUI Pro license.