Skip to content
Nimbus

CLI

使用 nimbus-docs CLI 安装注册表功能、迁移包 API、审查复制的代码以及检查内容。

更新于 查看 Markdown

nimbus-docs CLI 可以列出注册表中的内容、安装它们、在 nimbus.json 中记录你拥有的组件、显示哪些内容落后于上游版本，以及对 MDX 内容进行检查。

nimbus-docs list

列出所有可安装的组件、工具和功能。

npx @cloudflare/nimbus-docs list

按类型筛选：

npx @cloudflare/nimbus-docs list --type ui
npx @cloudflare/nimbus-docs list --type lib
npx @cloudflare/nimbus-docs list --type feature

运行 nimbus-docs add 时不指定 slug 也会显示相同的列表。

nimbus-docs add <slug>

注册表条目根据类型使用两种安装模式。特殊的 adapter-<id> slug 使用第三种流程来重写项目配置。

组件和工具

对于 registry:ui 和 registry:lib 类型的 slug，CLI 会解析依赖项，将文件复制到你的仓库中，并安装所需的 npm 包。

npx @cloudflare/nimbus-docs add badge

解析依赖项

遍历 slug 的 registryDependencies 及其所需的 npm dependencies。

复制文件

将每个文件放到 src/components/ui/、src/lib/ 或条目声明的对应路径下。

更新 package.json

如果 npm 依赖项尚不存在，则添加它们。

如果组件已经安装，add 会保留你的副本——它永远不会覆盖你拥有的文件。传入 --overwrite 可以用注册表版本替换它们（即升级路径）；使用 git diff 审查变更：

npx @cloudflare/nimbus-docs add badge --overwrite

对于 add，--yes 会同意依赖安装等提示，但仍会保留现有文件。只有当你确实想「替换我的文件」时才使用 --overwrite。

安装完成后，组件就存在于你的仓库中了。你可以自由编辑——不存在上游 API 被破坏的风险。每次 add 还会在你的 nimbus.json 中追加一条记录——slug、来源注册表、注册表版本以及内容哈希——以便后续升级时可以追踪你拥有的内容。

功能

对于 registry:feature 类型的 slug，不需要复制任何文件。功能配方是一个 markdown 提示，智能体会读取它、适配你的项目并应用。

npx @cloudflare/nimbus-docs add 404-page

如果 CLI 检测到环境中存在编码智能体，它会将配方输出到 stdout 供智能体使用。否则它会打印管道指令，你可以自行运行：

npx @cloudflare/nimbus-docs add 404-page --print | claude
npx @cloudflare/nimbus-docs add 404-page --print | codex

使用 --print 可以强制输出 markdown，跳过检测。

服务器适配器

对于 adapter-cloudflare、adapter-vercel、adapter-netlify 和 adapter-node，CLI 会安装 Astro 适配器并重写 astro.config 中标记的 output 块。它会拒绝替换不同的适配器或非字面量的 output 值。

npx @cloudflare/nimbus-docs add adapter-cloudflare

当 Nimbus 配置中没有显式的渲染策略时，adapter-cloudflare 会添加请求渲染。现有策略会被保留；导入或模糊的配置会收到编码智能体的交接指令，而不是投机性重写。当不存在 wrangler.jsonc 时，命令会创建一个服务器兼容的配置文件，或者替换未修改的 Nimbus 静态配置；自定义的 JSONC 以及替代的 JSON/TOML 配置不会被改动。

完成适配器安装后，预期结果如下：

const nimbusConfig = defineNimbusConfig({
  rendering: { default: "request" },
  // ...
});

export default defineConfig({
  output: "server",
  adapter: cloudflare({ prerenderEnvironment: "node" }),
  integrations: [nimbus(nimbusConfig)],
});

当命令在检测到的编码智能体中运行时，它会输出版本化的配方，以便智能体可以安全地适配项目拥有或分离的配置。在普通 shell 中，使用 --print 显式请求该配方：

npx @cloudflare/nimbus-docs add adapter-cloudflare --print | claude

之后务必运行项目的生产构建。参阅渲染策略了解按集合的构建/请求覆盖。

等效的长格式为 nimbus-docs add server-output --adapter <cloudflare|vercel|netlify|node>。

nimbus-docs init

为缺少 nimbus.json 的项目创建该文件——适用于在记录机制存在之前搭建的仓库、正在采用 Nimbus 的现有 Astro 站点，或记录被删除的情况。全新搭建的项目已有该文件，因此 init 是所有其他操作的入口。

npx @cloudflare/nimbus-docs init

它会扫描你已安装的组件，将每个组件与注册表匹配，并写入可恢复的内容——只标记，从不猜测：

  • matched — 与注册表副本完全一致。
  • modified — 你已编辑过；记录保留来源身份，以便升级时仍可比较。
  • hand-authored — 你自行编写的，不来自注册表。

启动版本、templates-v* 标签以及之前审查的 Nimbus 版本无法仅从仓库中恢复，因此留空（标记为 reconstructed）。使用 migrate --from <version> 来建立升级范围。

# 扫描嵌套包（monorepo）
npx @cloudflare/nimbus-docs init --root packages/docs
# 重建现有记录
npx @cloudflare/nimbus-docs init --force

保持更新

包管理器负责更新 Nimbus 本身；Nimbus 负责更新已知的 API 用法并审查复制的代码：

pnpm up @cloudflare/nimbus-docs --latest
pnpm exec nimbus-docs migrate
pnpm exec nimbus-docs outdated

nimbus-docs migrate

汇总项目 lastReviewedNimbusVersion 与已安装 Nimbus 版本之间的所有已声明的破坏性变更。它会显示静态证明安全的编辑的完整 diff，以及其余内容的有界审查任务。自定义或模糊的代码绝不会被强制修改。

没有审查基线的现有项目必须提供上次完成迁移的精确 Nimbus 版本：

pnpm exec nimbus-docs migrate --from PREVIOUS_VERSION

使用 --dry-run 或 --diff 获取只读计划，--yes --json 用于智能体安全的应用循环，--print 用于自包含的 Markdown 交接。可以通过 --src-dir <relative-dir> 显式提供计算得出的 Astro srcDir。

Nimbus 仅在识别来源且能证明变更安全时才应用编辑。自定义或模糊的代码保持不变，并作为审查任务返回。migrate --print 会为任何智能体或工作流输出该任务；Nimbus 本身不会启动智能体。

迁移输出包括选定的版本范围、需要审查的内容、计划的 diff、阻塞项和错误。报告扫描边界之外的文件不会被标记为已检查。

标记为可选的升级条目出现在 migrate 的必需工作之后，以及 outdated 的包 API 信息性说明中。它们描述了每个现有站点都可以跳过而不影响构建或输出的改进，因此不会阻止构建。当你准备好时，运行 migrate --yes 将它们记录为已审查。

完成所有报告的工作后，显式确认并推进已提交的审查基线：

pnpm exec nimbus-docs migrate --from PREVIOUS_VERSION --yes

仅当项目没有记录的基线时才需要重复 --from。干净的交互式重新运行会在记录审查版本之前询问；智能体通过 --yes 提供该同意。Nimbus 不会在仍存在可检测迁移时记录完成状态。然后运行 outdated 审查用户拥有的启动器和注册表代码，接着运行 nimbus-docs check、astro check 和生产构建。migrate 的输出是按版本选择的升级指南。

nimbus-docs outdated

跨包 API、启动器文件和注册表组件的只读「我是否落后？」概览：

npx @cloudflare/nimbus-docs outdated
  • 包 API — 将待处理的源迁移和按版本选择的审查指向 migrate。
  • 注册表组件 — 将每个记录的内容哈希与当前注册表进行比较，并分类记录的本地占用。注册表更新仍为仅审查状态，因为覆盖也可能影响依赖项。
  • 启动器文件 — 将你搭建的文件与上游 templates-v* 标签进行比较，包括新增和删除。因为这些文件来自从未出现在你 git 历史中的标签，普通的 git diff 无法显示这些差异。内容文件默认隐藏（--all 可包含它们）。

传入 --json 获取确定性的智能体可读结果。没有完整 nimbus.json 来源信息的项目仍然会收到包 API 结果以及明确的部分覆盖结果。

nimbus-docs diff [file]

启动器文件的只读详情——你改了什么，以及上游改了什么：

# 每个已更改的启动器文件
npx @cloudflare/nimbus-docs diff
# 单个文件
npx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro

每个文件属于以下状态之一：可拉取（上游有变更，你没有）、上游新增/删除、手动合并（双方都有变更）或你的变更（你编辑过，上游没有）。对于可拉取的更新、新增和删除，你可以让 CLI 应用一个已审查的变更：

npx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro --apply

--apply 是显式的、按文件操作的，会拒绝符号链接/路径逃逸，并在写入前重新检查干净的原始状态或缺失状态——它永远不会合并。之后使用 git diff 审查。传入 --to <templates-vX.Y.Z> 可以针对特定标签，或传入 --template-dir <path> 与本地检出进行离线比较。

nimbus-docs lint

遍历 src/content/，运行你启用的每条编写规则，打印诊断信息，并在存在任何 error 严重级别的发现时以非零退出码退出。构建不受 lint 限制——未通过 lint 的草稿在 astro dev 下仍会渲染。

npx @cloudflare/nimbus-docs lint

标志——与 lint 组合使用：

标志 效果
--format=json 智能体可读的诊断信息
--rule=nimbus/single-h1 仅运行一条规则
--fix 原地应用自动修复
--quiet 仅显示错误，抑制警告

严重级别覆盖在集成中配置（nimbus(config, { rules })）；文件内禁用（nimbusDisableRules frontmatter、内联注释）无需配置即可生效。

帮助和版本

npx @cloudflare/nimbus-docs --help
npx @cloudflare/nimbus-docs --version
导航

输入以搜索…

↑↓ 导航↵ 选择Esc 关闭