shadcn/ui CLI 命令深度参考：init、apply、add（dry-run）、search、info、build 全解与源码级说明

本文基于 shadcn/ui 仓库中面向 AI Agent 的技能参考文档 skills/shadcn/cli.md 编写，系统梳理 shadcn CLI 的全部核心命令（init、apply、add、search、view、docs、info、build）、模板体系与预设（Preset）机制。读完本文，你能准确使用 npx shadcn@latest 完成项目初始化、组件添加与变更预览（dry-run/diff/view）、注册表搜索、项目诊断和自定义注册表构建，并且知道每个命令在 packages/shadcn 源码中的真实行为依据。

CLI 入口与运行方式

shadcn CLI 的所有配置均从项目根目录的 components.json 读取。仓库中的真实示例可参考 apps/v4/components.json：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/registry/new-york-v4/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

运行命令时始终应使用项目自身的包管理器执行器：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest，具体选择取决于项目 package.json 中声明的 packageManager。下文的示例统一使用 npx shadcn@latest，实际使用时请替换为对应执行器。

从源码结构看，CLI 基于 commander 构建，入口 packages/shadcn/src/index.ts 中注册了 init、apply、add、diff、docs、view、search、migrate、eject、info、build、mcp、preset、registry 等子命令，其中 diff、eject 等命令在 Agent 工作流文档中未作为常用命令列出。

两个重要使用约束（直接来自技能文档）：

• 只使用文档明确记载的 flag：不要臆造参数。CLI 会自动从项目 lockfile 检测包管理器，不存在 --package-manager 参数。
• 比较本地组件与上游差异、预览变更时，始终使用 npx shadcn@latest add <component> --dry-run、--diff 或 --view，不要手动从 GitHub 抓取原始文件——CLI 会自动处理注册表解析、文件路径映射和 CSS diff。

init — 初始化或创建项目

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

init 用于在已有项目中初始化 shadcn/ui，或在提供 --name 时创建新项目，并可在同一步骤中安装组件。npx shadcn@latest create 是 init 的别名——这一点在 packages/shadcn/src/commands/init.ts 中可直接确认（.alias("create")）。

Flag	短选项	说明	默认值
--template <template>	-t	模板（next, start, vite, react-router, laravel, astro）	—
--preset [name]	-p	预设配置（命名预设、preset code 或 URL）	—
--yes	-y	跳过确认提示	true
--defaults	-d	使用默认配置（--template=next --preset=base-nova）	false
--force	-f	强制覆盖已有配置	false
--cwd <cwd>	-c	工作目录	当前目录
--name <name>	-n	新项目名称	—
--silent	-s	静默输出	false
--rtl	—	启用 RTL 支持	—
--reinstall	—	重新安装已有的 UI 组件	false
--monorepo	—	搭建 monorepo 项目	—
--no-monorepo	—	跳过 monorepo 询问	—

源码行为补充。 从 packages/shadcn/src/commands/init.ts 的 commander 定义看，上述之外还定义了 --base（base, radix, aria 三个基础库）、--css-variables/--no-css-variables、--pointer 等 flag；技能文档只列出 Agent 场景下常用的子集。几个值得注意的实现细节：

• --defaults 的实际展开：defaults 分支会把模板补为 next、基础库补为 base（见 init.ts），并与默认预设 nova 组合生成 init URL。
• 模板校验：非法模板名会立即报错并退出，同时打印可用模板列表（init.ts）。
• 已有 components.json 时的处理：未传 --force 时会交互式询问是否覆盖；选择覆盖后自动置 force = true。--reinstall 会收集项目已安装的组件并加入本次安装列表以覆盖重写。
• 失败自动回滚：init 在写入前会备份 components.json，并注册 exit 监听器在进程异常退出时恢复备份（init.ts），保证中途失败不会留下损坏的配置。
• monorepo 探测：在 monorepo 根目录执行且未指定 --monorepo 时，CLI 会提示应在具体的 workspace 中运行（init.ts）；--monorepo 与 --no-monorepo 都未传时，交互式询问。
• base 解析优先级：--base flag > 预设/URL 中携带的 base > 从已有 components.json 的 style 推断 > 交互询问（init.ts）。

apply — 对已有项目应用预设

npx shadcn@latest apply [preset] [options]

apply 将预设应用到已有项目，覆盖由预设驱动的配置、字体、CSS 变量以及检测到的 UI 组件。

Flag	短选项	说明	默认值
--preset <preset>	—	预设配置（命名预设、code 或 URL）	—
--yes	-y	跳过确认提示	false
--cwd <cwd>	-c	工作目录	当前目录
--silent	-s	静默输出	false

位置参数 [preset] 等价于 --preset <preset>；两者同时提供时必须一致，否则报错退出——这一校验逻辑可见 packages/shadcn/src/commands/apply.ts 的 resolveApplyPreset。若未提供任何 preset，CLI 会引导打开 ui.shadcn.com/create 的自定义预设构建器，并在给出 preset code 后提示执行 shadcn apply --preset <preset>。

源码行为补充。

• 前置条件硬校验：apply 只在存在 components.json 的已有项目中工作；目录为空或找不到配置时，会直接提示先运行 shadcn init（apply.ts）。
• 自动保留当前 base：apply 会用现有配置的 style 解析出当前 base（base 或 radix），并将其注入解析后的 init URL 中（resolveApplyInitUrl，见 apply.ts），即预设切换不会悄悄改变组件基础库。
• 部分应用：从源码结构看，apply 还支持 --only theme,font 参数，允许只应用预设的主题或字体部分而不重装组件（apply.ts），该 flag 未出现在技能文档的 flag 表中，属于源码额外能力。
• monorepo 同步：应用完成后，CLI 会把 style、baseColor、rtl、iconLibrary 等设计设置同步到链接的 workspace 的 components.json，失败时整体回滚备份（apply.ts）。

add — 添加组件

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

add 接受四种组件来源：组件名、带注册表前缀的名字（如 @magicui/shimmer-button）、GitHub item 地址（owner/repo/item）、URL 或本地路径。

Flag	短选项	说明	默认值
--yes	-y	跳过确认提示	false
--overwrite	-o	覆盖已有文件	false
--cwd <cwd>	-c	工作目录	当前目录
--all	-a	添加全部可用组件	false
--path <path>	-p	组件的目标路径	—
--silent	-s	静默输出	false
--dry-run	—	预览全部变更但不写文件	false
--diff [path]	—	显示 diff。不带 path 时显示前 5 个文件；带 path 时只显示该文件（隐含 --dry-run）	—
--view [path]	—	显示文件内容。不带 path 时显示前 5 个文件；带 path 时只显示该文件（隐含 --dry-run）	—

Dry-Run 模式

--dry-run 用于在写任何文件之前预览 add 将执行的操作；--diff 和 --view 均隐含 --dry-run。这一语义在源码中是一行的判断：packages/shadcn/src/commands/add.ts 中 const isDryRun = options.dryRun || options.diff || options.view，随后走 dryRunComponents 预览分支而不落盘。

完整示例（继承自技能文档）：

# 预览全部变更。
npx shadcn@latest add button --dry-run

# 显示所有文件的 diff（最多前 5 个）。
npx shadcn@latest add button --diff

# 显示指定文件的 diff。
npx shadcn@latest add button --diff button.tsx

# 显示所有文件内容（最多前 5 个）。
npx shadcn@latest add button --view

# 显示指定文件的完整内容。
npx shadcn@latest add button --view button.tsx

# 同样支持 URL。
npx shadcn@latest add https://api.npoint.io/abc123 --dry-run

# 也支持公开的 GitHub 注册表。
npx shadcn@latest add owner/repo/item --dry-run

# CSS diff（查看 globals.css 将发生什么变化）。
npx shadcn@latest add button --diff globals.css

何时使用 dry-run（技能文档给出的判断准则）：

• 用户问“这个会添加哪些文件 / 会改什么”时 — 用 --dry-run；
• 覆盖已有组件之前 — 先用 --diff 预览变更；
• 用户想检查组件源码但不安装时 — 用 --view；
• 用户想确认 globals.css 会经历哪些 CSS 变更时 — 用 --diff globals.css；
• 用户要求在安装前审查第三方注册表代码时 — 用 --view 检查源码。

add --dry-run 与 view 的区别：当用户想预览对自身项目的变更时，优先 npx shadcn@latest add --dry-run/--diff/--view。view 只显示注册表的原始元数据；add --dry-run 则展示在用户项目中真正会发生的事——解析后的文件路径、与现有文件的 diff、CSS 更新。只有当用户想在无项目上下文时浏览注册表信息，才使用 view。

其他 add 源码行为：在未初始化（无 components.json）的项目中直接 add 时，CLI 会引导补跑一次 init 流程而不是直接失败（add.ts）；安装 registry:style / registry:theme 这类会覆盖 CSS 变量与组件的条目时，CLI 会先弹出警告确认（add.ts）；--all 会拉取注册表索引并过滤掉当前 base 下不可选/已弃用的组件。

Smart Merge（来自上游的智能合并）

完整的组件更新工作流（先 diff、再逐文件审查、保留本地改动地合并上游更新）见 skills/shadcn/SKILL.md 中的 "Updating Components" 一节。核心思想是：用 add <component> --diff 对比上游与本地差异，逐文件确认后再执行覆盖式安装，避免丢失本地定制。

search — 搜索注册表

npx shadcn@latest search [registries...] [options]

跨注册表进行模糊搜索，list 是 search 的别名（源码中 .alias("list")，见 packages/shadcn/src/commands/search.ts）。支持命名空间（@acme）、公开的 GitHub 注册表源（owner/repo）以及注册表目录 URL。不传 -q 时列出全部条目；不传任何注册表时，搜索 components.json 中配置的所有注册表。

Flag	短选项	说明	默认值
--query <query>	-q	搜索关键词	—
--type <type>	-t	按条目类型过滤（如 ui、block、hook），逗号分隔多个	—
--limit <number>	-l	显示的最大条目数	100
--offset <number>	-o	跳过的条目数	0
--json	—	以 JSON 输出	false
--cwd <cwd>	-c	工作目录	当前目录

源码行为补充：--type 的值会先对照 SEARCHABLE_TYPES 校验，未知类型会明确报错并打印合法类型列表，而不是静默返回空结果（search.ts）。此外，"搜索所有已配置注册表"模式下单个注册表失败会被容忍并汇总到 results.errors（--json 模式下机器可读），只有全部注册表都失败时才以非零码退出（search.ts）。

view、docs 与 diff

view — 查看条目详情

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

显示条目信息（含文件内容）。示例：

npx shadcn@latest view @shadcn/button
npx shadcn@latest view owner/repo/item

view 只输出注册表的原始元数据，适合"无项目上下文的浏览"；需要评估对本地项目的影响时请改用 add --dry-run/--diff/--view（见上文）。

docs — 获取组件文档 URL

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

输出组件文档、示例与 API 参考的解析后 URL，接受一个或多个组件名，拿到 URL 后自行抓取内容即可。npx shadcn@latest docs input button 的输出形如：

base  radix

input
  docs      https://ui.shadcn.com/docs/components/radix/input
  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx

button
  docs      https://ui.shadcn.com/docs/components/radix/button
  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx

部分组件会附带一个指向底层库的 api 链接（例如 command 组件指向 cmdk）。

diff — 检查更新（不推荐使用）

技能文档明确：不要使用独立的 diff 命令，改用 npx shadcn@latest add --diff——后者能结合项目上下文输出解析后的路径与文件级 diff。

info — 项目信息

npx shadcn@latest info [options]

显示项目信息与 components.json 配置。在动手改项目前先运行 info，以了解项目的框架、别名、Tailwind 版本和解析后的路径。

Flag	短选项	说明	默认值
--cwd <cwd>	-c	工作目录	当前目录

Project Info 字段：

字段	类型	含义
framework	string	检测到的框架（next、vite、react-router、start 等）
frameworkVersion	string	框架版本（如 15.2.4）
isSrcDir	boolean	项目是否使用 src/ 目录
isRSC	boolean	是否启用 React Server Components
isTsx	boolean	项目是否使用 TypeScript
tailwindVersion	string	"v3" 或 "v4"
tailwindConfigFile	string	Tailwind 配置文件路径
tailwindCssFile	string	全局 CSS 文件路径
aliasPrefix	string	import 别名前缀（如 @、~、@/）
packageManager	string	检测到的包管理器（npm、pnpm、yarn、bun）

Components.json 字段：

字段	类型	含义
base	string	基础库（radix 或 base）——决定组件 API 与可用 props
style	string	视觉风格（如 nova、vega）
rsc	boolean	配置中的 RSC 标志
tsx	boolean	TypeScript 标志
tailwind.config	string	Tailwind 配置路径
tailwind.css	string	全局 CSS 路径——自定义 CSS 变量就写在这里
iconLibrary	string	图标库——决定图标 import 包（如 lucide-react、@tabler/icons-react）
aliases.components	string	组件 import 别名（如 @/components）
aliases.utils	string	工具函数 import 别名（如 @/lib/utils）
aliases.ui	string	UI 组件别名（如 @/components/ui）
aliases.lib	string	Lib 别名（如 @/lib）
aliases.hooks	string	Hooks 别名（如 @/hooks）
resolvedPaths	object	各别名对应的绝对文件系统路径
registries	object	已配置的自定义注册表

Links 字段：info 的输出还包含一个 Links 部分，提供组件文档、源码、示例的模板化 URL；需要解析后的具体 URL 时，请使用 npx shadcn@latest docs <component>。

build — 构建自定义注册表

npx shadcn@latest build [registry] [options]

将 registry.json 构建为可分发的独立 JSON 文件。默认输入 ./registry.json，默认输出 ./public/r。

Flag	短选项	说明	默认值
--output <path>	-o	输出目录	./public/r
--cwd <cwd>	-c	工作目录	当前目录

本仓库即是一个活例子：apps/v4/registry.json 是注册表源定义，apps/v4/public/r/ 下是构建产物（数百个组件 JSON 文件）。编写规则、include、条目定义、registryDependencies 与 GitHub 注册表行为，见 skills/shadcn/registry.md。

模板（Templates）

值	框架	支持 monorepo
next	Next.js	是
vite	Vite	是
start	TanStack Start	是
react-router	React Router	是
astro	Astro	是
laravel	Laravel	否

所有模板都支持通过 --monorepo flag 搭建 monorepo 项目。传入该 flag 时，CLI 使用对应的 monorepo 模板目录（如 next-monorepo、vite-monorepo）；两者都未传时交互式询问。Laravel 不支持 monorepo 脚手架。

仓库根目录的 templates/ 目录下可以看到真实模板项目：next-app、next-monorepo、vite-app、vite-monorepo、react-router-app、react-router-monorepo、astro-app、astro-monorepo、start-app、start-monorepo，命名与上表的 monorepo 后缀规则一一对应。

预设（Presets）的三种指定方式

通过 --preset 指定预设的三种形式：

1. 命名预设：--preset nova 或 --preset lyra
2. Preset code：--preset a2r6bw（带版本前缀的 base62 字符串，例如 a2r6bw 或 b0）
3. URL：--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."

重要：永远不要试图手动解码、抓取或解析 preset code。Preset code 是不透明的（opaque）——直接传给 npx shadcn@latest init --preset <code>，由 CLI 完成解析。对已有项目覆盖预设时用 npx shadcn@latest apply --preset <code>。

源码印证：init/apply 均通过 packages/shadcn/src/preset/preset.ts 提供的 isPresetCode / decodePreset 处理 code（见 init.ts）。一个关键细节是 preset code 不编码 base：decodePreset 解出的字段缺少 base 时，CLI 会用当前项目/交互结果中的 base 补齐后再生成 init URL（init.ts），这解释了下文"临时目录需显式传 --base"的原因。

切换预设的工作流

切换预设前，先询问用户：对已有组件是 overwrite、merge 还是 skip？

• Overwrite / Re-install → npx shadcn@latest apply --preset <code>。用新预设风格覆盖所有检测到的组件文件。适用于用户尚未定制组件的场景。
• Merge → npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 获取已安装组件列表，再用 SKILL.md 的 smart merge 工作流逐个更新，保留本地改动。适用于用户已定制组件的场景。
• Skip → npx shadcn@latest init --preset <code> --force --no-reinstall。只更新配置与 CSS 变量，现有组件保持不动。

两条硬性约束：预设命令必须始终在用户项目目录内运行；apply 只能在存在 components.json 的已有项目中使用。CLI 会自动从 components.json 保留当前 base（base vs radix）；如果必须在 scratch/临时目录中运行（例如做 --dry-run 对比），请显式传 --base <current-base>——因为 preset code 本身不编码 base。

命令速查

场景	命令
新建/初始化项目	npx shadcn@latest init -t next 或 init --defaults
创建 monorepo 项目	npx shadcn@latest init -t next --monorepo --name my-app
覆盖已有项目预设	npx shadcn@latest apply --preset <code>
添加组件	npx shadcn@latest add button
预览添加变更	npx shadcn@latest add button --dry-run / --diff / --view
搜索注册表	npx shadcn@latest search -q table 或 list
查看条目详情	npx shadcn@latest view @shadcn/button
获取文档 URL	npx shadcn@latest docs button input
诊断项目	npx shadcn@latest info
构建自定义注册表	npx shadcn@latest build -o ./public/r

适用前提：以上命令与 flag 以当前仓库 skills/shadcn/cli.md 技能文档及 packages/shadcn 源码为准；@latest 版本能力可能随上游发布演进，重要变更前建议先用 --dry-run 验证。