Skip to content
Skip to Content
verbatra

Reference / CLI

CLI reference

Every verbatra subcommand and the global flags they share, plus how the CLI reads your environment and loads .env files.

@verbatra/cli ships the verbatra binary, a thin wrapper over @verbatra/sdk.

Commands

These commands do the work:

init

Create a verbatra config and .env.example for this project.

extract

Scan your application source for translation call sites and add the new keys to the source locale file.

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.

report

Print a read-only report: report provenance lists which translations a machine wrote and which a person reviewed.

doctor

Validate the project setup and report every problem at once, without calling a provider.

pseudo

Generate a pseudolocale from the source strings, without calling a provider.

types

Generate TypeScript declarations for your catalog keys and their message arguments, without calling a provider.

export

Export untranslated strings for a human translator, as an Excel workbook, one CSV or TSV file per locale, or one XLIFF file per locale for a CAT tool.

import

Import a filled workbook or delimited file back into the locale files.

tmx

Import a TMX translation memory from another tool into this project's memory, or export this project's memory as a TMX file.

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:

npm install --save-dev @verbatra/cli

Then run the binary through your package manager:

npx @verbatra/cli <command>

You need Node.js ^22.22.0 || >=24 (CLI 0.12.x accepts ^22.18.0 || >=24).

Trying a command before installing? npx @verbatra/cli <command> (npm) or pnpm dlx @verbatra/cli <command> (pnpm) both work without a prior local install. Always use the scoped name: the unscoped name verbatra on npm does not belong to this project.

Global flags

These flags mean the same on every command that takes them, so the command pages list only their own flags. The last column names the commands that do not take a flag.

FlagArgumentDefaultEffectNot accepted by
--cwd<path>current directorystart the config search here and resolve the paths you pass against it; locale files resolve against the directory of the config the search found; init writes its files therenone
--config<path>search for oneload this config file instead of searching; see the search orderinit
--jsonnoneoffprint a machine-readable envelope on stdout, one line per record; errors still go to stderrmcp, studio
-q, --quietnoneoffprint only results, warnings and errors: no progress, hints or informational lines; works before or after the command namenone
--no-colornonecolor on a terminalnever color the output; see Terminal outputnone
-h, --helpnoneoffprint the help of the program or the command and exit 0none
-V, --versionnoneoffprint the CLI version and exit 0none

An unknown command or flag exits 2, and so does a bare verbatra with no command: it prints the help to stderr and, when no config is found, suggests verbatra init. mcp never writes to stdout, since stdout is its protocol channel, so it refuses --json with USAGE_ERROR. From 0.12.0 a --cwd that names no existing directory exits 2 with INVALID_OPTION on every command, before anything is read or written.

Environment files

translate, watch, doctor, studio, and mcp load .env.local and then .env from the working directory before they run. When the config the search found sits in a parent directory, they then load the same two files from that directory too; with --config they read only the working directory. When an MCP client changes its roots, the MCP server loads both files from the new project root too. doctor --literals is the exception: it reads no API key, so it loads neither file. A variable already set in your real environment always wins, then the working directory's files, then the config directory's, and a value in .env.local wins over the same variable in .env. API keys are read only from the environment, never from the config file or a flag: see Providers. The read-only commands (check, diff, report), the handoff commands (export, import), extract, init, pseudo, types, and tmx never call a provider and load no .env files.

.gitignore entries

A real run of translate, watch, import, tmx import or pseudo also appends whichever of .env, .env.local, .verbatra-local/ and verbatra.cache.json an existing .gitignore in the project root is missing, and names them on stderr (--json and --quiet drop that line). This happens as soon as the config has loaded, so a run that then fails has already done it. A dry run leaves the file alone, and none of these commands creates one; verbatra init does. A .gitignore that is a symbolic link leaving the project is left unchanged, with a warning that --json and --quiet keep.

Terminal output

Color, the spinner, --quiet and the variables that control them are described in Terminal output.

Exit codes

The exit-code contract and its edge cases are on Exit codes and JSON output. Each command page lists only the codes that command returns.

Edit on GitHub

On this page

CommandsInstall and invokeGlobal flagsEnvironment files.gitignore entriesTerminal outputExit codes