@lingo.dev/cli

@lingo.dev/cli 会把你的源内容发送到本地化引擎，等待引擎生成翻译，再将结果写回磁盘。它是旧版 npx lingo.dev 流程的替代方案——项目没变，但底层架构已经完全不同。

相比旧版 CLI，有哪些变化#

旧版 CLI（npx lingo.dev run）会提取字符串、直接在你的机器上调用 LLM，并一次性把文件写回本地。新版 CLI 则把流程拆成 push 和 pull：

lingo push 将源文件上传到你的引擎，启动服务端工作流，并可选择等待完成，或立即返回一个运行 ID
lingo pull 拉取最近一次 push 的输出——即使你在翻译中途关掉了终端，或是在另一台机器上执行 pull，也照样可用
lockfile（.lingo/lock.json）会记录每个目标文件在服务器上的最新已知版本，以便在本地修改即将被覆盖前触发冲突检测

这也解锁了旧版 CLI 做不到的两件事：翻译任务再久也不用一直挂着终端，以及可以在执行 push 的那台机器之外拉取结果（包括在 CI 中）。

等待结果#

目前，lingo push 会上传源文件、启动服务端工作流、等待其完成，并将输出写回——全部由一条命令完成。传入 --wait（-w）会显式启用这种阻塞行为。你也可以稍后用 lingo pull 重新连接到一个已完成的运行。

bash

lingo push            # submit, wait, and write outputs (current default)
lingo push --wait     # same thing, made explicit

lingo pull            # later: re-attach to the most recent push and download its outputs

即将到来的变更： 即将发布的版本会调整默认行为，让 lingo push 在提交运行后立即退出；届时你将通过 lingo pull 下载已完成的翻译，而 --wait（-w）则用于重新启用这种单命令阻塞流程。

--wait（-w）会一直阻塞到工作流结束，并在同一条命令中写入输出。
lingo pull 会重新连接到该项目最近一次 push，并下载对应输出——即使你早已关闭终端也没问题。运行状态按机器存放在 ~/.lingo/runs/<project-hash>.json，因此 pull 会在同一台机器上恢复。

认证：这两个命令都会读取 LINGO_API_KEY（或 --api-key，或 lingo login 会话）。在 CI 中，只需设置 LINGO_API_KEY，无需额外配置。

push 模式#

命令	模式	适用时机
`lingo push`	增量——对比源文件与 `.lingo/lock.json` 的差异，只翻译新增或变更的键到现有目标文件中，其余内容保持不变	日常运行 / CI
`lingo push --backfill-missing`	初始化——补齐尚不存在的目标文件	首次 push，或新增语言区域后
`lingo push --force`	全量重译——覆盖所有目标文件（包括手动编辑）；`--yes`/`-y` 可跳过提示	极少使用（例如 glossary/engine 变更后）

--backfill-missing 是一个初始化标志。它会发起一次限定范围的全新请求，只补齐整份缺失的目标文件——不会把新增的键翻译到已有译文的文件中（运行会显示“already up-to-date”，并跳过该键）。持续迭代时，请直接使用 lingo push。

手动编辑翻译#

普通的 lingo push 会按键保留手动编辑：

编辑某个目标字符串（其源内容未变）→ 该字符串会被保留；其他键仍会继续更新。
某个已编辑键对应的源内容发生变化 → 系统会为该键生成新的翻译，并替换原来的手动编辑。
新增一个源键 → 该键会被翻译并添加进去，即使目标文件中已有手动编辑也一样。

本节内容#

快速开始

安装、认证、连接引擎，并完成第一次 push 和 pull。

配置

`.lingo/config.json`、`.lingo/lock.json`，以及保存在 `~/.lingo/runs/<hash>.json` 中、按机器区分的运行状态。

lingo push

发送源文件，等待翻译完成，并将结果写回。涵盖范围模式、`--force` 和重试语义。

lingo pull

拉取最近一次 push 的输出——跨机器、跨终端会话都适用。支持冲突检测。

其他命令