CLI Commands

Complete reference for every Polyglot CLI command.

polyglot start

Prepare a local first-screen plan or resume its saved journey by omitting --file. Use a source file and a target language in the selected app. The route is guidance for verifying your screen, not an instruction to rewrite the router. Planning and wrapping do not require authentication.

polyglot start --file src/app/page.tsx --lang fr --route /fr
polyglot start
polyglot start --json

polyglot doctor

Discover app roots with --apps, then run doctor inside the selected app. Plain output and --json explain framework/router mode, installed versus declared runtime versions, catalogs, package manager and unknown setup. --diagnostics writes a bounded private support file with no upload; see Troubleshooting for exactly what it includes.

polyglot doctor --apps
polyglot doctor
polyglot doctor --json
polyglot doctor --diagnostics polyglot-support.json

polyglot init

Interactive setup wizard. Auto-detects your framework, asks for target languages, and creates polyglot.toml.

polyglot init [OPTIONS]

Options:
      --languages <LANGS>  Target languages, comma-separated. Skips the
                           interactive prompt — makes init scriptable for
                           CI/Docker/automation.
      --framework <NAME>   Framework to use, bypassing auto-detection. One of:
                           nextjs, astro, sveltekit, reactnative, flutter,
                           vue, angular.
      --local              Skip hosted linking; configure locally
      --yes                Update explicit choices without prompting;
                           preserve customized settings and comments

Fully scriptable: pass --languages and --framework together to run init with no prompts (CI, Docker, scaffolding scripts). --framework also overrides auto-detection when it guesses wrong; without a TTY, a detection miss exits with a clear error naming the flag instead of hanging.

polyglot link

Bind this repo to an existing project — the explicit alternative to the automatic create-on-first-use. Writes the committed project_id binding.

polyglot link [PROJECT] [OPTIONS]

Arguments:
  [PROJECT]  Project to link by id or name (omit for an interactive picker)

Options:
      --yes  Non-interactive: requires the project argument

polyglot invite

Invite a teammate to this project. Reviewers are free on every plan — only admins use a developer seat.

polyglot invite <EMAIL> [OPTIONS]

Options:
      --role <ROLE>  reviewer (default — can edit and approve translations),
                     viewer (read-only), or admin (uses a developer seat)

polyglot languages

List supported translation languages, search by name or code, or add languages to your project interactively. Solves the "I want German but I don't remember if the code is de or ger" problem.

polyglot languages              # Browse the catalog
polyglot languages search japan # Filter by name or code
polyglot languages add          # Pick interactively (multi-select)

The picker (languages add) shows your currently-configured languages pre-checked, validates the new list against your plan's language cap before writing, then updates both polyglot.toml and your project's backend record. For CI, use polyglot translate --languages <codes> instead — it auto-extends polyglot.toml the same way without needing interactive input.

polyglot scan

Detect untranslated strings in your codebase using tree-sitter parsing.

polyglot scan [OPTIONS]

Options:
  -f, --format <FORMAT>  Output format: table, json [default: table]
  -j, --jobs <N>         Parallel threads (default: CPU cores)

The scanner uses AST-level analysis to find user-facing strings while filtering out imports, type annotations, CSS classes, URLs, and other non-translatable content.

polyglot translate

Send detected strings to the Polyglot API and write translation files.

polyglot translate [OPTIONS]

Options:
  -l, --languages <LANGS>       Target languages, comma-separated. Accepts
                                ISO codes (de) or English names (German).
      --plan <PLAN_ID>          Limit work to this saved plan's changed source keys
      --estimate                Report local pending work without an API call
      --force                   Skip cache, retranslate everything
      --format <FORMAT>         Output format: json or yaml; Flutter uses ARB
      --ci                      CI mode: translate + validate + coverage check
      --coverage-threshold <N>  Min coverage % in CI mode [default: 100]
      --ephemeral               Translate to a one-off language without saving
                                it to polyglot.toml or the project record

Without --languages, translates into all languages defined in polyglot.toml. With --languages, new codes are auto-added to polyglot.toml after a tier-cap check passes — your config catches up to what you've actually translated.

Don't remember the code for a language? Just pass the English name — polyglot translate --languages German,French resolves to de,fr. Or browse the catalog with polyglot languages.

Incremental by default — only new or changed strings are sent. Use --force to retranslate everything.

Estimate and retry semantics

--estimate reports pending string/language work and local reuse without a hosted request; it cannot know hosted cache hits or quote an exact currency charge. --plan scopes work to that plan’s new or changed source keys after apply. Keep its ID when authentication or a partial provider failure requires a retry. Successful siblings and human approvals are preserved.

polyglot translate --plan <plan-id> --languages fr --estimate
polyglot translate --plan <plan-id> --languages fr

polyglot check

Run the same differential policy check that CI runs: compare an immutable base revision against a head revision, classify findings as new, existing, or resolved, and evaluate your policy.

polyglot check --base <REVISION> [OPTIONS]

Options:
      --base <REVISION>         Immutable base Git revision (required)
      --head <REVISION>         Git revision to evaluate [default: HEAD]
      --config-path <PATH>      Project-relative polyglot.toml [default: polyglot.toml]
      --policy <POLICY>         Policy JSON, a path to a JSON policy, or a named preset
      --policy-source <SOURCE>  managed, repository, or explicit
  -f, --format <FORMAT>         Output: table, json [default: table]

The exit code is the gate — zero means the configured policy passed. This is the command the open GitHub Action and Polyglot Automation both execute.

polyglot push

Seed your project's translation memory from the locale files already in your repo. The dashboard reconciles coverage against your project's backend memory — not your repo — so if you translated locally, or before a fix landed, the backend can lag behind. polyglot push closes that gap so it stops re-translating work you already have.

polyglot push

It reads your source and target locale files, pairs each string's source value with its existing translations, and uploads only the ones the backend is missing. No new translation is generated and nothing is billed — it just stores work you already did.

It never overwrites an existing translation — pairs already in memory come back as skipped — so it's safe to re-run any time your repo is ahead of the dashboard. Requires authentication; run polyglot auth login first.

polyglot pull

Materialize reviewed translations into your local catalogs. The flag is required — pending and rejected work is never written to disk.

polyglot pull --approved-only

This is the CLI fallback for teams that want approved translations without granting the Publisher App write access to the repository.

polyglot catalogs

Manage the keyed, repository-bound catalog manifest that Polyglot Automation synchronizes. catalogs sync uploads a complete, hashed catalog snapshot for the current Git commit; catalogs apply applies an immutable approved-translation manifest after differential verification — normally run by the managed workflow, not by hand.

polyglot catalogs sync
polyglot catalogs apply --manifest <PATH>

polyglot coverage

Report translation coverage by language.

polyglot coverage [OPTIONS]

Options:
  -f, --format <FORMAT>  Output: table, json, badge [default: table]
      --by-file          Show per-file breakdown

polyglot diff

Show what changed since the last translation run.

polyglot diff [OPTIONS]

Options:
  -f, --format <FORMAT>  Output: table, json [default: table]

Compares the current scan results against the .polyglot-cache.json to identify new, modified, and removed strings.

polyglot validate

Check translation files for interpolation errors, missing placeholders, and length issues.

polyglot validate [OPTIONS]

Options:
  -f, --format <FORMAT>  Output: table, json [default: table]

polyglot preview

Preview translations in your local dev server. See Preview for details.

polyglot preview [OPTIONS]

Options:
  -l, --lang <LANG>       Language to preview. Auto-picks the single
                          configured language, or prompts interactively
                          when multiple are configured.
      --pseudo            Offline accented/expanded source; requires source catalog
      --route <ROUTE>     App-relative route to open (for example /fr/settings)
      --no-serve          Generate preview locale files to a temp dir
                          instead of starting the dev server
      --cmd <CMD>         Custom dev server command
      --no-open           Don't open browser
      --compare <A>,<B>   HTML catalog comparison, not two running app screens

polyglot glossary

Manage glossary terms. See Glossary for details.

polyglot glossary <ACTION> [OPTIONS]

Actions: list, add, remove, import

Options:
  -t, --term <TERM>             Term to add/remove
      --translation <TEXT>      Translation for the term
  -l, --lang <LANG>             Target language
  -c, --context <NOTE>          Context note
      --do-not-translate        Mark as "do not translate"
      --file <PATH>             CSV file to import
  -f, --format <FORMAT>         Output: table, json [default: table]

polyglot export

Export translation files to a different format without the backend.

polyglot export [OPTIONS]

Options:
  -f, --format <FORMAT>     Target format: json, yaml, arb, strings, xml
  -o, --output <DIR>        Output directory
  -l, --languages <LANGS>   Languages, comma-separated

polyglot wrap

Auto-replace hardcoded strings with translation function calls. See Auto-Wrap for details.

Saved-plan wrapping

Create a complete plan, inspect it, then apply the same plan ID. File scope includes required catalog/setup companions. --dry-run is a current-source report; it is not the durable plan identity. Source/configuration/dependency or executable changes can invalidate a saved plan.

polyglot wrap --plan --file src/app/page.tsx --json
polyglot wrap --show <plan-id>
polyglot wrap --apply <plan-id>

# Other wrapping controls:
polyglot wrap --dry-run --file src/app/page.tsx
polyglot wrap --report ./wrap-report
polyglot wrap --no-report
polyglot wrap --strict-wiring
polyglot wrap --translation-fn t

polyglot runs / polyglot undo

runs lists local recovery records; --json exposes an array including each run’s kind. undo takes a run ID, not a plan ID. --diff inspects recovery without writing. An omitted run ID selects the latest run with changes; explicit IDs are safer when multiple operations have run.

A nonzero wrap exit may accompany committed writes, including --strict-wiring warnings. Read the execution state and inspect the journal before retrying. Undo refuses later-edit conflicts and preserves unrelated files; remote approvals and merged PRs are outside local recovery.

polyglot runs
polyglot runs --json
polyglot undo <run-id> --diff
polyglot undo <run-id>

polyglot report-schema

Print the canonical v4 wrap-report JSON Schema for integrations. Candidate counts, review groups, execution/commit state and syntax/wiring/build/runtime evidence have distinct meanings. A report must not hide an unsuccessful exit or an unexecuted runtime check.

polyglot report-schema

polyglot study

Opt in to a local study only after configuring the app. Records are never uploaded automatically. --export prints them, --disable deletes the session, and a new session requires deleting the old one after any chosen export.

Accepted user-reported outcomes are runtime_verified, patch_kept, assistance_required and abandoned. Record actual observations; command completion cannot establish language quality or unassisted success.

polyglot study --enable
polyglot study --record runtime_verified
polyglot study --record patch_kept
polyglot study --export
polyglot study --disable

polyglot add

Scaffold owned UI code into your repo — code you own and restyle, no runtime lock-in. Currently: the language switcher. See Language Switcher for the full guide.

polyglot add switcher [OPTIONS]

Options:
      --framework <NAME>  Override framework detection
      --dir <PATH>        Target directory [default: src/components]
      --force             Overwrite files that already exist

polyglot auth

Manage authentication.

polyglot auth login     # Sign in via browser
polyglot auth logout    # Remove credentials
polyglot auth status    # Show current auth state

Credentials are stored at ~/.config/polyglot/credentials.json.

polyglot hook

Manage git hooks for automatic string detection on commit.

polyglot hook install     # Add pre-commit hook
polyglot hook uninstall   # Remove pre-commit hook

polyglot screenshot

Capture screenshots of pages in different languages.

polyglot screenshot [OPTIONS]

Options:
  -l, --languages <LANGS>   Languages, comma-separated
  -u, --urls <URLS>         URLs to capture [default: /]
      --base-url <URL>      Dev server URL [default: http://localhost:3000]
  -o, --output <DIR>        Output directory [default: polyglot-screenshots]
      --width <PX>          Viewport width [default: 1280]
      --height <PX>         Viewport height [default: 720]
      --report              Generate comparison HTML report

Saved plans and recovery · Troubleshooting and support