shadcn CLI 完全参考：init/add/apply 等全部命令与 preset 切换实战（remeda 文档站实践）

• 开发工具

本篇以 remeda 仓库内.agents/skills/shadcn/cli.md为骨架，完整梳理 shadcn CLI 的每个命令、全部 flag 及默认值、模板与预设机制，并对照仓库中 remeda 官方文档站（packages/docs，Astro + shadcn/ui 构建）的真实配置，给出可直接落地的实战命令与底层原理。读完你将掌握：如何用init/create初始化或创建项目、用add加组件（含--dry-run/--diff/--view预览机制）、用apply切换主题预设、用info读取项目上下文，以及如何在 overwrite / merge / skip 三种策略之间做出正确选择。

1. 配置来源与命令运行前提

1.1 配置从components.json读取

shadcn CLI 的一切配置都来源于项目根目录的components.json文件。该文件声明了样式、别名、图标库、Tailwind 路径等信息，CLI 在执行add、apply、info等命令时会自动读取并据此解析目标路径。

remeda 仓库中 packages/docs/components.json 就是一个真实示例：

{ "$schema": "https://ui.shadcn.com/schema.json", "style": "new-york", "rsc": false, "tsx": true, "tailwind": { "config": "", "css": "src/styles/global.css", "baseColor": "slate", "cssVariables": true, "prefix": "" }, "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" }, "iconLibrary": "lucide" }

可以看到，文档站的别名体系为@/components、@/components/ui、@/lib/utils，图标库为lucide，全局 CSS 文件是src/styles/global.css。这些字段与下文的info命令输出一一对应，是理解后续所有命令行为的前提。

1.2 两条铁律

原文档对命令执行方式给出了两条强制约束，任何使用者都应遵守：

1. 始终使用项目自身的包管理器运行命令：根据项目上下文的packageManager字段选择npx shadcn@latest、pnpm dlx shadcn@latest或bunx --bun shadcn@latest。下文示例统一使用npx shadcn@latest，请在实际项目中替换为正确的 runner。remeda 文档站的devDependencies中直接依赖了"shadcn": "^4.19.0"（见 packages/docs/package.json），因此在文档站目录内可以直接运行本地 shadcn 命令。
2. 只使用下文列出的 flag，禁止自行发明或猜测：文档没有列出的 flag 就不存在。特别地，CLI 会从项目的 lockfile 自动检测包管理器，不存在--package-manager这个 flag。

2. 命令详解

CLI 提供的命令包括：init、apply、add（dry-run / smart merge）、search、view、docs、info、build。下面逐一展开。

2.1init— 初始化或创建项目

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

在既有项目中初始化 shadcn/ui，或在提供--name时创建全新项目，并可选择在同一命令中安装组件。

注意：npx shadcn@latest create是npx shadcn@latest init的别名。

快速创建新项目示例（源自 SKILL.md 的 Quick Reference）：

# 创建新项目。 npx shadcn@latest init --name my-app --preset base-nova npx shadcn@latest init --name my-app --preset a2r6bw --template vite # 创建 monorepo 项目。 npx shadcn@latest init --name my-app --preset base-nova --monorepo npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo # 初始化既有项目。 npx shadcn@latest init --preset base-nova npx shadcn@latest init --defaults # 快捷方式：--template=next --preset=nova（base 样式隐含）

2.2apply— 将预设应用到既有项目

npx shadcn@latest apply [preset] [options]

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

要点：

• 位置参数[preset]是--preset <preset>的简写；两者同时提供时必须一致。
• 若未提供预设，CLI 会主动邀请打开ui.shadcn.com/create上的自定义预设构建器。
• apply只适用于已存在components.json的既有项目，命令必须在用户项目目录内执行。
• CLI 会自动保留components.json中当前的 base（base还是radix）；如果必须在临时/草稿目录中执行（例如做--dry-run对比），需要显式传--base <current-base>—— 因为preset code 本身不编码 base。

2.3add— 添加组件

重要：要对比本地组件与上游差异、或预览改动，始终使用npx shadcn@latest add <component> --dry-run、--diff或--view。绝不手动从 GitHub 等来源拉取原始文件——CLI 会自动处理 registry 解析、文件路径与 CSS diff。

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

接受组件名、带 registry 前缀的名称（如@magicui/shimmer-button）、URL 或本地路径。

实际用法：

# 添加组件。 npx shadcn@latest add button card dialog npx shadcn@latest add @magicui/shimmer-button npx shadcn@latest add --all

Dry-Run 模式

--dry-run用于在不写任何文件的情况下预览add将要执行的操作；--diff与--view都隐含--dry-run。

# 预览全部改动。 npx shadcn@latest add button --dry-run # 显示所有文件的差异（前 5 个）。 npx shadcn@latest add button --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 # CSS 差异。 npx shadcn@latest add button --diff globals.css

何时使用 dry-run：

• 用户问"这个操作会添加哪些文件 / 会改动什么"→ 用--dry-run；
• 覆盖已有组件之前 → 先用--diff预览改动；
• 用户想查看组件源码但暂不安装 → 用--view；
• 想确认globals.css会有哪些 CSS 改动 → 用--diff globals.css；
• 安装第三方 registry 代码前想先审查/审计 → 用--view检查源码。

add --dry-run与view的区别：当用户要预览"对项目"的改动时，优先用npx shadcn@latest add --dry-run/--diff/--view，它展示的是真实会发生的事件：解析后的文件路径、与现有文件的 diff、CSS 更新。而npx shadcn@latest view只显示 registry 的原始元数据，仅在用户想脱离项目上下文浏览 registry 信息时使用。

Smart Merge from Upstream

更新已有组件时，若需在保留本地改动的前提下合并上游更新，采用"智能合并"工作流：先add --dry-run列出所有受影响文件，再对每个文件执行add --diff <file>逐文件决策（无本地改动可安全覆盖；有本地改动则读取本地文件、分析 diff、在保留本地修改的前提下应用上游更新）。完整流程见 SKILL.md 的 Updating Components 一节。绝不未经用户明确批准就使用--overwrite。

2.4search— 搜索 registry

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

跨 registry 模糊搜索，别名为npx shadcn@latest list。不带-q时列出全部条目。

示例：

npx shadcn@latest search @shadcn -q "sidebar" npx shadcn@latest search @tailark -q "stats"

remeda 文档站的组件选择原则也与此呼应：先搜索 registry 中是否已有组件，再决定是否手写自定义 UI（详见 SKILL.md）。

2.5view— 查看条目详情

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

显示条目信息（含文件内容）。示例：npx shadcn@latest view @shadcn/button。

2.6docs— 获取组件文档 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）。SKILL.md 强调：创建、修复、调试或使用组件时，务必先运行docs并抓取 URL，确保基于正确的 API 与用法模式，而不是猜测。

2.7diff— 检查更新（勿用）

不要使用这个命令，请改用npx shadcn@latest add --diff。

2.8info— 项目信息

npx shadcn@latest info [options]

显示项目信息与components.json配置。建议最先运行此命令，以发现项目的框架、别名、Tailwind 版本与解析路径。

Project Info 字段：

remeda 文档站的场景下，framework为astro、tailwindVersion为"v4"（依赖@tailwindcss/vite与tailwindcss@^4.3.3，见 packages/docs/package.json），tailwindCssFile为src/styles/global.css，aliasPrefix为@。

Components.json 字段：

Links 字段：info输出还包含一个Links区段，提供组件文档、源码和示例的模板化 URL；要获取已解析的 URL，改用npx shadcn@latest docs <component>。

remeda 文档站对这些字段的实际运用可以直接对照 packages/docs/components.json：iconLibrary: "lucide"对应依赖中的lucide-react，aliases.ui对应src/components/ui/目录（badge.tsx、button.tsx、card.tsx、dropdown-menu.tsx、scroll-area.tsx、sheet.tsx等 shadcn 组件均位于该目录），aliases.utils则对应 packages/docs/src/lib/utils.ts 中的cn()函数：

import { clsx, type ClassValue } from "clsx"; import { twMerge } from "tailwind-merge"; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }

cn()正是 shadcn 组件中用于条件类名合并的标准工具，对应 styling 规则 中"使用cn()做条件类"的强制要求。

2.9build— 构建自定义 registry

npx shadcn@latest build [registry] [options]

将registry.json构建为单个 JSON 文件以用于分发。默认输入./registry.json，默认输出./public/r。

3. Templates 模板

所有模板都支持通过--monorepoflag 进行 monorepo 脚手架：传入时，CLI 使用 monorepo 专用模板目录（如next-monorepo、vite-monorepo）。当--monorepo与--no-monorepo都未传入时，CLI 会交互式询问。Laravel 不支持 monorepo 脚手架。

值得说明的是，remeda 文档站本身就是 Astro 项目（packages/docs的构建脚本为astro build），这对应模板表中的astro模板；而文档站的 shadcn 组件（button.tsx、card.tsx等）以.tsx形式被.astro页面引用，体现了 Astro + shadcn/ui 的组合模式。

4. Presets 预设

通过--preset指定预设，共有三种形式：

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

已知命名预设：nova、vega、maia、lyra、mira、luma。

重要：绝不手动解码、抓取或解析 preset code。Preset code 是不透明的，直接传给npx shadcn@latest init --preset <code>让 CLI 自行解析即可。覆盖既有项目的预设时，使用npx shadcn@latest apply --preset <code>。

5. Switching Presets 切换预设

切换预设前必须询问用户：对已有组件执行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获取已安装组件列表，然后逐一使用 smart merge 工作流 更新，以保留本地改动。适用于用户已自定义组件的情况。
• Skip（跳过）→npx shadcn@latest init --preset <code> --force --no-reinstall。只更新配置与 CSS 变量，已有组件保持原样。

实际命令：

# 将预设应用到既有项目。 npx shadcn@latest apply --preset a2r6bw npx shadcn@latest apply a2r6bw # 仅更新部分预设（theme/font，可逗号组合；icon 有意不支持）。 npx shadcn@latest apply --preset a2r6bw --only theme npx shadcn@latest apply --preset a2r6bw --only font npx shadcn@latest apply --preset a2r6bw --only theme,font # 保留已有组件的切换（skip 策略）。 npx shadcn@latest init --preset nova --force --no-reinstall

三条硬性前提：

1. 预设命令始终在用户项目目录内执行；
2. apply只对存在components.json的既有项目生效；
3. CLI 自动保留components.json中的当前 base（basevsradix）；若必须在临时目录操作（如--dry-run对比），需显式传--base <current-base>，因为 preset code 不编码 base。

SKILL.md 还补充了一个partial策略：npx shadcn@latest apply --preset <code> --only theme,font，只更新选中部分而不重装 UI 组件。icon刻意不支持--only，因为图标变更可能要求完整重装组件并做转换（见 SKILL.md 第 9 步工作流）。

6. 主题定制与 CSS 变量（配套能力）

切换预设之外，直接编辑 CSS 变量也能改主题。remeda 文档站的 packages/docs/src/styles/global.css 就是 shadcn 主题 CSS 变量的完整落地实例，其中:root（浅色）部分示例：

:root { --background: oklch(1 0 0); --foreground: oklch(0.129 0.042 264.695); --card: oklch(1 0 0); --primary: oklch(0.546 0.2153 262.87); --muted: oklch(0.968 0.007 247.896); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.929 0.013 255.508); --input: oklch(0.929 0.013 255.508); --ring: oklch(0.869 0.022 252.894); --chart-1: oklch(0.646 0.222 41.116); --radius: 0.625rem; --sidebar: oklch(0.984 0.003 247.858); }

这印证了 CLI 文档中的关键机制：颜色使用 OKLCH 格式（oklch(亮度 色度 色相)），采用name/name-foreground约定（base 变量用于背景，-foreground用于该背景上的文字/图标），--radius全局控制圆角（组件据此派生rounded-lg=var(--radius)、rounded-md=calc(var(--radius) - 2px)）。组件通过 Tailwind 语义工具类（bg-primary、text-muted-foreground）引用这些变量——修改变量即可全局改变所有引用它的组件。完整变量表与深浅色切换、Tailwind v3/v4 注册自定义颜色的方法见 customization.md。

7. 关联参考资源

本 CLI 文档是.agents/skills/shadcn/技能包的一部分，配套资料可进一步深化使用：

• SKILL.md — 组件使用原则、关键模式、组件选择表、完整工作流（含 smart merge 更新流程）；
• rules/styling.md — 语义色、variant、className、间距、size、truncate、暗色模式、cn()、z-index 的正确/错误写法；
• rules/forms.md — FieldGroup/Field/InputGroup/ToggleGroup/FieldSet 与校验态；
• rules/composition.md — Groups、overlays、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 加载态；
• rules/icons.md —data-icon、图标尺寸、图标以对象而非字符串传递；
• rules/base-vs-radix.md —asChildvsrender、Select/ToggleGroup/Slider/Accordion 两套 API 差异；
• customization.md — 主题、CSS 变量、扩展组件；
• mcp.md — CLI 内置的 MCP 服务器（shadcn mcp/shadcn mcp init），支持 AI 助手搜索、浏览、查看与安装组件。

这些文件与本文档共同构成一套完整的 shadcn/ui 工程化指南：本文档负责"命令与参数"，SKILL.md 负责"使用原则与工作流"，rules 目录负责"代码写法规范"。remeda 文档站的 packages/docs/components.json 与 packages/docs/src/styles/global.css 则是这套体系在真实项目中的落地样本，可作为理解配置与输出之间对应关系的第一手参照。

• 开发工具