CLI reference#

Running globetrotter without a subcommand generates every configured output. The format and lint subcommands operate on the same discovered inputs.

$ globetrotter --help
 
Polyglot, type-safe internationalization
 
Usage: globetrotter [OPTIONS] [COMMAND]
 
Commands:
  format  Formats translation files in place
  lint    Lints translation files and reports any issues
  help    Print this message or the help of the given subcommand(s)
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --check[=<CHECK_TEMPLATES>]
          Whether to validate that all templates render successfully
 
          [possible values: true, false]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Generation#

globetrotter [OPTIONS]

Common options:

Option	Purpose
`-c, --config <PATH>`	Load a config file, or search a directory for one. Repeatable.
`-i, --translation <PATH>`	Add a translation file directly. Repeatable.
`--engine <ENGINE>`	Override the configured template engine.
`--strict[=<BOOL>]`	Promote warnings to errors.
`--check[=<BOOL>]`	Compile and validate templates.
`--dry-run[=<BOOL>]`	Run without writing output files.
`--absolute[=<BOOL>]`	Print absolute paths instead of paths relative to the shared base directory.
`--max-keys <N>`	Process a bounded prefix of each config for debugging.
`--color <CHOICE>`	Control ANSI color output.
`--log <LEVEL>`	Set the log level unless `RUST_LOG` overrides it.
`--log-format <FORMAT>`	Select pretty or JSON logs.

When neither --config nor --translation is present, Globetrotter searches the current directory for its config file.

Format#

globetrotter format [OPTIONS]

The formatter sorts translation keys while preserving comments. It defaults to ascending order. --check exits non-zero when a file would change and is suitable for CI. Ordinary # comments move with their keys; #! comments stay at the top of the file. See file-level comments for examples and migration guidance.

$ globetrotter format --help
 
Formats translation files in place
 
Usage: globetrotter format [OPTIONS]
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --order <ORDER>
          Order in which translation keys are sorted
 
          Possible values:
          - ascending:  Sort keys from A to Z
          - descending: Sort keys from Z to A
 
          [default: ascending]
 
      --check
          Check whether files are already formatted instead of rewriting them.
 
          Exits with a non-zero status if any file would be reformatted.
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Lint#

globetrotter lint [OPTIONS]

Lint includes all shared input and config options. Its own controls cover source-usage scanning, duplicate detection, and the experimental LLM judge.

$ globetrotter lint --help
 
Lints translation files and reports any issues
 
Usage: globetrotter lint [OPTIONS]
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --usages <DIR>
          Report potentially unused translation keys using this source directory.
 
          The supplied roots replace every selected config's declared roots. Repeat the option to include multiple directories. When omitted, each config uses its own `usages.roots`.
 
      --dynamic-usages <POLICY>
          Override each config's dynamic translation-call policy (allow, warn, or deny)
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --call-usages <POLICY>
          Override each config's static translation-call policy (allow, warn, or deny).
 
          The policy governs undefined keys and mismatched arguments in calls with a literal key.
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
      --no-ignore
          Bypass `.ignore` files when scanning usages
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --no-gitignore
          Bypass `.gitignore` and Git exclude files when scanning usages
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --no-duplicates
          Disable duplicate-translation detection entirely
 
      --llm-judge
          (experimental) Asks an LLM whether each key's languages tell the user the same thing.
 
          Each key is judged in one request against an OpenAI-compatible endpoint (a local ollama by default). Findings are printed as notes with the model's reason and never fail the lint: the judge is tuned for recall, so treat every finding as a suggestion for inspection. Verdicts are cached, so re-runs only pay for changed keys.
 
          Use a capable model: in testing, 4B-class models missed real drift and hallucinated justifications, while `gemma4:12b` and `qwen3.5:9b` (Q4, 4K context) with medium reasoning effort worked well.
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --llm-base-url <URL>
          Base URL of the OpenAI-compatible endpoint
 
          [default: http://localhost:11434/v1]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --llm-model <MODEL>
          Model name as known to the endpoint
 
          [default: gemma4:12b]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --llm-api-key-env <ENV>
          Name of the environment variable holding the API key.
 
          Local servers ignore the key, so leaving the variable unset is fine.
 
          [default: OPENAI_API_KEY]
 
      --llm-concurrency <N>
          Maximum number of concurrent requests
 
          [default: 8]
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
      --llm-temperature <T>
          Sampling temperature. The default `0` keeps verdicts reproducible (and cacheable) across runs
 
          [default: 0]
 
      --llm-effort <EFFORT>
          Reasoning effort, for models that support it
 
          Possible values:
          - none:   Sends no reasoning-effort field
          - low:    Minimal reasoning; fastest, least reliable
          - medium: Balanced reasoning; the tested sweet spot for drift detection
          - high:   Maximal reasoning; slowest
 
          [default: medium]
 
      --llm-min-confidence <MIN>
          Minimum confidence a finding needs to be reported.
 
          Each finding carries the model's self-reported confidence (0 to 1), which is only loosely calibrated — treat it as a ranking of findings, not a probability. The default `0` reports everything, keeping recall maximal; raise it to trade recall for fewer false positives. The threshold applies after the verdict cache, so changing it re-filters cached verdicts without new requests.
 
          [default: 0]
 
      --llm-prompt <FILE>
          File with a custom judge prompt template.
 
          The template must contain the `{key}` and `{languages}` placeholders; all other braces pass through verbatim. Prompt wording strongly affects which findings a given model reports, and the best wording differs per model, so tune the template together with `--llm-model`.
 
      --llm-cache-capacity <N>
          Maximum number of cached verdicts kept on disk (least-recently-used eviction); `0` disables the cache entirely
 
          [default: 100000]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Useful groups:

--usages <DIR> is repeatable and enables unused-key scanning.
--dynamic-usages <POLICY> overrides config policies with allow, warn, or deny.
--call-usages <POLICY> overrides the undefined-key and argument checks the same way.
--no-ignore bypasses .ignore files in usage scans.
--no-gitignore bypasses .gitignore and Git exclude files in usage scans.
--no-duplicates disables both cross-key duplicate checks and identical-language checks.
--llm-judge enables semantic drift review.
--llm-base-url, --llm-model, and --llm-api-key-env select the endpoint.
--llm-concurrency, --llm-temperature, and --llm-effort control requests.
--llm-prompt loads a custom prompt containing {key} and {languages}.
--llm-min-confidence filters reported findings after the cache.
--cache-dir and --llm-cache-capacity control persisted verdicts.

The generated help above is captured from the working-tree binary during every documentation build, so it is the authoritative list when flags change.