CLI reference
This page lists every command of the x18n CLI. CLI and x18n check explains how to use them. Run x18n <command> --help to see the same text in a terminal.
Global options
Every command accepts these options.
| Option | Description |
|---|---|
--root <dir> | Project root (default: nearest config upward from the cwd) |
--config <file> | Explicit config file |
--project <name> | Pick one project in a monorepo |
--json | Print the JSON contract instead of human output |
--no-cache | Ignore the persistent cache |
--yes | Accept default answers for decisions |
-h, --help | Display the help of a command |
-v, --version | Display the version number |
A repeatable option takes several values: --locale de --locale fr. Options that take a list also accept commas: --only missing-key,unused-key.
x18n
x18n [options]Show the status and the main commands.
status
x18n status [options]Locales with coverage, resources, keys and diagnostics.
keys
x18n keys [glob] [options]List keys.
| Option | Description |
|---|---|
--missing <locale> | Only keys missing or empty in a locale |
--unused | Only keys without usages |
--namespace <ns> | Only keys of a namespace |
--values | Include the value per locale |
--limit <n> | Page size |
--cursor <cursor> | Start of the page (from nextCursor) |
get
x18n get <key> [options]Values, resources, usages and diagnostics of one key.
usages
x18n usages [key] [options]Usages of a key, or all usages.
| Option | Description |
|---|---|
--file <path> | Only usages in a file |
--limit <n> | Page size |
--cursor <cursor> | Start of the page |
locales
x18n locales [options]Locale codes as found, with display names and resources.
doctor
x18n doctor [options]How the project was understood: presets, finders, formats, scanners, config origins.
check
x18n check [options]Report invalid, untranslated and unused keys, like tsc --noEmit.
| Option | Description |
|---|---|
--watch | Re-check on change |
--strict | Turn every warning into an error |
--locale <locale> | Only report for these locales (repeatable) |
--only <checks> | Only these check ids (comma separated) |
--skip <checks> | Skip these check ids (comma separated) |
--max-warnings <n> | Fail when there are more warnings |
--reporter <id> | pretty, json, markdown, github or sarif (repeatable) |
--output <file> | Write the matching reporter output to a file (repeatable) |
set
x18n set <key> [options]Set one value.
| Option | Description |
|---|---|
--locale <locale> | Locale (default: source locale) |
--value <value> | The value; - reads stdin |
--dry-run | Print the plan instead of writing |
apply
x18n apply <file> [options]Batch set from JSON { "<locale>": { "<key>": "<value>" } }; - reads stdin.
| Option | Description |
|---|---|
--force | Write values with placeholder problems |
--dry-run | Print the plan instead of writing |
rename
x18n rename <from> <to> [options]Rename a key (or every key under a parent) in all locales and usages.
| Option | Description |
|---|---|
--no-usages | Keep code unchanged |
--dry-run | Print the plan instead of writing |
delete
x18n delete <key> [options]Delete a key (or every key under a parent) in all locales.
| Option | Description |
|---|---|
--locale <locale> | Only in these locales (repeatable) |
--dry-run | Print the plan instead of writing |
fill
x18n fill [options]Add missing keys with empty values.
| Option | Description |
|---|---|
--locale <locale> | Only these locales (repeatable) |
--copy-source | Use the source value instead of an empty string |
--dry-run | Print the plan instead of writing |
format
x18n format [options]Re-write resources with the configured sort and indent.
| Option | Description |
|---|---|
--dry-run | Print the plan instead of writing |
extract
x18n extract [...files] [options]Find hard-coded strings and turn them into keys.
| Option | Description |
|---|---|
--list | Print candidates and proposed keys |
--plan <file> | Write the extraction plan to a file to edit |
--apply <file> | Apply an (edited) extraction plan |
--dry-run | Print the plan instead of writing |
prompt
x18n prompt <kind> [options]Print a prompt for an agent or LLM: prompt translate --to <locale> or prompt review --locale <locale>.
| Option | Description |
|---|---|
--to <locale> | Target locale (translate) |
--locale <locale> | Locale to review |
--keys <glob> | Only keys matching a glob |
--namespace <ns> | Only keys of a namespace |
--limit <n> | Messages per prompt (default 50) |
--cursor <cursor> | Continue from nextCursor |
--format <format> | markdown (default) or json |
--no-context | Leave out code around usages |
--stale | Also translate stale translations (needs git history) |
ui
x18n ui [options]Start the UI: browse and edit messages in the browser, with HTTP MCP at /__mcp.
| Option | Description |
|---|---|
--port <port> | Port (default: a free one from 9999) |
--host <host> | Bind host (default: localhost) |
--no-open | Do not open the browser |
--no-auth | Skip authentication (CI and e2e only) |
build
x18n build [options]Write a static, read-only report of the UI.
| Option | Description |
|---|---|
--out-dir <dir> | Output directory (default: .x18n/report) |
mcp
x18n mcp [options]Serve the MCP tools over stdio.
init
x18n init [options]Detect the setup and write x18n.config.ts.
| Option | Description |
|---|---|
--format <format> | ts (default), yml or json |
--force | Replace an existing config |
migrate
x18n migrate <source> [options]Convert i18n-ally settings: migrate i18n-ally.
| Option | Description |
|---|---|
--format <format> | ts (default), yml or json |
--dry-run | Print the files instead of writing |
--force | Replace an existing config |
schema
x18n schema [name] [options]Print a JSON Schema: config (default) or plugin.
plugin
x18n plugin <action> <file> [options]Plugin tools: plugin eject <file.yml> prints the TS equivalent.
Exit codes
| Exit code | Meaning | Error codes |
|---|---|---|
0 | Success. For x18n check: no errors, and no more warnings than --max-warnings. | |
1 | x18n check found errors or too many warnings, x18n apply rejected values, or the command failed with one of these errors. | X18N2001, X18N2002, X18N2003, X18N2004, X18N3001, X18N4001, X18N4002, X18N4005, X18N4006, X18N4007, X18N4008 |
2 | Usage, config or plugin error. Errors without an x18n code also exit with 2. | X18N0001, X18N0002, X18N0003, X18N1001, X18N1002, X18N1003, X18N1004 |
3 | A decision is needed and no answer was given. Run again with --yes. | X18N4003 |
4 | Files changed while the command ran. Run it again. | X18N4004 |