Coolify 中的 shadcn CLI 完整命令参考:init、apply、add、search 与预设机制解析

原创2026-09-06 10:46:271,941 阅读
文章标签:云原生DevOpsCI/CD容器编排运维后端微服务MCP 服务

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 *)

由此引出两条必须遵守的执行铁律(原文档加粗强调的部分):

  1. 始终使用项目自身的包管理器运行器:npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest,根据项目上下文中的 packageManager 字段选择正确的一种。
  2. 只使用文档中列出的参数,禁止臆造 flag——某个 flag 没列出来,就意味着它不存在。特别地,CLI 会自动从项目的 lockfile 探测包管理器,因此不存在 --package-manager 参数。

与 Coolify 仓库的对应关系:从 package.json 可见,Coolify 前端使用 tailwindcss 4.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(原文档明确列出的五种场景):

  1. 用户问"这会添加哪些文件?"或"这会改动什么?"——用 --dry-run;
  2. 覆盖已有组件之前——先用 --diff 预演变更;
  3. 用户想在不安装的前提下审查组件源码——用 --view;
  4. 检查 globals.css 将发生哪些 CSS 变更——用 --diff globals.css;
  5. 安装前审查/审计第三方注册表代码——用 --view 检查源码。

一个重要的选型对照(原文档专门加粗):

当用户想预览对自己项目的影响时,优先 add --dry-run/--diff/--view,而不是 view 命令。view 只显示注册表的原始元数据;add --dry-run 则展示项目中真实会发生的事:解析后的文件路径、与现有文件的 diff、CSS 更新。只有当用户想脱离项目上下文浏览注册表信息时,才用 view。

5.2 与上游的 Smart Merge(智能合并)

当需要从上游更新组件同时保留本地修改时,原文档指向 SKILL.md 的 Updating Components 章节,其完整工作流为:

  1. npx shadcn@latest add <component> --dry-run —— 查看受影响的全部文件;
  2. 对每个文件执行 npx shadcn@latest add <component> --diff <file> —— 对比上游与本地的差异;
  3. 按 diff 逐文件决策:无本地改动 → 可安全覆盖;有本地改动 → 读取本地文件、分析 diff、在保留本地修改的前提下应用上游更新;用户明确表示"全部更新" → 才可用 --overwrite(但必须先确认);
  4. 未经用户明确批准,绝不使用 --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 有且仅有三种指定方式:

  1. 命名预设:--preset nova 或 --preset lyra(SKILL.md 中列出的命名预设还包括 vega、maia、mira、luma);
  2. 预设代码:--preset a2r6bw——带版本前缀的 base62 字符串(如 a2r6bw 或 b0);
  3. 预设 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 变量,已有组件原样保留

三条收尾约束:

  1. 预设命令必须运行在用户项目目录内;apply 仅对存在 components.json 的已有项目有效。
  2. CLI 会自动从 components.json 保留当前的 base(base vs radix)。
  3. 若因 --dry-run 对比等原因必须使用临时/空白目录,请显式传 --base <current-base>——预设代码并不编码 base 信息。

十三、小结:一条可复用的操作主线

把全文串起来,一个典型的 shadcn 工作流是:

  1. npx shadcn@latest info —— 探测框架、别名、Tailwind 版本、包管理器(一切判断的起点);
  2. npx shadcn@latest search -q "关键词" —— 先查注册表,避免重复造轮子;
  3. npx shadcn@latest docs <component> —— 抓取文档与示例 URL,确认 API;
  4. npx shadcn@latest add <component> --dry-run / --diff <file> —— 预演后再落地;
  5. 需要换主题时用 apply --preset <code>(无自定义)或 init --preset <code> --force --no-reinstall(保留自定义,走 merge 流程);
  6. 自建组件库时用 build 生成 public/r 分发包,或把仓库根 registry.json 直接作为 GitHub 源注册表。

以上所有命令与参数均以 cli.md 的原始文档为准;组件写法与主题定制细节可继续在 SKILL.md、customization.md 与 mcp.md 中深入。

登录后查看全文
coolify