226 lines
13 KiB
Markdown
226 lines
13 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](./SKILL.md#updating-components) for the full workflow.
|
|
|
|
### `search` — Search registries
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](./SKILL.md#updating-components) 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.
|