Overview
The verbatra command: its eight 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. Eight 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 |
export | export untranslated strings into an Excel workbook for a human translator |
import | import a filled workbook back into the locale files |
studio | start Verbatra Studio, the local translation dashboard |
Install and invoke
Install @verbatra/cli as a dev dependency and run the binary through your package manager:
pnpm add -D @verbatra/cli
pnpm verbatra translate # or: npx verbatra translate, yarn verbatra translateYou need Node.js >=22.14.0.
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 result on stdout, keeping stdout clean for piping: errors go to stderr.translate,watch,check,diff,export, andimportsupport it;initandstudiodo not.--helpand--versionprint and exit0. An unknown command or flag exits2.
Environment files
translate, watch, and studio 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 workbook 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, check found a locale out of sync, or diff found pending changes |
2 | could not run: a whole-run error (config, source, provider, lock), or a usage error |
130 | watch or studio 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