# glotfile CLI reference

Run via `npx glotfile <command>` (or `node bin/glotfile.js <command>` from a checkout).
Every command accepts the global flags:

- `-f, --file <path>` — state file to use (default: `./glotfile.json`).
- `-h, --help` — show help. `glotfile <command> --help` shows a command's options.

The state file is auto-detected: a `glotfile/` directory (split layout) wins over a
single `glotfile.json`.

## serve
`glotfile serve [--dev]` — start the local web UI (the default command when none is
given). Opens a browser at a local URL. `--dev` runs the UI from source with hot reload
(the API runs on a separate port; open the Vite URL, not the API port). With
`config.autoExport` on (the default), serving re-exports to disk on every change.

## export
`glotfile export [--adapter <name>] [--watch]` — write the locale files for every
configured output in `config.outputs`.
- `--adapter <name>` — only export this adapter (e.g. `flutter-arb`, `laravel-php`).
- `--watch` — re-export whenever the state file changes.

Adapter names: `flutter-arb`, `laravel-php`, `i18next-json`, `vue-i18n-json`,
`gettext-po`, `apple-strings`, `apple-stringsdict`, `angular-xliff`, `rails-yaml`.

## translate
`glotfile translate [--all] [--estimate] [--locale <list>] [--key <glob>]` — AI-translate
strings into the target locales and write the results back into the state file.
- By default only **empty** values are translated (existing translations are left alone).
- `--all` — re-translate every string, overwriting existing translations.
- `--estimate` — print batch/token/cost estimates and translate nothing.
- `--locale fr,de` — restrict to these target locales (alias: `--locales`).
- `--key <glob>` — only keys matching the glob (e.g. `auth.*`).

Requires a configured AI provider + API key in per-machine local settings.

## lint
`glotfile lint [--format text|json|sarif] [--locale <list>] [--rule <list>] [--max-warnings <n>] [--include-suppressed] [--accept]`
— check the catalog for problems (placeholder mismatches, length, glossary violations,
spelling, identical-to-source, …).
- `--max-warnings <n>` — exit non-zero if warnings exceed n (for CI).
- `--accept` — suppress all current warnings (narrow with `--rule`/`--locale`); each
  suppression expires automatically when its key's source text changes.
- `--include-suppressed` — also show findings hidden by suppressions.

## check
`glotfile check [--format text|json|sarif]` — lint the catalog **and** verify the
exported files on disk are up to date. Use in CI to catch a state file that was changed
without re-exporting. Exits non-zero on any error.

## import
`glotfile import --format <name> [--source <dir>] [--source-locale <code>] [--locales <list>] [--cldr] [--force]`
— create `glotfile.json` from a project's existing locale files. See
`references/workflows.md` for the onboarding flow.
- `--source <dir>` — directory to import from (default: the state file's directory).
- `--source-locale <code>` — which locale is the source of truth.
- `--cldr` — expand CLDR plural forms.
- `--force` — overwrite an existing `glotfile.json`.

## build-context
`glotfile build-context [--all] [--key <glob>] [--limit <n>] [--since <date>]` —
AI-generate per-key context (where/how a string is used) to improve translation quality.
**Requires a prior `glotfile scan`** to index code references.

## scan
`glotfile scan` — index the codebase's references to translation keys, writing
`.glotfile/usage.json`. Feeds `build-context` and `prune --unused`.

## prune
`glotfile prune (--empty-source | --unused) [--write]` — remove keys. **Dry-run (lists
only) unless `--write` is given.**
- `--empty-source` — keys whose source value is empty.
- `--unused` — keys with no code reference (runs a scan first so the result is current).

## split
`glotfile split` — convert a single `glotfile.json` into a `glotfile/` directory
(`config.json`, `keys.json`, `locales/<code>.json`). Produces smaller, more reviewable
git diffs on large catalogs. All commands work with either layout.

## skill
`glotfile skill [--print] [--force]` — install this Claude Code skill into the current
repo's `.claude/skills/glotfile/`. `--print` writes `SKILL.md` to stdout instead;
`--force` overwrites an existing install.
