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

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

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

<h2 id="nimbus-docs-list">`nimbus-docs list`</h2>

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

```sh
npx list
pnpm dlx list
yarn dlx list
bunx list
```

按类型筛选：

```sh
npx list --type ui
pnpm dlx list --type ui
yarn dlx list --type ui
bunx list --type ui
```
```sh
npx list --type lib
pnpm dlx list --type lib
yarn dlx list --type lib
bunx list --type lib
```
```sh
npx list --type feature
pnpm dlx list --type feature
yarn dlx list --type feature
bunx list --type feature
```

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

<h2 id="nimbus-docs-add-slug">`nimbus-docs add <slug>`</h2>

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

<h3 id="components-and-utilities">组件和工具</h3>

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

```sh
npx add badge
pnpm dlx add badge
yarn dlx add badge
bunx add badge
```

1. **解析依赖项**

   遍历 slug 的 `registryDependencies` 及其所需的 npm `dependencies`。
2. **复制文件**

   将每个文件放到 `src/components/ui/`、`src/lib/` 或条目声明的对应路径下。
3. **更新 package.json**

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

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

```sh
npx add badge --overwrite
pnpm dlx add badge --overwrite
yarn dlx add badge --overwrite
bunx add badge --overwrite
```

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

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

<h3 id="features">功能</h3>

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

```sh
npx add 404-page
pnpm dlx add 404-page
yarn dlx add 404-page
bunx add 404-page
```

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

```sh
npx add 404-page --print | claude
pnpm dlx add 404-page --print | claude
yarn dlx add 404-page --print | claude
bunx add 404-page --print | claude
```
```sh
npx add 404-page --print | codex
pnpm dlx add 404-page --print | codex
yarn dlx add 404-page --print | codex
bunx add 404-page --print | codex
```

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

<h3 id="server-adapters">服务器适配器</h3>

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

```sh
npx add adapter-cloudflare
pnpm dlx add adapter-cloudflare
yarn dlx add adapter-cloudflare
bunx add adapter-cloudflare
```

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

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

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

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

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

```sh
npx add adapter-cloudflare --print | claude
pnpm dlx add adapter-cloudflare --print | claude
yarn dlx add adapter-cloudflare --print | claude
bunx add adapter-cloudflare --print | claude
```

之后务必运行项目的生产构建。参阅[渲染策略](/configuration#rendering-policy)了解按集合的构建/请求覆盖。

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

<h2 id="nimbus-docs-init">`nimbus-docs init`</h2>

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

```sh
npx init
pnpm dlx init
yarn dlx init
bunx init
```

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

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

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

```sh
npx init --root packages/docs
pnpm dlx init --root packages/docs
yarn dlx init --root packages/docs
bunx init --root packages/docs
```
```sh
npx init --force
pnpm dlx init --force
yarn dlx init --force
bunx init --force
```

<h2 id="keeping-up-to-date">保持更新</h2>

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

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

<h3 id="nimbus-docs-migrate">`nimbus-docs migrate`</h3>

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

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

```sh
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` 将它们记录为已审查。

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

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

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

<h3 id="nimbus-docs-outdated">`nimbus-docs outdated`</h3>

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

```sh
npx outdated
pnpm dlx outdated
yarn dlx outdated
bunx outdated
```

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

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

<h3 id="nimbus-docs-diff-file">`nimbus-docs diff [file]`</h3>

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

```sh
npx diff
pnpm dlx diff
yarn dlx diff
bunx diff
```
```sh
npx diff src/components/ui/aside/Aside.astro
pnpm dlx diff src/components/ui/aside/Aside.astro
yarn dlx diff src/components/ui/aside/Aside.astro
bunx diff src/components/ui/aside/Aside.astro
```

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

```sh
npx diff src/components/ui/aside/Aside.astro --apply
pnpm dlx diff src/components/ui/aside/Aside.astro --apply
yarn dlx diff src/components/ui/aside/Aside.astro --apply
bunx diff src/components/ui/aside/Aside.astro --apply
```

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

<h2 id="nimbus-docs-lint">`nimbus-docs lint`</h2>

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

```sh
npx lint
pnpm dlx lint
yarn dlx lint
bunx lint
```

标志——与 `lint` 组合使用：

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

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

<h2 id="help-and-version">帮助和版本</h2>

```sh
npx --help
pnpm dlx --help
yarn dlx --help
bunx --help
```
```sh
npx --version
pnpm dlx --version
yarn dlx --version
bunx --version
```

Source: https://nimbus-docs.cn/cli/index.mdx