# 命令行
Source: https://blume.ndjp.net/docs/cli/
English: https://useblume.dev/docs/cli

```bash
blume <command> [options]
```

## 命令

| 命令 | 说明 |
| --- | --- |
| `blume init [dir]` | 生成项目脚手架（默认交互式）。 |
| `blume dev` | 启动带热重载的开发服务器。 |
| `blume build` | 构建静态（或服务端）站点。 |
| `blume preview` | 预览上一次构建。 |
| `blume add [item]` | 从 registry 安装一个源组件（不带 item 时列出可用项）。 |
| `blume sync` | 重新拉取远程内容源并重新生成。 |
| `blume eject` | 把运行时导出为一个独立的 Astro 应用。 |
| `blume check` | 用 `astro check` 对站点做类型检查。 |
| [`blume doctor`](/docs/cli/doctor/) | 诊断配置与内容问题。 |
| [`blume validate`](/docs/cli/validate/) | 校验内容中的所有链接。 |
| [`blume audit`](/docs/cli/audit/) | 审查构建产物中的 SEO 与站点健康问题。 |
| [`blume eval`](/docs/cli/evals/) | 测试文档：让一个 agent 仅凭文档回答你的问题。 |
| [`blume translate`](/docs/cli/translate/) | 用本地 agent CLI 把文档翻译到已配置的语言。 |
| [`blume version [id]`](/docs/cli/version/) | 把当前文档冻结为一个归档版本（不带 id 时列出已配置的版本）。 |
| [`blume skill`](/docs/discoverability/agent-discovery/) | 用 Codex 或 Claude Code 为你的文档编写 agent skill，替代自动生成的那一份。 |
| [`blume migrate [source]`](/docs/migrating/) | 用 Codex 或 Claude Code 把 Mintlify、Fumadocs、Docusaurus、Starlight 或 Nextra 站点迁移到 Blume。 |
| [`blume upgrade`](/docs/upgrading/) | 升级到新的主版本：先升级 `blume`，再列出剩余的配置改动，或把它们交给 Codex 或 Claude Code。 |

## 通用选项 [#common-flags]

- `blume init` — 在终端里，它会引导你回答几个问题（项目建在哪里、站点名称、模板、内容源）；下面的每个选项都预先回答了其中一个问题。
- `blume init --yes` — 跳过所有提问，用默认值生成脚手架（在 CI 中或 stdin 不是终端时也是这个行为）。
- `blume init --content-dir <dir>` — 设置内容目录（默认 `docs`）。
- `blume init --template docs|api|sdk|changelog` — 从一个起始模板生成脚手架（用 API 参考、SDK 或更新日志，替代普通的文档种子）。
- `blume init --package-manager npm|pnpm|yarn|bun` — 用指定的包管理器安装依赖，并打印对应的后续步骤（默认：运行 `blume init` 的那个）。
- `blume init --no-install` — 只写文件、跳过依赖安装，适用于 CI 或自定义的依赖流程。默认情况下 `blume init` 会运行包管理器的安装命令，让项目开箱即可运行；如果安装失败，脚手架会被保留、重试命令会被打印出来，退出码非零。
- `blume init --eject` — 先生成脚手架，再导出为一个独立的 Astro 项目（配合 `--no-install` 时，依赖装好后会改为引导你执行 `blume eject`）。
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — 扫描另一个内容目录，无需改动 `blume.config.ts`。
- `blume dev --debug` — 输出详细的 Astro/Vite 日志，便于排查问题。
- `blume dev --preview` / `blume build --preview` — 包含草稿和未发布的 CMS 内容。
- `blume build --no-strict` — 即使有诊断错误也照常构建。默认情况下 `blume build` 只要遇到任何错误级诊断就失败（退出码 1），因为 frontmatter 校验未通过的页面会被从产物中丢弃；加上 `--no-strict` 后构建会成功，并报告有多少页面被丢弃。`blume dev --strict` 让开发模式采用同样的快速失败行为。
- `blume build --analyze` — 构建后打印客户端 JavaScript 各包的体积（从大到小）。
- `blume build --budget-js <kb> --budget-css <kb>` — 当客户端 JavaScript/CSS 总量超出预算时让构建失败，把性能目标变成一道 CI 关卡。
- `blume build --isolated` — 构建到一个一次性的 `.blume-verify/` 运行时（以及它自己的 `dist/`）中，而不是 `.blume/`，这样正在运行的 `blume dev` 服务器和你真正的 `dist/` 都不会被影响。参见[开发服务器运行时如何校验](#verifying-while-the-dev-server-runs)。
- `blume preview --host --port <n>` — 绑定预览服务器。
- `blume sync --force` — 先丢弃缓存快照，再重新拉取远程源。
- `blume sync --preview` — 包含草稿和未发布的 CMS 内容。
- `blume sync --strict` — 遇到诊断即失败。
- `blume add <item> --force` — 覆盖已存在的文件。
- `blume check --preview` — 检查时包含草稿和未发布的 CMS 内容。
- `blume check --strict` — 内容诊断与类型错误都导致失败。
- `blume check --isolated` — 在一次性的 `.blume-verify/` 运行时中做类型检查，使正在运行的 `blume dev` 服务器不受影响。参见[开发服务器运行时如何校验](#verifying-while-the-dev-server-runs)。
- `blume eject --yes` — 跳过确认提示。
- `blume eject --force` — 在已经导出的应用上再次导出，覆盖其 `astro.config.mjs` 和 `src/`。

有独立页面的命令会把自己的全部选项都列在那一页：[`blume doctor`](/docs/cli/doctor/)、[`blume validate`](/docs/cli/validate/)、[`blume audit`](/docs/cli/audit/)、[`blume eval`](/docs/cli/evals/)、[`blume translate`](/docs/cli/translate/) 和 [`blume version`](/docs/cli/version/)。`blume validate`、`blume doctor`、`blume audit`、`blume eval` 和 `blume translate` 接受 `--json`，把机器可读的结果打印到 stdout，供 CI 和编辑器集成使用（诊断的数据结构见 [validate](/docs/cli/validate/)）；`build`、`check` 和 `dev` 只向终端输出。每个命令都会拒绝自己不接受的选项，并给出最接近的那一个作为建议、同时列出它真正接受的选项，因此像 `--isolatd` 这样的拼写错误会直接失败，而不会被悄悄忽略。

## 开发服务器运行时如何校验 [#verifying-while-the-dev-server-runs]

`blume dev` 提供的是一个以生成的 `.blume/` 运行时为根的实时 Astro 服务器，并在每次改动后重新生成它。`blume build` 和 `blume check` 重新生成的是*同一个* `.blume/`，因此在开发服务器运行时执行其中任何一个都会把它弄坏——两者都会报错并以非零码退出：

```
A `blume dev` server is running at http://localhost:4321; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

`--isolated` 就是那个逃生舱。它把整个生成的运行时（对 `build` 来说还有它输出的 `dist/`）挪到同级的 `.blume-verify/` 目录，因此校验过程绝不会写入开发服务器（或你真正的 `dist/`）所依赖的任何东西：

```bash
# 在第二个终端里，`blume dev` 正在运行时：
blume check --isolated   # 快：只对 .astro/config 的改动做类型检查
blume build --isolated   # 彻底：把生产构建完整渲染到 .blume-verify/dist
```

`check --isolated` 是快捷路径（Astro 类型与模板诊断，不产出 `dist/`）；`build --isolated` 更重，还会捕捉运行时渲染错误。隔离构建会跳过部署后的步骤（搜索索引、托管服务同步、`llms.txt`、sitemap/robots、重定向）——一次校验只需要确认站点能编译、能渲染，不需要把它发布出去。`--analyze` 以及 `--budget-js`/`--budget-css` 两道关卡仍然会跑，只是以隔离产物为基准。Blume 会自动把 `.blume-verify/` 加进你的 `.gitignore`。

当你想让开发服务器一直开着、同时又需要编码 agent 校验改动时，这一点尤其有用。要让普通的 `blume build`/`blume check` 不加这个选项也能自动隔离——比如在 agent 的 shell 里——把 `BLUME_RUNTIME_DIR` 设成要使用的运行时目录：

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## 类型检查

`blume check` 会对你的项目运行 [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)。它会重新生成 `.blume` 运行时、同步 Astro 的内容类型，然后报告所有 TypeScript 错误——无论是在你的 `blume.config.ts` 里、在自定义的 `.astro` 页面里，还是在这些页面导入的组件中。有错误时它以非零码退出，因此可以直接当作 CI 中的 `typecheck` 步骤：

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

在项目根目录添加一个继承 Astro 配置的 `tsconfig.json`，这样手写的页面才能解析 `blume/*` 导入以及 `blume:data` 这类虚拟模块：

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", "**/*"]
}
```

没有项目级 `tsconfig.json` 时，只会检查生成的运行时。