---
order: 9
section: reference
title: CLI 命令参考
description: >-
  scribe
  命令行工具的详细说明：status、validate、translate、delete、history、studio、export-static
  等所有命令与参数。
noindex: false
canonicalPath: /zh-CN/docs/cli
---
`scribe` 命令行工具随依赖包一起安装，并在安装后自动加入 PATH 环境变量。所有命令都支持通过 `--config <path>` 指定配置文件路径（默认在当前工作目录查找 `scribe.config.ts`），并且在运行前会按顺序读取 `.env` 和 `.env.local` 文件（已有的环境变量优先级更高）。

```bash
scribe status
scribe validate
scribe translate [flags]
scribe delete <type> <en-slug> [--dry-run] [--yes]
scribe history <type> <en-slug> [locale]
scribe studio [--port 3600]
scribe export-static [flags]
scribe version
```

## `scribe status`

按内容类型统计当前状态：先输出英文原文档的数量，接着是各个语言的翻译数量，以及对应的存储路径。用于快速查看翻译覆盖率。

## `scribe validate`

对整个项目进行全面校验：包括 Schema 定义、内置字段、`crossValidate` 钩子、英文正文与已有翻译的 MDX 编译检查、关联关系、`_redirects.json` 规则、多语言 Slug 后缀格式，以及（在设置了 `assetsDir` 的情况下）是否存在缺失的图片资源。校验问题会逐行打印，遇到错误则以非零状态码退出，因此可以集成到 CI/CD 流程中作为构建门禁。完整的检查清单请参考[内容模型](/docs/content-model)章节。

## `scribe translate`

调用 Gemini 翻译缺失和过期的页面（需要配置 `GEMINI_API_KEY`）。如果在终端中不带参数直接运行，它会启动交互式提示，让你选择内容类型、语言预设、翻译策略以及运行模式。在脚本中使用时，可以通过参数指定：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `--type <id,id>` | 所有类型 | 需翻译的内容类型，多个以逗号分隔。 |
| `--locale <code>...` | 所有非默认语言 | 目标语言，多个以空格分隔。此选项会覆盖 `--preset`。 |
| `--preset <name>` | - | 使用配置文件中 `localePresets` 定义的语言组。 |
| `--slug <en-slug>` | - | 指定单篇英文文档进行翻译。 |
| `--strategy <all\|missing-only>` | `all` | `all` = 翻译过期内容 + 缺失内容；`missing-only` 则跳过已过期（但已存在）的翻译。 |
| `--batch` / `--direct` | `batch` | 翻译模式。Batch 模式将任务提交至 Gemini Batch API，可节省 50% 的 token 成本；Direct 模式则为逐页发起常规 API 请求，结果实时返回。 |
| `--resume` | - | 检查未完成的 Batch 任务状态，拉取已完成的结果，不再提交任何新任务。 |
| `--concurrency <n>` | `3` | 并发翻译请求数（仅在 Direct 模式下生效）。 |
| `--model <id>` | `gemini-3.1-pro` | 指定要使用的 Gemini 模型。 |
| `--dry-run` | - | 打印待翻译清单，不会实际调用 API 或写入文件。同时预估每篇文章和整体的 token 消耗及美元成本。 |
| `--force` | - | 即使英文内容的哈希值未发生变化，也强制重新翻译。 |
| `--no-progress` | - | 禁用实时更新的进度条 UI，改为输出纯文本的逐行日志。 |

在交互模式下运行时，终端会显示实时更新的进度条，包含 Batch 任务状态、单项翻译结果、累计的输入输出 token 数量，以及预估的美元成本（包括思考 token 的成本）。Batch 任务在开始轮询状态前就会持久化到本地存储中，因此中途按 Ctrl+C 中断是安全的：下次运行（或加上 `--resume` 参数）会继续未完成的任务，不会发生重复提交。如果翻译过程中有任何失败项，命令最终将以非零状态码退出。更多详情请参阅[内容翻译](/docs/translation)。

## `scribe delete`

```bash
scribe delete <type> <en-slug> [--dry-run] [--yes]
```

删除指定的文档条目及其引发的级联删除内容。命令执行前会先计算出一份删除计划，按类别分组打印：级联删除的条目、将被解除关联的引用、受影响的资源文件、各语言对应的存储数量（包含翻译内容与历史快照）以及可能阻止删除的阻碍因素。随后会提示 `y/N` 确认是否继续。确认后，程序将严格按照计划执行（删除源文件、清理存储记录、删除资源文件并重写关联解除规则），绝不会超出计划范围。

| 参数 | 说明 |
| --- | --- |
| `--dry-run` | 仅打印删除计划，退出码为 0，不执行任何实际删除。 |
| `--yes` | 跳过确认提示（适合在脚本中使用）。 |

具体执行效果取决于关联字段配置的 `onTargetDelete` 模式（`restrict` 阻止、`detach` 解除、`cascade` 级联）以及资源字段的 `onDelete` 模式（`delete` 删除、`keep` 保留），字段选项详见[内容模型](/docs/content-model)。如果计划中包含阻碍因素（如某个文档被设置为 `restrict` 关联，或是某个必填的单一关联字段因删除变成了空悬状态），则会打印这些阻碍因素并以状态码 1 退出，终止删除。你也可以在 [Studio 后台](/docs/studio) 的删除按钮面板中查看同样的删除计划。

## `scribe history <type> <en-slug> [locale]`

查看单篇文档的英文快照历史记录：显示每个快照的捕获时间、内容哈希值，以及哪些语言的翻译是基于该快照生成的。可以传入具体的 locale 参数进行过滤筛选。

## `scribe studio`

启动一个只读的本地 Web 管理界面（默认访问地址为 `http://127.0.0.1:3600`，可通过 `--port` 修改端口）。这里展示了各个类型和语言的翻译覆盖率、当前的缺失/过期任务清单，以及单篇文档的详细信息：带有可翻译或结构化标记的 Frontmatter、存储在数据库中的翻译内容、相关元数据（使用模型、翻译日期、哈希值），以及翻译所基于的英文快照。Studio 只提供查看功能；所有的编辑修改仍需在你的编辑器和 Git 中完成。

## `scribe export-static`

将纯正的 MDX 文件（Frontmatter 加上正文，按语言区分）输出到一个静态目录中，非常适合提供给爬虫或 LLM 解析纯文本版本的网页内容：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `--out <dir>` | `public` | 导出文件的存放目录。 |
| `--extension <ext>` | `mdx` | 导出文件的扩展名。 |
| `--type <id,id>` | 所有带路由配置的类型 | 需要导出的内容类型，多个以逗号分隔。 |
| `--locale <code>...` | 所有语言 | 需要导出的目标语言。 |

在执行写入操作前，系统会自动清理指定的导出目录。在 `_redirects.json` 中配置为重定向来源的文档将被跳过。

## `scribe version`

打印当前安装的 scribe-cms 版本号（也可使用 `--version` 或 `-V` 参数）。