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
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:
npx wunderui-cli add button badge input
npx wunderui-cli login <license-key>
npx wunderui-cli add auth/sign-inwith 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
| Command | What 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 .
| Command | What 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. |
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 --fixWith 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
| Option | Effect |
|---|---|
| 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. |
npx wunderui-cli add auth/sign-in --screen 02-centered-card --dry-runwunderui.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:
| Source | Use it for |
|---|---|
| A one-off command | |
| CI and shared machines. Store it as a secret. | |
| Your own machine, written by login |
Keep the key private
Do not commit the key or paste it into a README. In CI, read it from the secret store as .
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:
npm install lucide-react cnThen wire up the package stylesheet, if your project does not have it yet, and import the screen like any other component in your app:
@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.