CLI Commands
CLI Commands
Every command @the-i18n-kit/cli registers is listed below and documented on its own page. This page carries what is true of all of them: the flags they share, the exit code each one sets, and the gates that make one fail a build on findings.
The command pages are generated from the command definitions, so a flag that no longer exists cannot appear on one.
Commands
| Command | What it does |
|---|---|
init | Create a schema-valid .i18n-mcp.json from framework detection. Non-interactive; refuses to overwrite without --force |
get | Get translation values for specific keys |
write | Write translation keys (add/update/upsert). Default mode: upsert. |
add | Add new translation keys (skips keys that already exist) |
update | Update existing translation keys (skips keys that do not exist) |
missing | Find translation keys missing in target locales |
status | Translation coverage per locale and per layer, with an overall completion percentage |
search | Search translation files by key or value |
remove | Remove translation keys from all locale files in a layer |
rename | Rename/move a translation key across all locale files |
move | Move a translation key from one layer to another, carrying every locale that defines it |
translate | Find missing translations and translate them via LLM. Requires --provider and --model for auto-translation. |
translate-key | Translate a single key from a source locale into target locales. Supports LLM translation with --provider. |
scan | Scan source code for translation key usage (file paths + line numbers) |
check | Find keys referenced in code but defined in no consumed locale layer (they render as raw keys); findings trip an always-on gate and exit 2, distinct from exit 1 for a run that failed |
find-duplicates | Find keys defined in both a shared layer and a consuming child layer (with divergence detection); --byValue also finds different keys carrying the same value |
remove-orphans | Find and remove orphan translation keys not referenced in source code |
scaffold | Create empty locale files for new languages |
Aliases
These names run a command documented above. They get no page of their own, because they take the same flags and produce the same result.
| Name | Runs | Why it exists |
|---|---|---|
translate-missing | translate | Alias of "translate" — matches the MCP tool translate_missing. |
Shared Flags
The shared command factory merges these into every command, so they are documented once here rather than repeated on every command page.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--projectDir, -d | string | no | — | Project directory (default: cwd) |
--json | boolean | no | false | Output as JSON (default for non-TTY) |
Flag Name Forms
Flags are declared in camel case and print that way in the-i18n-cli <command> --help, which is the form used throughout this reference. citty registers the kebab-case form as an alias, so --dryRun and --dry-run are the same flag.
Exit Codes
| Code | Means |
|---|---|
| 0 | The run succeeded and no gate tripped. |
| 1 | The run itself failed — an unusable API key, an unreadable project, a translate call that produced nothing. |
| 2 | The run succeeded and a gate tripped — one you requested, or one the command always evaluates. The findings are real; the tool worked. |
A gate tripping is not a run failing. Exit 2 means the command did its job and found something you asked it to fail on — missing keys, orphans, coverage below a floor. Exit 1 means the run itself fell over, and its counters say nothing about your project. A failed run outranks a tripped gate: gates are not consulted at all when the run failed.
CI Gates
Gates are opt-in, with one exception. Without one of these flags a command reports its findings and exits 0, so failing a build on findings is something you ask for rather than something you discover. The exception is a gate marked "always on": its findings are a defect rather than a threshold, so there is nothing to opt into.
| Command | Flag | Trips when |
|---|---|---|
missing | --failOnMissing | Exit 2 when any key is missing (CI gate) |
status | --failUnder | Exit 2 when overall completion is below this percentage (CI gate) |
translate | --failOnFailed | Exit 2 when any key failed to translate (CI gate) |
check | always on | summary.undefinedCount is above 0 |
remove-orphans | --failOnOrphans | Exit 2 when any orphan key is found (CI gate) |
When a gate trips, the result gains a gatesTripped array naming each gate, the counter it read, the threshold it was held to and the value it observed. A run where nothing tripped is byte-for-byte what it was before gates existed, so a consumer parsing the result needs no change to tolerate them.
gatesTripped entry — so a finding stays distinguishable from the run itself failing with exit 1.