Coolify 中的 shadcn CLI 完整命令参考:init、apply、add、search 与预设机制解析
Coolify 中的 shadcn CLI 完整命令参考:init、apply、add、search 与预设机制解析
本文基于 Coolify 仓库中随 Agent 技能(Skill)体系提交的 shadcn CLI 参考文档 cli.md,系统讲解 shadcn/ui 命令行工具的 8 个核心命令、全部参数表、模板与预设(Preset)体系。读完后,你能够独立完成项目初始化、组件安装、变更预演(dry-run)、注册表搜索与预设切换等完整工作流,并理解每条命令背后的项目上下文探测机制。
一、定位与执行约定
shadcn CLI 的定位是:把组件以源码形式复制到你的项目中(而非以 npm 包依赖形式引入),组件安装、注册表解析、文件路径改写与 CSS 差异合并全部由 CLI 代劳。CLI 的项目配置统一从 components.json 读取——这是判断一个项目是否已经 shadcn 化的标志文件。
在 Coolify 仓库中,该文档位于 .agents/skills/shadcn/cli.md,与 SKILL.md、registry.md、customization.md、mcp.md 共同构成一套面向 AI Agent 的 UI 组件管理规范。其中 SKILL.md 的前置元数据通过 allowed-tools 把可执行命令严格限定为三种包管理器运行器:
Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
由此引出两条必须遵守的执行铁律(原文档加粗强调的部分):
- 始终使用项目自身的包管理器运行器:
npx shadcn@latest、pnpm dlx shadcn@latest或bunx --bun shadcn@latest,根据项目上下文中的packageManager字段选择正确的一种。 - 只使用文档中列出的参数,禁止臆造 flag——某个 flag 没列出来,就意味着它不存在。特别地,CLI 会自动从项目的 lockfile 探测包管理器,因此不存在
--package-manager参数。
与 Coolify 仓库的对应关系:从 package.json 可见,Coolify 前端使用
tailwindcss4.3.3、@tailwindcss/forms、tw-animate-css等依赖,属于 Tailwind v4 技术栈。对这类项目执行npx shadcn@latest info时,tailwindVersion字段会返回"v4",后续的主题定制方式(@theme inline还是tailwind.config.js)须以此为准。此外,由于 Coolify 本身是 Laravel 项目,下文的laravel模板对其具有直接意义。归档测试代码 V5FrontendSourceContractTest.php.txt 中也存在读取base_path('components.json')的断言,从源码结构看可以确认 Coolify 前端曾/正在按 shadcn 约定组织组件。
二、命令总览
| 命令 | 用途 | 一句话说明 |
|---|---|---|
init |
初始化或创建项目 | 已有项目中初始化 shadcn,或用 --name 新建项目 |
apply |
对已有项目应用预设 | 覆盖预设驱动的配置、字体、CSS 变量与已检测到的组件 |
add |
安装组件 | 支持 dry-run、diff、view 三种预演模式 |
search |
模糊搜索注册表 | 亦可通过 list 别名调用 |
view |
查看条目详情 | 含完整文件内容 |
docs |
获取组件文档 URL | 输出文档、示例与 API 参考地址 |
info |
项目信息 | 首选的上下文探测命令 |
build |
构建自定义注册表 | 把 registry.json 拆分为可分发的 JSON 文件 |
diff |
检查更新 | 已标记为不要使用,改用 add --diff |
三、init —— 初始化或创建项目
npx shadcn@latest init [components...] [options]
在已有项目中初始化 shadcn/ui,或在提供 --name 时创建一个全新项目;可选地在同一步骤中安装组件。
完整参数表(继承自原文档,未作删减):
| Flag | 短写 | 说明 | 默认值 |
|---|---|---|---|
--template <template> |
-t |
模板(next、start、vite、next-monorepo、react-router) | — |
--preset [name] |
-p |
预设配置(命名、代码或 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 交互询问 | — |
补充说明:
npx shadcn@latest create是init的别名,两者完全等价。--defaults是快速脚手架的捷径:等价于--template=next --preset=nova(base 风格隐含)。--monorepo/--no-monorepo与下文"模板"一节的 monorepo 支持联动:既都不传时,CLI 会交互式询问。
典型用法(摘自同目录 SKILL.md 的快速参考,与本文命令表一一对应):
# 创建新项目(命名预设)。
npx shadcn@latest init --name my-app --preset base-nova
# 创建新项目(预设代码 + vite 模板)。
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 --preset base-nova
# 使用默认值初始化。
npx shadcn@latest init --defaults
四、apply —— 对已有项目应用预设
npx shadcn@latest apply [preset] [options]
将预设应用到已有项目,会覆盖预设所驱动的配置、字体、CSS 变量,以及 CLI 检测到的 UI 组件。
| Flag | 短写 | 说明 | 默认值 |
|---|---|---|---|
--preset <preset> |
— | 预设配置(命名、代码或 URL) | — |
--yes |
-y |
跳过确认提示 | false |
--cwd <cwd> |
-c |
工作目录 | 当前目录 |
--silent |
-s |
静默输出 | false |
两个容易踩坑的细节:
[preset]位置参数是--preset <preset>的简写。若两者同时提供,取值必须一致,否则无法执行。- 未提供任何预设时,CLI 会提示打开自定义预设构建器(即 ui.shadcn.com 的 create 页面),而不是本地臆造一个预设。
apply 只在存在 components.json 的已有项目中有效——这是它与 init 的关键分界:init 可以创建项目,apply 只能改造已有项目。
# 位置参数简写。
npx shadcn@latest apply a2r6bw
# 显式 --preset 形式。
npx shadcn@latest apply --preset a2r6bw
五、add —— 安装组件与变更预演
npx shadcn@latest add [components...] [options]
add 的参数接受四种来源形式:组件名、带注册表前缀的名称(如 @magicui/shimmer-button)、GitHub 条目地址(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] |
— | 显示差异。不带 path 时显示前 5 个文件;带 path 时只显示该文件(隐含 --dry-run) |
— |
--view [path] |
— | 显示文件内容。不带 path 时显示前 5 个文件;带 path 时只显示该文件(隐含 --dry-run) |
— |
5.1 Dry-Run 模式
--dry-run 用于在不写任何文件的前提下预演 add 将做什么;--diff 与 --view 都隐含 --dry-run。原文档给出的完整示例集如下(URL 与 GitHub 地址形式均适用):
# 预演全部变更。
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 <registry-item-url> --dry-run
# 公开的 GitHub 注册表同样适用。
npx shadcn@latest add owner/repo/item --dry-run
# 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/--diff/--view,而不是view命令。view只显示注册表的原始元数据;add --dry-run则展示项目中真实会发生的事:解析后的文件路径、与现有文件的 diff、CSS 更新。只有当用户想脱离项目上下文浏览注册表信息时,才用view。
5.2 与上游的 Smart Merge(智能合并)
当需要从上游更新组件同时保留本地修改时,原文档指向 SKILL.md 的 Updating Components 章节,其完整工作流为:
npx shadcn@latest add <component> --dry-run—— 查看受影响的全部文件;- 对每个文件执行
npx shadcn@latest add <component> --diff <file>—— 对比上游与本地的差异; - 按 diff 逐文件决策:无本地改动 → 可安全覆盖;有本地改动 → 读取本地文件、分析 diff、在保留本地修改的前提下应用上游更新;用户明确表示"全部更新" → 才可用
--overwrite(但必须先确认); - 未经用户明确批准,绝不使用
--overwrite。
红线同样是:禁止手工从 GitHub 抓取原始文件——注册表解析、文件路径与 CSS diff 全部由 CLI 处理。
六、search —— 搜索注册表
npx shadcn@latest search [registries...] [options]
跨注册表模糊搜索,别名 npx shadcn@latest list。支持三类来源:命名空间(@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 |
工作目录 | 当前目录 |
典型用法:
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search @shadcn -q "menu" -t ui # 按类型过滤
npx shadcn@latest search # 搜索所有已配置注册表
七、view 与 docs —— 条目详情与文档地址
7.1 view —— 查看条目详情
npx shadcn@latest view <items...> [options]
展示条目信息(含文件内容)。示例:npx shadcn@latest view @shadcn/button、npx shadcn@latest view owner/repo/item。
再次强调选型边界:view 面向"尚未安装、想先看看注册表里有什么"的场景;对已安装组件的项目级预演,一律用 add --diff/--view。
7.2 docs —— 获取组件文档 URL
npx shadcn@latest docs <components...> [options]
输出组件的文档、示例、API 参考等解析后的 URL,可一次传入多个组件名。拿到 URL 后再去抓取实际内容。原文档给出的示例输出形态如下(以 npx shadcn@latest docs input button 为例,URL 依项目实际解析结果为准):
base radix
input
docs <官方组件文档地址>
examples <示例源码地址>
button
docs <官方组件文档地址>
examples <示例源码地址>
部分组件会额外附带指向底层库(如 command 组件对应的 cmdk)的 api 链接。
SKILL.md 的工作流把 docs 定为硬性步骤:创建、修复、调试或使用任何组件前,先运行 npx shadcn@latest docs <component> 并抓取 URL,确保依据的是正确 API 而不是猜测。
7.3 diff 命令(不推荐使用)
原文档对 diff 命令只留了一句话:"Do not use this command. Use npx shadcn@latest add --diff instead."——检查更新请统一走 add --diff。
八、info —— 项目信息探测(首选命令)
npx shadcn@latest info [options]
展示项目信息与 components.json 配置。原文档建议:先运行 info 来发现项目的框架、别名、Tailwind 版本与解析后的路径,再做任何其它操作。
| Flag | 短写 | 说明 | 默认值 |
|---|---|---|---|
--cwd <cwd> |
-c |
工作目录 | 当前目录 |
8.1 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 |
导入别名前缀(如 @、~、@/) |
packageManager |
string |
探测到的包管理器(npm、pnpm、yarn、bun) |
这些字段直接决定后续命令的调用方式:packageManager 决定用 npx / pnpm dlx / bunx --bun 哪一种运行器;tailwindVersion 决定自定义颜色走 @theme inline(v4)还是 tailwind.config.js(v3)——参考 customization.md 中"Adding Custom Colors"一节的两套注册写法。
8.2 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 |
图标库——决定图标导入包(如 lucide-react、@tabler/icons-react) |
aliases.components |
string |
组件导入别名(如 @/components) |
aliases.utils |
string |
Utils 导入别名(如 @/lib/utils) |
aliases.ui |
string |
UI 组件别名(如 @/components/ui) |
aliases.lib |
string |
Lib 别名(如 @/lib) |
aliases.hooks |
string |
Hooks 别名(如 @/hooks) |
resolvedPaths |
object |
各别名对应的绝对文件系统路径 |
registries |
object |
已配置的自定义注册表 |
其中 tailwind.css 是定制主题的唯一落点:customization.md 明确要求"永远编辑该文件,而不是新建一个 CSS 文件";iconLibrary 则意味着不能假设项目一定用 lucide-react,第三方注册表组件的图标导入可能需要按项目实际图标库替换。
8.3 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 |
工作目录 | 当前目录 |
| 示例 | 说明 |
|---|---|
npx shadcn@latest build |
构建默认的 ./registry.json |
npx shadcn@latest build registry.json --output public/r |
显式指定输入与输出 |
注册表的编写规则(include、item 定义、registryDependencies、GitHub 注册表行为与地址方案——button / @acme/button / owner/repo/item / URL / 本地文件等)全部在 registry.md 中定义。构建后可用 search / view / add --dry-run 自检结果,例如 npx shadcn@latest add @acme/login-form --dry-run。
一个值得注意的边界:GitHub 注册表是"源注册表",被 CLI 直接消费,不需要 build;只有自建的"源注册表"才需要构建为 public/r 下的 JSON 分发包(详见 registry.md 的 "GitHub Registries" 一节)。
十、模板(Templates)
| 取值 | 框架 | Monorepo 支持 |
|---|---|---|
next |
Next.js | 是 |
vite |
Vite | 是 |
start |
TanStack Start | 是 |
react-router |
React Router | 是 |
astro |
Astro | 是 |
laravel |
Laravel | 否 |
规则要点(原文档完整保留):
- 所有模板均支持通过
--monorepo进行 monorepo 脚手架搭建;传入该 flag 后,CLI 会使用 monorepo 专用模板目录(如next-monorepo、vite-monorepo)。 - 既未传
--monorepo也未传--no-monorepo时,CLI 会交互式询问。 laravel模板不支持 monorepo 脚手架——对 Coolify 这类 Laravel 项目而言,init --template laravel只能走单应用形态。
十一、预设(Presets)
--preset 有且仅有三种指定方式:
- 命名预设:
--preset nova或--preset lyra(SKILL.md 中列出的命名预设还包括vega、maia、mira、luma); - 预设代码:
--preset a2r6bw——带版本前缀的 base62 字符串(如a2r6bw或b0); - 预设 URL:预设构建器生成的完整 URL(形如
?base=radix&style=nova&...的查询串)。
两条硬性纪律(原文档加粗部分):
- 永远不要手工解码、抓取或解析预设代码。 预设代码是不透明的(opaque)——直接把
--preset <code>传给npx shadcn@latest init,解析交给 CLI 完成。 - 对已有项目覆盖预设时,用
npx shadcn@latest apply --preset <code>。
十二、切换预设(Switching Presets)
切换预设前必须先询问用户:对已有组件采取 overwrite(覆盖)、merge(合并) 还是 skip(跳过)?
| 策略 | 命令 | 适用场景 |
|---|---|---|
| 覆盖 / 重装 | npx shadcn@latest apply --preset <code> |
用户没有自定义过组件——用新预设风格覆盖所有检测到的组件文件 |
| 合并 | npx shadcn@latest init --preset <code> --force --no-reinstall,随后运行 npx shadcn@latest info 拿到已安装组件列表,再按 Smart Merge 工作流 逐个更新 |
用户已自定义组件——逐组件 --dry-run + --diff,保留本地修改 |
| 跳过 | npx shadcn@latest init --preset <code> --force --no-reinstall |
只更新配置与 CSS 变量,已有组件原样保留 |
三条收尾约束:
- 预设命令必须运行在用户项目目录内;
apply仅对存在components.json的已有项目有效。 - CLI 会自动从
components.json保留当前的base(basevsradix)。 - 若因
--dry-run对比等原因必须使用临时/空白目录,请显式传--base <current-base>——预设代码并不编码 base 信息。
十三、小结:一条可复用的操作主线
把全文串起来,一个典型的 shadcn 工作流是:
npx shadcn@latest info—— 探测框架、别名、Tailwind 版本、包管理器(一切判断的起点);npx shadcn@latest search -q "关键词"—— 先查注册表,避免重复造轮子;npx shadcn@latest docs <component>—— 抓取文档与示例 URL,确认 API;npx shadcn@latest add <component> --dry-run/--diff <file>—— 预演后再落地;- 需要换主题时用
apply --preset <code>(无自定义)或init --preset <code> --force --no-reinstall(保留自定义,走 merge 流程); - 自建组件库时用
build生成public/r分发包,或把仓库根registry.json直接作为 GitHub 源注册表。
以上所有命令与参数均以 cli.md 的原始文档为准;组件写法与主题定制细节可继续在 SKILL.md、customization.md 与 mcp.md 中深入。