nuxt-app/.agents/skills/shadcn-vue/cli.md

shadcn-vue CLI Reference

Configuration is read from components.json.

IMPORTANT: Always run commands using the project's package runner: npx shadcn-vue@latest, pnpm dlx shadcn-vue@latest, or bunx --bun shadcn-vue@latest. Check packageManager from project context to choose the right one. Examples below use npx shadcn-vue@latest but substitute the correct runner for the project. 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.

Contents

• Commands: init, apply, add (smart merge), search, view, docs, info, build
• Templates: nuxt, vite, astro, laravel
• Presets: named, code, URL formats and fields
• Switching presets

---

Commands

init — Initialize or create a project

npx shadcn-vue@latest init [components...] [options]

Initializes shadcn-vue in an existing project or creates a new project (when --name is provided). Optionally installs components in the same step.

Flag	Short	Description	Default
--template <template>	-t	Template (nuxt, vite, astro, laravel)	—
--preset [name]	-p	Preset configuration (named, code, or URL)	—
--yes	-y	Skip confirmation prompt	true
--defaults	-d	Use defaults (--template=nuxt --preset=nova)	false
--force	-f	Force overwrite existing configuration	false
--cwd <cwd>	-c	Working directory	current
--name <name>	-n	Name for new project	—
--silent	-s	Mute output	false
--rtl		Enable RTL support	—
--reinstall		Re-install existing UI components	false

npx shadcn-vue@latest create is an alias for npx shadcn-vue@latest init.

apply — Apply a preset to an existing project

npx shadcn-vue@latest apply [preset] [options]

Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.

Flag	Short	Description	Default
--preset <preset>	—	Preset configuration (named, code, or URL)	—
--yes	-y	Skip confirmation prompt	false
--cwd <cwd>	-c	Working directory	current
--silent	-s	Mute output	false

[preset] is a shorthand for --preset <preset>. If both are provided, they must match. If no preset is provided, the CLI offers to open the custom preset builder on shadcn-vue.com/create.

add — Add components

IMPORTANT: NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.

npx shadcn-vue@latest add [components...] [options]

Accepts component names, registry-prefixed names (@magicui/shimmer-button), URLs, or local paths.

Flag	Short	Description	Default
--yes	-y	Skip confirmation prompt	false
--overwrite	-o	Overwrite existing files	false
--cwd <cwd>	-c	Working directory	current
--all	-a	Add all available components	false
--path <path>	-p	Target path for the component	—
--silent	-s	Mute output	false

Smart Merge from Upstream

See Updating Components in SKILL.md for the full workflow.

search — Search registries

npx shadcn-vue@latest search <registries...> [options]

Fuzzy search across registries. Also aliased as npx shadcn-vue@latest list. Without -q, lists all items.

Flag	Short	Description	Default
--query <query>	-q	Search query	—
--limit <number>	-l	Max items per registry	100
--offset <number>	-o	Items to skip	0
--cwd <cwd>	-c	Working directory	current

view — View item details

npx shadcn-vue@latest view <items...> [options]

Displays item info including file contents. Example: npx shadcn-vue@latest view @shadcn/button.

docs — Get component documentation URLs

npx shadcn-vue@latest docs <components...> [options]

Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.

Example output for npx shadcn-vue@latest docs input button:

input
  docs      https://shadcn-vue.com/docs/components/input
  examples  https://raw.githubusercontent.com/.../examples/InputExample.vue

button
  docs      https://shadcn-vue.com/docs/components/button
  examples  https://raw.githubusercontent.com/.../examples/ButtonExample.vue

Some components include an api link to the underlying library (e.g. reka-ui for the primitive components).

diff — Check for updates

Do not use this command. Use npx shadcn-vue@latest add --diff instead.

info — Project information

npx shadcn-vue@latest info [options]

Displays project info and components.json configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.

Flag	Short	Description	Default
--cwd <cwd>	-c	Working directory	current

Project Info fields:

Field	Type	Meaning
framework	string	Detected framework (nuxt, vite, astro, laravel)
frameworkVersion	string	Framework version (e.g. 3.15.0)
isSrcDir	boolean	Whether the project uses a src/ directory
isTs	boolean	Whether the project uses TypeScript
tailwindVersion	string	"v3" or "v4"
tailwindConfigFile	string	Path to the Tailwind config file
tailwindCssFile	string	Path to the global CSS file
aliasPrefix	string	Import alias prefix (e.g. @, ~, @/)
packageManager	string	Detected package manager (npm, pnpm, yarn, bun)

Components.json fields:

Field	Type	Meaning
base	string	Primitive library (reka) — determines component APIs and available props
style	string	Visual style (e.g. nova, vega)
typescript	boolean	TypeScript flag
tailwind.config	string	Tailwind config path
tailwind.css	string	Global CSS path — this is where custom CSS variables go
iconLibrary	string	Icon library — determines icon import package (e.g. @lucide/vue, @tabler/icons-vue)
aliases.components	string	Component import alias (e.g. @/components)
aliases.utils	string	Utils import alias (e.g. @/lib/utils)
aliases.ui	string	UI component alias (e.g. @/components/ui)
aliases.lib	string	Lib alias (e.g. @/lib)
aliases.composables	string	Composables/Hooks alias (e.g. @/composables)
resolvedPaths	object	Absolute file-system paths for each alias
registries	object	Configured custom registries

Links fields:

The info output includes a Links section with templated URLs for component docs, source, and examples. For resolved URLs, use npx shadcn-vue@latest docs <component> instead.

build — Build a custom registry

npx shadcn-vue@latest build [registry] [options]

Builds registry.json into individual JSON files for distribution. Default input: ./registry.json, default output: ./public/r.

Flag	Short	Description	Default
--output <path>	-o	Output directory	./public/r
--cwd <cwd>	-c	Working directory	current

---

Templates

Value	Framework
nuxt	Nuxt
vite	Vite
astro	Astro
laravel	Laravel

---

Presets

Three ways to specify a preset via --preset:

1. Named: --preset nova or --preset lyra
2. Code: --preset a2r6bw (version-prefixed base62 string, e.g. a2r6bw)
3. URL: --preset "https://shadcn-vue.com/init?base=reka&style=nova&..."

IMPORTANT: Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to npx shadcn-vue@latest init --preset <code> and let the CLI handle resolution. Use npx shadcn-vue@latest apply --preset <code> when overwriting an existing project's preset.

Switching Presets

Ask the user first: overwrite, merge, or skip existing components?

• Overwrite / Re-install → npx shadcn-vue@latest apply --preset <code>. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
• Merge → npx shadcn-vue@latest init --preset <code> --force --no-reinstall, then run npx shadcn-vue@latest info to get the list of installed components and use the smart merge workflow to update them one by one, preserving local changes. Use when the user has customized components.
• Skip → npx shadcn-vue@latest init --preset <code> --force --no-reinstall. Only updates config and CSS variables, leaves existing components as-is.

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 (base) 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.