Overview
The verbatra command: its ten subcommands, the shared flags, how it reads your environment, and the exit-code contract.
@verbatra/cli ships the verbatra binary, a thin wrapper over @verbatra/sdk. Ten commands do the work:
| Command | What it does |
|---|---|
init | create a verbatra config and .env.example for this project |
translate | translate every target locale once, then exit |
watch | re-translate on every source change until interrupted |
check | report which keys are missing or stale per locale, read-only |
diff | list the exact keys that would be added, re-translated, or are orphaned per locale, read-only |
doctor | validate the project setup and report every problem at once, without calling a provider |
export | export untranslated strings for a human translator, as an Excel workbook or one CSV or TSV file per locale |
import | import a filled workbook or delimited file back into the locale files |
studio | start Verbatra Studio, the local translation dashboard |
mcp | start a stdio MCP server exposing verbatra's tools to an MCP client |
Install and invoke
Install @verbatra/cli as a dev dependency, then run the binary through your package manager:
| Package manager | Install | Run |
|---|---|---|
| npm | npm install --save-dev @verbatra/cli | npx verbatra <command> |
| pnpm | pnpm add -D @verbatra/cli | pnpm verbatra <command> (or pnpm exec verbatra <command>) |
| yarn | yarn add -D @verbatra/cli | yarn verbatra <command> |
| bun | bun add -d @verbatra/cli | bun run verbatra <command> |
You need Node.js >=22.14.0.
Trying a command before installing? npx @verbatra/cli <command> (npm) or pnpm dlx @verbatra/cli <command> (pnpm) both work without a prior local install.
Shared conventions
--cwd <path>resolves the config and locale files from that directory instead of the current one. Every command takes it.--config <path>loads that config file instead of searching for one. Every command exceptinittakes it; the search order is described in The config file.--jsonprints a machine-readable envelope on stdout, one line per record, keeping stdout clean for piping.- Branch on its
okfield: a success carries the command's payload underresult, and a failed run carries the same stable error code the stderr line names. The human-readable error line goes to stderr either way. translate,watch,check,diff,doctor,export, andimportsupport it;init,studio, andmcpdo not.mcpnever writes anything to stdout at all, since stdout is the MCP protocol channel; seeverbatra mcp.
- Branch on its
--helpand--versionprint and exit0. An unknown command or flag exits2.
Environment files
translate, watch, doctor, studio, and mcp load .env.local and then .env from the working directory before they run. A variable already set in your real environment always wins. API keys are read only from the environment, never from the config file or a flag: see Providers. The read-only commands (check, diff) and the handoff commands (export, import) never call a provider and load no .env files.
Exit codes
The exit code is the contract a CI step or script branches on:
| Code | Meaning |
|---|---|
0 | success (also --help and --version) |
1 | translate or import finished but some locales failed or came out partial, check found a locale out of sync, diff found pending changes, or doctor found a setup problem |
2 | could not run: a whole-run error (config, source, provider, lock), or a usage error |
130 | watch, studio, or mcp was force-stopped by a second interrupt |
Each command page spells out how these codes apply to it. See CI and exit codes for wiring them into a pipeline.
Edit on GitHub