feat: global unslop 6531421a month ago 276 lines · 16.0 KB 1 # shadcn CLI Reference 2 3 Configuration is read from ` components.json ` . 4 5 > ** IMPORTANT: 6 7 > ** IMPORTANT: 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 21 22 ``` bash 23 npx shadcn@latest init [components...] [ options 24 ``` 25 26 Initializes 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 31 | ` --preset [name] ` | ` -p 32 | ` --yes ` | ` -y 33 | ` --defaults ` | ` -d 34 | ` --force ` | ` -f 35 | ` --cwd <cwd> ` | ` -c 36 | ` --name <name> ` | ` -n 37 | ` --silent ` | ` -s 38 | ` --rtl ` | | Enable RTL support 39 | ` --reinstall ` | | Re-install existing UI components 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 46 47 ``` bash 48 npx shadcn@latest apply [preset] [ options 49 ``` 50 51 Applies 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> ` | - 56 | ` --yes ` | ` -y 57 | ` --cwd <cwd> ` | ` -c 58 | ` --silent ` | ` -s 59 60 ` [preset] ` is a shorthand for ` --preset <preset> ` . If both are provided, they must match. 61 If no preset is provided, the CLI offers to open the custom preset builder on ` ui.shadcn.com/create ` . 62 63 ### ` add 64 65 > ** IMPORTANT: 66 67 ``` bash 68 npx shadcn@latest add [components...] [ options 69 ``` 70 71 Accepts component names, registry-prefixed names ( ` @magicui/shimmer-button ` ), URLs, or local paths. 72 73 | Flag | Short | Description | Default | 74 | --------------- | ----- | 75 | ` --yes ` | ` -y 76 | ` --overwrite ` | ` -o 77 | ` --cwd <cwd> ` | ` -c 78 | ` --all ` | ` -a 79 | ` --path <path> ` | ` -p 80 | ` --silent ` | ` -s 81 | ` --dry-run ` | | Preview all changes without writing files 82 | ` --diff [path] ` | | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies 83 | ` --view [path] ` | | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies 84 85 #### Dry-Run Mode 86 87 Use ` --dry-run ` to preview what ` add ` would do without writing any files. ` 88 89 ``` bash 90 # Preview all changes. 91 npx shadcn@latest add button 92 93 # Show diffs for all files (top 5). 94 npx shadcn@latest add button 95 96 # Show the diff for a specific file. 97 npx shadcn@latest add button 98 99 # Show contents for all files (top 5). 100 npx shadcn@latest add button 101 102 # Show the full content of a specific file. 103 npx shadcn@latest add button 104 105 # Works with URLs too. 106 npx shadcn@latest add https://api.npoint.io/abc123 107 108 # CSS diffs. 109 npx shadcn@latest add button 110 ``` 111 112 ** When to use dry-run: ** 113 114 - When the user asks "what files will this add?" or "what will this change?" - use ` --dry-run ` . 115 - Before overwriting existing components - use ` --diff ` to preview the changes first. 116 - When the user wants to inspect component source code without installing - use ` --view ` . 117 - When checking what CSS changes would be made to ` globals.css ` - use ` --diff globals.css ` . 118 - When the user asks to review or audit third-party registry code before installing - use ` --view ` to inspect the source. 119 120 > ** ` 121 122 #### Smart Merge from Upstream 123 124 See [ Updating Components in SKILL.md ] ( ./SKILL.md#updating-components 125 126 ### ` search 127 128 ``` bash 129 npx shadcn@latest search < registries.. 130 ``` 131 132 Fuzzy search across registries. Also aliased as ` npx shadcn@latest list ` . Without ` -q ` , lists all items. 133 134 | Flag | Short | Description | Default | 135 | ------------------- | ----- | 136 | ` --query <query> ` | ` -q 137 | ` --limit <number> ` | ` -l 138 | ` --offset <number> ` | ` -o 139 | ` --cwd <cwd> ` | ` -c 140 141 ### ` view 142 143 ``` bash 144 npx shadcn@latest view < items.. 145 ``` 146 147 Displays item info including file contents. Example: ` npx shadcn@latest view @shadcn/button ` . 148 149 ### ` docs 150 151 ``` bash 152 npx shadcn@latest docs < components.. 153 ``` 154 155 Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content. 156 157 Example output for ` npx shadcn@latest docs input button ` : 158 159 ``` 160 base radix 161 162 input 163 docs https://ui.shadcn.com/docs/components/radix/input 164 examples https://raw.githubusercontent.com/.../examples/input-example.tsx 165 166 button 167 docs https://ui.shadcn.com/docs/components/radix/button 168 examples https://raw.githubusercontent.com/.../examples/button-example.tsx 169 ``` 170 171 Some components include an ` api ` link to the underlying library (e.g. ` cmdk ` for the command component). 172 173 ### ` diff 174 175 Do not use this command. Use ` npx shadcn@latest add --diff ` instead. 176 177 ### ` info 178 179 ``` bash 180 npx shadcn@latest info [options] 181 ``` 182 183 Displays project info and ` components.json ` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths. 184 185 | Flag | Short | Description | Default | 186 | ------------- | ----- | 187 | ` --cwd <cwd> ` | ` -c 188 189 ** Project Info fields: ** 190 191 | Field | Type | Meaning | 192 | -------------------- | --------- | 193 | ` framework ` | ` string 194 | ` frameworkVersion ` | ` string 195 | ` isSrcDir ` | ` boolean 196 | ` isRSC ` | ` boolean 197 | ` isTsx ` | ` boolean 198 | ` tailwindVersion ` | ` string 199 | ` tailwindConfigFile ` | ` string 200 | ` tailwindCssFile ` | ` string 201 | ` aliasPrefix ` | ` string 202 | ` packageManager ` | ` string 203 204 ** Components.json fields: ** 205 206 | Field | Type | Meaning | 207 | -------------------- | --------- | 208 | ` base ` | ` string 209 | ` style ` | ` string 210 | ` rsc ` | ` boolean 211 | ` tsx ` | ` boolean 212 | ` tailwind.config ` | ` string 213 | ` tailwind.css ` | ` string 214 | ` iconLibrary ` | ` string 215 | ` aliases.components ` | ` string 216 | ` aliases.utils ` | ` string 217 | ` aliases.ui ` | ` string 218 | ` aliases.lib ` | ` string 219 | ` aliases.hooks ` | ` string 220 | ` resolvedPaths ` | ` object 221 | ` registries ` | ` object 222 223 ** Links fields: ** 224 225 The ` info ` output includes a ** Links 226 227 ### ` build 228 229 ``` bash 230 npx shadcn@latest build [registry] [ options 231 ``` 232 233 Builds ` registry.json ` into individual JSON files for distribution. Default input: ` ./registry.json ` , default output: 234 235 | Flag | Short | Description | Default | 236 | ----------------- | ----- | 237 | ` --output <path> ` | ` -o 238 | ` --cwd <cwd> ` | ` -c 239 240 --- 241 242 ## Templates 243 244 | Value | Framework | Monorepo support | 245 | -------------- | -------------- | 246 | ` next ` | Next.js | Yes 247 | ` vite ` | Vite | Yes 248 | ` start ` | TanStack Start | Yes 249 | ` react-router ` | React Router | Yes 250 | ` astro ` | Astro | Yes 251 | ` laravel ` | Laravel | No 252 253 All templates support monorepo scaffolding via the ` --monorepo ` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. ` next-monorepo ` , 254 255 --- 256 257 ## Presets 258 259 Three ways to specify a preset via ` --preset ` : 260 261 1. ** Named: ** 262 2. ** Code: ** 263 3. ** URL: ** 264 265 > ** IMPORTANT: 266 > Use ` npx shadcn@latest apply --preset <code> 267 268 ## Switching Presets 269 270 Ask the user first: ** overwrite ** , ** 271 272 - ** Overwrite / Re-install ** → 273 - ** Merge ** → 274 - ** Skip ** → 275 276 Always 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 (
**
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.
**
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.
`
- Initialize or create a project
]
---------------------------------------------------------
|
-------
|
`
|
Template (next, start, vite, next-monorepo, react-router)
|
-
|
`
|
Preset configuration (named, code, or URL)
|
-
|
`
|
Skip confirmation prompt
|
`
true
`
|
`
|
Use defaults (
`
--template=next --preset=base-nova
`
)
|
`
false
`
|
`
|
Force overwrite existing configuration
|
`
false
`
|
`
|
Working directory
|
current
|
`
|
Name for new project
|
-
|
`
|
Mute output
|
`
false
`
|
|
-
|
|
`
false
`
|
|
-
|
|
-
|
`
- Apply a preset to an existing project
]
------------------------------------------
|
-------
|
|
Preset configuration (named, code, or URL)
|
-
|
`
|
Skip confirmation prompt
|
`
false
`
|
`
|
Working directory
|
current
|
`
|
Mute output
|
`
false
`
|
`
- Add components
**
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.
]
--------------------------------------------------------------------------------------------------------------------
|
-------
|
`
|
Skip confirmation prompt
|
`
false
`
|
`
|
Overwrite existing files
|
`
false
`
|
`
|
Working directory
|
current
|
`
|
Add all available components
|
`
false
`
|
`
|
Target path for the component
|
-
|
`
|
Mute output
|
`
false
`
|
|
`
false
`
|
`
--dry-run
`
)
|
-
|
`
--dry-run
`
)
|
-
|
--diff
`
and
`
--view
`
both imply
`
--dry-run
`
.
--dry-run
--diff
--diff
button.tsx
--view
--view
button.tsx
--dry-run
--diff
globals.css
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.
)
for the full workflow.
`
- Search registries
.
>
[options]
----------------------
|
-------
|
`
|
Search query
|
-
|
`
|
Max items per registry
|
`
100
`
|
`
|
Items to skip
|
`
0
`
|
`
|
Working directory
|
current
|
`
- View item details
.
>
[options]
`
- Get component documentation URLs
.
>
[options]
`
- Check for updates
`
- Project information
-----------------
|
-------
|
`
|
Working directory
|
current
|
------------------------------------------------------------------
|
`
|
Detected framework (
`
next
`
,
`
vite
`
,
`
react-router
`
,
`
start
`
, etc.)
|
`
|
Framework version (e.g.
`
15.2.4
`
)
|
`
|
Whether the project uses a
`
src/
`
directory
|
`
|
Whether React Server Components are enabled
|
`
|
Whether the project uses TypeScript
|
`
|
`
"v3"
`
or
`
"v4"
`
|
`
|
Path to the Tailwind config file
|
`
|
Path to the global CSS file
|
`
|
Import alias prefix (e.g.
`
@
`
,
`
~
`
,
`
@/
`
)
|
`
|
Detected package manager (
`
npm
`
,
`
pnpm
`
,
`
yarn
`
,
`
bun
`
)
|
------------------------------------------------------------------------------------------
|
`
|
Primitive library (
`
radix
`
or
`
base
`
) - determines component APIs and available props
|
`
|
Visual style (e.g.
`
nova
`
,
`
vega
`
)
|
`
|
RSC flag from config
|
`
|
TypeScript flag
|
`
|
Tailwind config path
|
`
|
Global CSS path - this is where custom CSS variables go
|
`
|
Icon library - determines icon import package (e.g.
`
lucide-react
`
,
`
@tabler/icons-react
`
)
|
`
|
Component import alias (e.g.
`
@/components
`
)
|
`
|
Utils import alias (e.g.
`
@/lib/utils
`
)
|
`
|
UI component alias (e.g.
`
@/components/ui
`
)
|
`
|
Lib alias (e.g.
`
@/lib
`
)
|
`
|
Hooks alias (e.g.
`
@/hooks
`
)
|
`
|
Absolute file-system paths for each alias
|
`
|
Configured custom registries
|
**
section with templated URLs for component docs, source, and examples. For resolved URLs, use
`
npx shadcn@latest docs <component>
`
instead.
`
- Build a custom registry
]
`
./public/r
`
.
-----------------
|
------------
|
`
|
Output directory
|
`
./public/r
`
|
`
|
Working directory
|
current
|
----------------
|
|
|
|
|
|
|
`
vite-monorepo
`
). When neither
`
--monorepo
`
nor
`
--no-monorepo
`
is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
`
--preset nova
`
or
`
--preset lyra
`
`
--preset a2r6bw
`
(version-prefixed base62 string, e.g.
`
a2r6bw
`
or
`
b0
`
)
`
--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."
`
**
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.
`
when overwriting an existing project's preset.
merge
**
, or
**
skip
**
existing components?
`
npx shadcn@latest apply --preset <code>
`
. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
`
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.
`
npx shadcn@latest init --preset <code> --force --no-reinstall
`
. Only updates config and CSS variables, leaves existing components as-is.
`
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.