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

Coolify 中的 shadcn CLI 完整命令参考init、apply、add、search 与预设机制解析【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文基于 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 shadcnlatest *), Bash(pnpm dlx shadcnlatest *), Bash(bunx --bun shadcnlatest *)由此引出两条必须遵守的执行铁律原文档加粗强调的部分始终使用项目自身的包管理器运行器npx shadcnlatest、pnpm dlx shadcnlatest或bunx --bun shadcnlatest根据项目上下文中的packageManager字段选择正确的一种。只使用文档中列出的参数禁止臆造 flag——某个 flag 没列出来就意味着它不存在。特别地CLI 会自动从项目的 lockfile 探测包管理器因此不存在--package-manager参数。与 Coolify 仓库的对应关系从 package.json 可见Coolify 前端使用tailwindcss4.3.3、tailwindcss/forms、tw-animate-css等依赖属于 Tailwind v4 技术栈。对这类项目执行npx shadcnlatest 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 shadcnlatest 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使用默认值等价于--templatenext --presetbase-novafalse--force-f强制覆盖已有配置false--cwd cwd-c工作目录当前目录--name name-n新建项目的名称—--silent-s静默输出false--rtl—启用 RTL 支持—--reinstall—重新安装已有的 UI 组件false--monorepo—搭建 monorepo 项目—--no-monorepo—跳过 monorepo 交互询问—补充说明npx shadcnlatest create是init的别名两者完全等价。--defaults是快速脚手架的捷径等价于--templatenext --presetnovabase 风格隐含。--monorepo/--no-monorepo与下文模板一节的 monorepo 支持联动既都不传时CLI 会交互式询问。典型用法摘自同目录 SKILL.md 的快速参考与本文命令表一一对应# 创建新项目命名预设。 npx shadcnlatest init --name my-app --preset base-nova # 创建新项目预设代码 vite 模板。 npx shadcnlatest init --name my-app --preset a2r6bw --template vite # 创建 monorepo 项目。 npx shadcnlatest init --name my-app --preset base-nova --monorepo # 在已有项目中初始化。 npx shadcnlatest init --preset base-nova # 使用默认值初始化。 npx shadcnlatest init --defaults四、apply—— 对已有项目应用预设npx shadcnlatest 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 shadcnlatest apply a2r6bw # 显式 --preset 形式。 npx shadcnlatest apply --preset a2r6bw五、add—— 安装组件与变更预演npx shadcnlatest 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 shadcnlatest add button --dry-run # 显示全部文件的 diff最多前 5 个。 npx shadcnlatest add button --diff # 显示指定文件的 diff。 npx shadcnlatest add button --diff button.tsx # 显示全部文件内容最多前 5 个。 npx shadcnlatest add button --view # 显示指定文件的完整内容。 npx shadcnlatest add button --view button.tsx # URL 来源同样适用。 npx shadcnlatest add registry-item-url --dry-run # 公开的 GitHub 注册表同样适用。 npx shadcnlatest add owner/repo/item --dry-run # CSS 差异。 npx shadcnlatest 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 shadcnlatest add component --dry-run—— 查看受影响的全部文件对每个文件执行npx shadcnlatest add component --diff file—— 对比上游与本地的差异按 diff 逐文件决策无本地改动 → 可安全覆盖有本地改动 → 读取本地文件、分析 diff、在保留本地修改的前提下应用上游更新用户明确表示全部更新 → 才可用--overwrite但必须先确认未经用户明确批准绝不使用--overwrite。红线同样是禁止手工从 GitHub 抓取原始文件——注册表解析、文件路径与 CSS diff 全部由 CLI 处理。六、search—— 搜索注册表npx shadcnlatest search [registries...] [options]跨注册表模糊搜索别名npx shadcnlatest 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 shadcnlatest search shadcn -q sidebar npx shadcnlatest search owner/repo -q login npx shadcnlatest search shadcn -q menu -t ui # 按类型过滤 npx shadcnlatest search # 搜索所有已配置注册表七、view与docs—— 条目详情与文档地址7.1view—— 查看条目详情npx shadcnlatest view items... [options]展示条目信息含文件内容。示例npx shadcnlatest view shadcn/button、npx shadcnlatest view owner/repo/item。再次强调选型边界view面向尚未安装、想先看看注册表里有什么的场景对已安装组件的项目级预演一律用add --diff/--view。7.2docs—— 获取组件文档 URLnpx shadcnlatest docs components... [options]输出组件的文档、示例、API 参考等解析后的 URL可一次传入多个组件名。拿到 URL 后再去抓取实际内容。原文档给出的示例输出形态如下以npx shadcnlatest docs input button为例URL 依项目实际解析结果为准base radix input docs 官方组件文档地址 examples 示例源码地址 button docs 官方组件文档地址 examples 示例源码地址部分组件会额外附带指向底层库如 command 组件对应的cmdk的api链接。SKILL.md 的工作流把docs定为硬性步骤创建、修复、调试或使用任何组件前先运行npx shadcnlatest docs component并抓取 URL确保依据的是正确 API 而不是猜测。7.3diff命令不推荐使用原文档对diff命令只留了一句话Do not use this command. Usenpx shadcnlatest add --diffinstead.——检查更新请统一走add --diff。八、info—— 项目信息探测首选命令npx shadcnlatest info [options]展示项目信息与components.json配置。原文档建议先运行info来发现项目的框架、别名、Tailwind 版本与解析后的路径再做任何其它操作。Flag短写说明默认值--cwd cwd-c工作目录当前目录8.1 Project Info 字段字段类型含义frameworkstring检测到的框架next、vite、react-router、start等frameworkVersionstring框架版本如15.2.4isSrcDirboolean项目是否使用src/目录isRSCboolean是否启用 React Server ComponentsisTsxboolean是否使用 TypeScripttailwindVersionstringv3或v4tailwindConfigFilestringTailwind 配置文件路径tailwindCssFilestring全局 CSS 文件路径aliasPrefixstring导入别名前缀如、~、/packageManagerstring探测到的包管理器npm、pnpm、yarn、bun这些字段直接决定后续命令的调用方式packageManager决定用npx/pnpm dlx/bunx --bun哪一种运行器tailwindVersion决定自定义颜色走theme inlinev4还是tailwind.config.jsv3——参考 customization.md 中Adding Custom Colors一节的两套注册写法。8.2 Components.json 字段字段类型含义basestring原语库radix或base——决定组件 API 与可用 propsstylestring视觉风格如nova、vegarscboolean配置中的 RSC 标记tsxbooleanTypeScript 标记tailwind.configstringTailwind 配置路径tailwind.cssstring全局 CSS 路径——自定义 CSS 变量就写在这里iconLibrarystring图标库——决定图标导入包如lucide-react、tabler/icons-reactaliases.componentsstring组件导入别名如/componentsaliases.utilsstringUtils 导入别名如/lib/utilsaliases.uistringUI 组件别名如/components/uialiases.libstringLib 别名如/libaliases.hooksstringHooks 别名如/hooksresolvedPathsobject各别名对应的绝对文件系统路径registriesobject已配置的自定义注册表其中tailwind.css是定制主题的唯一落点customization.md 明确要求永远编辑该文件而不是新建一个 CSS 文件iconLibrary则意味着不能假设项目一定用lucide-react第三方注册表组件的图标导入可能需要按项目实际图标库替换。8.3 Links 字段info输出中还包含一个Links段提供组件文档、源码、示例的模板化 URL。需要解析后的具体 URL 时改用npx shadcnlatest docs component。九、build—— 构建自定义注册表npx shadcnlatest build [registry] [options]把registry.json构建为一个个独立 JSON 文件用于分发。默认输入./registry.json默认输出./public/r。Flag短写说明默认值--output path-o输出目录./public/r--cwd cwd-c工作目录当前目录示例说明npx shadcnlatest build构建默认的./registry.jsonnpx shadcnlatest 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 shadcnlatest add acme/login-form --dry-run。一个值得注意的边界GitHub 注册表是源注册表被 CLI 直接消费不需要build只有自建的源注册表才需要构建为public/r下的 JSON 分发包详见 registry.md 的 GitHub Registries 一节。十、模板Templates取值框架Monorepo 支持nextNext.js是viteVite是startTanStack Start是react-routerReact Router是astroAstro是laravelLaravel否规则要点原文档完整保留所有模板均支持通过--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 lyraSKILL.md 中列出的命名预设还包括vega、maia、mira、luma预设代码--preset a2r6bw——带版本前缀的 base62 字符串如a2r6bw或b0预设 URL预设构建器生成的完整 URL形如?baseradixstylenova...的查询串。两条硬性纪律原文档加粗部分永远不要手工解码、抓取或解析预设代码。预设代码是不透明的opaque——直接把--preset code传给npx shadcnlatest init解析交给 CLI 完成。对已有项目覆盖预设时用npx shadcnlatest apply --preset code。十二、切换预设Switching Presets切换预设前必须先询问用户对已有组件采取overwrite覆盖、merge合并还是skip跳过策略命令适用场景覆盖 / 重装npx shadcnlatest apply --preset code用户没有自定义过组件——用新预设风格覆盖所有检测到的组件文件合并npx shadcnlatest init --preset code --force --no-reinstall随后运行npx shadcnlatest info拿到已安装组件列表再按 Smart Merge 工作流 逐个更新用户已自定义组件——逐组件--dry-run--diff保留本地修改跳过npx shadcnlatest init --preset code --force --no-reinstall只更新配置与 CSS 变量已有组件原样保留三条收尾约束预设命令必须运行在用户项目目录内apply仅对存在components.json的已有项目有效。CLI 会自动从components.json保留当前的basebasevsradix。若因--dry-run对比等原因必须使用临时/空白目录请显式传--base current-base——预设代码并不编码 base 信息。十三、小结一条可复用的操作主线把全文串起来一个典型的 shadcn 工作流是npx shadcnlatest info—— 探测框架、别名、Tailwind 版本、包管理器一切判断的起点npx shadcnlatest search -q 关键词—— 先查注册表避免重复造轮子npx shadcnlatest docs component—— 抓取文档与示例 URL确认 APInpx shadcnlatest 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 中深入。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考