跳到正文
跳到正文

参考 / CLI

机器翻译页面

本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。

CLI 参考

verbatra 的每个子命令及其共用的全局选项,以及 CLI 如何读取环境、加载 .env 文件。

@verbatra/cli 提供 verbatra 二进制文件,它是 @verbatra/sdk 之上的一层薄封装。

命令

下列命令负责实际工作:

安装与调用

把 @verbatra/cli 作为开发依赖安装:

npm install --save-dev @verbatra/cli

然后通过包管理器运行该二进制文件:

npx @verbatra/cli <command>

需要 Node.js ^22.22.0 || >=24(CLI 0.12.x 接受 ^22.18.0 || >=24)。

想在安装之前试用某个命令?npx @verbatra/cli <command>(npm)或 pnpm dlx @verbatra/cli <command>(pnpm)都不需要事先在本地安装。始终使用带作用域的名称:npm 上不带作用域的名称 verbatra 不属于本项目。

全局选项

这些选项在每个接受它们的命令上含义相同,因此各命令页面只列出它们自己的选项。最后一列列出不接受该选项的命令。

选项参数默认值作用不适用于
--cwd<path>当前目录从这里开始查找配置,并以它为基准解析你传入的路径;语言文件相对于查找到的配置文件所在目录解析;init 把文件写到这里无
--config<path>自动查找加载这个配置文件,不再查找;见查找顺序init
--json无关闭在 stdout 上输出机器可读的信封(envelope),每条记录一行;错误仍输出到 stderrmcp、studio
-q、--quiet无关闭只输出结果、警告和错误:不输出进度、提示或说明性的行;放在命令名之前或之后都有效无
--no-color无在终端中着色输出从不着色;见终端输出无
-h、--help无关闭输出程序或命令的帮助,并以退出码 0 退出无
-V、--version无关闭输出 CLI 版本,并以退出码 0 退出无

未知的命令或选项以退出码 2 退出,不带任何命令的裸 verbatra 也是如此:它把帮助输出到 stderr,找不到配置时还会建议运行 verbatra init。mcp 从不写入 stdout,因为 stdout 是它的协议通道,所以它以 USAGE_ERROR 拒绝 --json。从 0.12.0 起,指向不存在目录的 --cwd 在每个命令上都以退出码 2 和 INVALID_OPTION 退出,且发生在读取或写入任何内容之前。

环境文件

translate、watch、doctor、studio 和 mcp 在运行前,会从工作目录加载 .env.local,然后加载 .env。当查找到的配置位于上级目录时,它们接着也从该目录加载同样两个文件;使用 --config 时只读取工作目录。MCP 客户端更改它的根目录时,MCP 服务器也会从新的项目根目录加载这两个文件。doctor --literals 是例外:它不读取 API 密钥,因此两个文件都不加载。优先级为:你真实环境中已设置的变量始终优先,其次是工作目录中的文件,再次是配置所在目录中的文件;.env.local 中的值优先于 .env 中的同名变量。API 密钥只从环境读取,绝不从配置文件或选项读取:见提供商。只读命令(check、diff、report)、交接命令(export、import)、extract、init、pseudo、types 和 tmx 从不调用提供商,也不加载 .env 文件。

.gitignore 条目

translate、watch、import、tmx import 或 pseudo 的真实运行,还会把项目根目录中现有 .gitignore 缺少的 .env、.env.local、.verbatra-local/ 和 verbatra.cache.json 追加进去,并在 stderr 上指出它们(--json 和 --quiet 会去掉那一行)。这发生在配置一加载完成时,因此随后失败的运行已经做过这件事了。试运行不会动该文件,这些命令也都不会创建它;verbatra init 会创建。若 .gitignore 是指向项目之外的符号链接,则保持不变,并给出警告,--json 和 --quiet 会保留该警告。

终端输出

颜色、加载动画(spinner)、--quiet 以及控制它们的变量,见终端输出。

退出码

退出码约定及其边界情况见退出码与 JSON 输出。每个命令页面只列出该命令返回的退出码。

在 GitHub 上编辑

本页内容