CLI 命令参考

scribe 命令行工具随依赖包一起安装，并在安装后自动加入 PATH 环境变量。所有命令都支持通过 --config <path> 指定配置文件路径（默认在当前工作目录查找 scribe.config.ts），并且在运行前会按顺序读取 .env 和 .env.local 文件（已有的环境变量优先级更高）。

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 流程中作为构建门禁。完整的检查清单请参考内容模型章节。

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 参数）会继续未完成的任务，不会发生重复提交。如果翻译过程中有任何失败项，命令最终将以非零状态码退出。更多详情请参阅内容翻译。

scribe delete

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

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

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

具体执行效果取决于关联字段配置的 onTargetDelete 模式（restrict 阻止、detach 解除、cascade 级联）以及资源字段的 onDelete 模式（delete 删除、keep 保留），字段选项详见内容模型。如果计划中包含阻碍因素（如某个文档被设置为 restrict 关联，或是某个必填的单一关联字段因删除变成了空悬状态），则会打印这些阻碍因素并以状态码 1 退出，终止删除。你也可以在 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 参数）。