1# shadcn CLI Reference
2 
3Configuration is read from `components.json`.
4 
5> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
6 
7> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
8 
9## Contents
10 
11- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build
12- Templates: next, vite, start, react-router, astro
13- Presets: named, code, URL formats and fields
14- Switching presets
15 
16---
17 
18## Commands
19 
20### `init` — Initialize or create a project
21 
22```bash
23npx shadcn@latest init [components...] [options]
24```
25 
26Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
27 
28| Flag                    | Short | Description                                               | Default |
29| ----------------------- | ----- | --------------------------------------------------------- | ------- |
30| `--template <template>` | `-t`  | Template (next, start, vite, next-monorepo, react-router) | —       |
31| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)                | —       |
32| `--yes`                 | `-y`  | Skip confirmation prompt                                  | `true`  |
33| `--defaults`            | `-d`  | Use defaults (`--template=next --preset=base-nova`)       | `false` |
34| `--force`               | `-f`  | Force overwrite existing configuration                    | `false` |
35| `--cwd <cwd>`           | `-c`  | Working directory                                         | current |
36| `--name <name>`         | `-n`  | Name for new project                                      | —       |
37| `--silent`              | `-s`  | Mute output                                               | `false` |
38| `--rtl`                 |       | Enable RTL support                                        | —       |
39| `--reinstall`           |       | Re-install existing UI components                         | `false` |
40| `--monorepo`            |       | Scaffold a monorepo project                               | —       |
41| `--no-monorepo`         |       | Skip the monorepo prompt                                  | —       |
42 
43`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
44 
45### `apply` — Apply a preset to an existing project
46 
47```bash
48npx shadcn@latest apply [preset] [options]
49```
50 
51Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
52 
53| Flag                | Short | Description                                | Default |
54| ------------------- | ----- | ------------------------------------------ | ------- |
55| `--preset <preset>` | —     | Preset configuration (named, code, or URL) | —       |
56| `--yes`             | `-y`  | Skip confirmation prompt                   | `false` |
57| `--cwd <cwd>`       | `-c`  | Working directory                          | current |
58| `--silent`          | `-s`  | Mute output                                | `false` |
59 
60`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
61If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.
62 
63### `add` — Add components
64 
65> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
66 
67```bash
68npx shadcn@latest add [components...] [options]
69```
70 
71Accepts component names, registry-prefixed names (`@magicui/shimmer-button`),
72GitHub item addresses (`owner/repo/item`), URLs, or local paths.
73 
74| Flag            | Short | Description                                                                                                          | Default |
75| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
76| `--yes`         | `-y`  | Skip confirmation prompt                                                                                             | `false` |
77| `--overwrite`   | `-o`  | Overwrite existing files                                                                                             | `false` |
78| `--cwd <cwd>`   | `-c`  | Working directory                                                                                                    | current |
79| `--all`         | `-a`  | Add all available components                                                                                         | `false` |
80| `--path <path>` | `-p`  | Target path for the component                                                                                        | —       |
81| `--silent`      | `-s`  | Mute output                                                                                                          | `false` |
82| `--dry-run`     |       | Preview all changes without writing files                                                                            | `false` |
83| `--diff [path]` |       | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`)         | —       |
84| `--view [path]` |       | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | —       |
85 
86#### Dry-Run Mode
87 
88Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
89 
90```bash
91# Preview all changes.
92npx shadcn@latest add button --dry-run
93 
94# Show diffs for all files (top 5).
95npx shadcn@latest add button --diff
96 
97# Show the diff for a specific file.
98npx shadcn@latest add button --diff button.tsx
99 
100# Show contents for all files (top 5).
101npx shadcn@latest add button --view
102 
103# Show the full content of a specific file.
104npx shadcn@latest add button --view button.tsx
105 
106# Works with URLs too.
107npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
108 
109# Works with public GitHub registries too.
110npx shadcn@latest add owner/repo/item --dry-run
111 
112# CSS diffs.
113npx shadcn@latest add button --diff globals.css
114```
115 
116**When to use dry-run:**
117 
118- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
119- Before overwriting existing components — use `--diff` to preview the changes first.
120- When the user wants to inspect component source code without installing — use `--view`.
121- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
122- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
123 
124> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
125 
126#### Smart Merge from Upstream
127 
128See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
129 
130### `search` — Search registries
131 
132```bash
133npx shadcn@latest search [registries...] [options]
134```
135 
136Fuzzy search across registries. Also aliased as `npx shadcn@latest list`.
137Supports namespaces (`@acme`), public GitHub registry sources (`owner/repo`),
138and registry catalog URLs. Without `-q`, lists all items. When no registries are
139passed, searches every registry configured in `components.json`.
140 
141| Flag                | Short | Description                                       | Default |
142| ------------------- | ----- | ------------------------------------------------- | ------- |
143| `--query <query>`   | `-q`  | Search query                                      | —       |
144| `--type <type>`     | `-t`  | Filter by item type (e.g. `ui`, `block`, `hook`); comma-separated | —       |
145| `--limit <number>`  | `-l`  | Max items to display                              | `100`   |
146| `--offset <number>` | `-o`  | Items to skip                                     | `0`     |
147| `--json`            |       | Output as JSON                                    | `false` |
148| `--cwd <cwd>`       | `-c`  | Working directory                                 | current |
149 
150### `view` — View item details
151 
152```bash
153npx shadcn@latest view <items...> [options]
154```
155 
156Displays item info including file contents. Examples:
157`npx shadcn@latest view @shadcn/button`,
158`npx shadcn@latest view owner/repo/item`.
159 
160### `docs` — Get component documentation URLs
161 
162```bash
163npx shadcn@latest docs <components...> [options]
164```
165 
166Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
167 
168Example output for `npx shadcn@latest docs input button`:
169 
170```
171base  radix
172 
173input
174  docs      https://ui.shadcn.com/docs/components/radix/input
175  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx
176 
177button
178  docs      https://ui.shadcn.com/docs/components/radix/button
179  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx
180```
181 
182Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
183 
184### `diff` — Check for updates
185 
186Do not use this command. Use `npx shadcn@latest add --diff` instead.
187 
188### `info` — Project information
189 
190```bash
191npx shadcn@latest info [options]
192```
193 
194Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
195 
196| Flag          | Short | Description       | Default |
197| ------------- | ----- | ----------------- | ------- |
198| `--cwd <cwd>` | `-c`  | Working directory | current |
199 
200**Project Info fields:**
201 
202| Field                | Type      | Meaning                                                            |
203| -------------------- | --------- | ------------------------------------------------------------------ |
204| `framework`          | `string`  | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |
205| `frameworkVersion`   | `string`  | Framework version (e.g. `15.2.4`)                                  |
206| `isSrcDir`           | `boolean` | Whether the project uses a `src/` directory                        |
207| `isRSC`              | `boolean` | Whether React Server Components are enabled                        |
208| `isTsx`              | `boolean` | Whether the project uses TypeScript                                |
209| `tailwindVersion`    | `string`  | `"v3"` or `"v4"`                                                   |
210| `tailwindConfigFile` | `string`  | Path to the Tailwind config file                                   |
211| `tailwindCssFile`    | `string`  | Path to the global CSS file                                        |
212| `aliasPrefix`        | `string`  | Import alias prefix (e.g. `@`, `~`, `@/`)                          |
213| `packageManager`     | `string`  | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`)            |
214 
215**Components.json fields:**
216 
217| Field                | Type      | Meaning                                                                                    |
218| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
219| `base`               | `string`  | Primitive library (`radix` or `base`) — determines component APIs and available props      |
220| `style`              | `string`  | Visual style (e.g. `nova`, `vega`)                                                         |
221| `rsc`                | `boolean` | RSC flag from config                                                                       |
222| `tsx`                | `boolean` | TypeScript flag                                                                            |
223| `tailwind.config`    | `string`  | Tailwind config path                                                                       |
224| `tailwind.css`       | `string`  | Global CSS path — this is where custom CSS variables go                                    |
225| `iconLibrary`        | `string`  | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
226| `aliases.components` | `string`  | Component import alias (e.g. `@/components`)                                               |
227| `aliases.utils`      | `string`  | Utils import alias (e.g. `@/lib/utils`)                                                    |
228| `aliases.ui`         | `string`  | UI component alias (e.g. `@/components/ui`)                                                |
229| `aliases.lib`        | `string`  | Lib alias (e.g. `@/lib`)                                                                   |
230| `aliases.hooks`      | `string`  | Hooks alias (e.g. `@/hooks`)                                                               |
231| `resolvedPaths`      | `object`  | Absolute file-system paths for each alias                                                  |
232| `registries`         | `object`  | Configured custom registries                                                               |
233 
234**Links fields:**
235 
236The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
237 
238### `build` — Build a custom registry
239 
240```bash
241npx shadcn@latest build [registry] [options]
242```
243 
244Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
245 
246For authoring rules, `include`, item definitions, `registryDependencies`, and
247GitHub registry behavior, see [registry.md](./registry.md).
248 
249| Flag              | Short | Description       | Default      |
250| ----------------- | ----- | ----------------- | ------------ |
251| `--output <path>` | `-o`  | Output directory  | `./public/r` |
252| `--cwd <cwd>`     | `-c`  | Working directory | current      |
253 
254---
255 
256## Templates
257 
258| Value          | Framework      | Monorepo support |
259| -------------- | -------------- | ---------------- |
260| `next`         | Next.js        | Yes              |
261| `vite`         | Vite           | Yes              |
262| `start`        | TanStack Start | Yes              |
263| `react-router` | React Router   | Yes              |
264| `astro`        | Astro          | Yes              |
265| `laravel`      | Laravel        | No               |
266 
267All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
268 
269---
270 
271## Presets
272 
273Three ways to specify a preset via `--preset`:
274 
2751. **Named:** `--preset nova` or `--preset lyra`
2762. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
2773. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
278 
279> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.
280> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
281 
282## Switching Presets
283 
284Ask the user first: **overwrite**, **merge**, or **skip** existing components?
285 
286- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
287- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
288- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
289 
290Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
291