Documentation

CLI command reference

Command help from the source candidate. Published CLI 0.3.0 does not include the new source-aware and checkout-check additions. See the guide for setup, workflows and permissions.

On this pageGlobal options

Global options

The resource-check flags below require a candidate containing these source additions. They are unavailable in published CLI 0.3.0; an older CLI must refuse them.

CLI setup and workflow guide

Code example

Show full Code example

Usage: lingvo [<options>] <command> [<args>]...

  Sync localization files, inspect translation progress, and run machine
  translation.

Options:
  --api-url=<text>  Override the Lingvo API URL
  --project=<text>  Override the configured project slug
  --json            Print machine-readable JSON
  --no-color        Disable ANSI colors
  --version         Show the version and exit
  -h, --help        Show this message and exit

Commands:
  init       Detect localization files and scaffold lingvo.yaml.
  project    Set up the hosted project for this repository.
  login      Authenticate with an API token or email and password.
  logout     Remove locally stored credentials for the active API URL.
  whoami     Show the user authenticated for the active API URL.
  auth       Inspect how the CLI will authenticate.
  push       Upload configured source files or existing translations.
  pull       Download translations into configured repository paths.
  status     Show translation progress for every project locale.
  scan       Record where this project's strings are used in your source.
  verify     Prove a round trip: upload sources, download them again, and diff
             against disk.
  usage      Show the workspace plan, seats, and machine-translation credits.
  keys       Inspect translation keys.
  export     Export one translated file or a zip bundle.
  qa         Check hosted QA, or captured checkout resources with --local.
  sync       Push source files, then safely pull translations.
  watch      Watch configured source files and push them when they change.
  translate  Machine-translate project keys and stream progress.
  propose    Suggest a translation for review. Writes no translation.
  validate   Check lingvo.yaml, the configured paths and the source files. No
             network.
  diff       Show what differs between the repository and Lingvo. Writes
             nothing.
  explain    Explain a locale, a file format, a QA check or an error code.
             Offline.
  complete   List the locales, formats, projects or keys that actually exist.
  plurals    Inspect, check and fill the plural categories a language requires.
  providers  List, configure, and test machine-translation providers.
  generate   Generate typed Kotlin or Swift accessors for project keys.
  describe   Print a machine-readable description of every command.
  mcp        Serve Lingvo to an MCP client over stdio.
  agent      Set an MCP client up against this repository.

Setup and authentication

lingvo init

Code example

Usage: lingvo init [<options>]

  Detect localization files and scaffold lingvo.yaml.

Options:
  --source-locale=<text>  Source locale used by files in the repository
  --force                 Replace an existing lingvo.yaml
  -h, --help              Show this message and exit

lingvo project

Code example

Usage: lingvo project [<options>] <command> [<args>]...

  Set up the hosted project for this repository.

Options:
  -h, --help  Show this message and exit

Commands:
  create  Create the configured project in a named workspace, ready for push.

lingvo project create

Code example

Usage: lingvo project create [<options>]

  Create the configured project in a named workspace, ready for push.

Options:
  --workspace=<text>  Workspace slug that will own the project
  --name=<text>       Display name; defaults to the configured project slug
  --locale=<text>     Target locale; repeat for each language
  -h, --help          Show this message and exit

Code example

Usage: lingvo login [<options>]

  Authenticate with an API token or email and password.

Options:
  --token=<text>     API token. Prefer --token-stdin or --token-env: a token on
                     the command line is recorded in shell history and visible
                     in process listings.
  --token-env=<var>  Read the API token from this environment variable.
  --token-stdin      Read the API token from standard input.
  --email=<text>     Account email; prompted when omitted
  --device           Pair with a browser instead of typing a password or a
                     token
  -h, --help         Show this message and exit

lingvo logout

Code example

Usage: lingvo logout [<options>]

  Remove locally stored credentials for the active API URL.

Options:
  -h, --help  Show this message and exit

lingvo whoami

Code example

Usage: lingvo whoami [<options>]

  Show the user authenticated for the active API URL.

Options:
  -h, --help  Show this message and exit

lingvo auth

Code example

Usage: lingvo auth [<options>] <command> [<args>]...

  Inspect how the CLI will authenticate.

Options:
  -h, --help  Show this message and exit

Commands:
  status  Show which credential and API URL would be used, without calling the
          server.

lingvo auth status

Code example

Usage: lingvo auth status [<options>]

  Show which credential and API URL would be used, without calling the server.

Options:
  -h, --help  Show this message and exit

Synchronization

lingvo push

Code example

Usage: lingvo push [<options>]

  Upload configured source files or existing translations.

Options:
  --dry-run                 Validate and show uploads without changing Lingvo
  --file=<text>             Configured source path to upload
  --obsolete-missing        Mark keys the pushed files no longer contain as
                            obsolete. Off by default.
  --keep-obsolete           Accepted and ignored: keys missing from source
                            files are kept by default now.
  --confirm-obsolete=<int>  Confirm this exact number of keys should be marked
                            obsolete, when the server asks
  --translations            Upload configured translated files instead of
                            sources
  --locale=<text>           Upload translations for one locale
  -h, --help                Show this message and exit

lingvo pull

Code example

Usage: lingvo pull [<options>]

  Download translations into configured repository paths.

Options:
  --locale=<text>  Download one target locale
  --dry-run        Show what would be written without changing any file
  --fallback       Use source strings when translations are empty
  --format=<text>  Override the configured export format
  --approved-only  Write only translations a reviewer has approved
  -h, --help       Show this message and exit

lingvo sync

Code example

Usage: lingvo sync [<options>]

  Push source files, then safely pull translations.

Options:
  --dry-run                 Show uploads, writes, and conflicts without
                            changing data
  --adopt-local             Upload locally edited translations instead of
                            reporting conflicts
  --locale=<text>           Sync one target locale
  --fallback                Fall back to source values on pull
  --obsolete-missing        Mark keys the pushed files no longer contain as
                            obsolete. Off by default.
  --keep-obsolete           Accepted and ignored: keys missing from source
                            files are kept by default now.
  --confirm-obsolete=<int>  Confirm this exact number of keys should be marked
                            obsolete, when the server asks
  -h, --help                Show this message and exit

lingvo watch

Code example

Usage: lingvo watch [<options>]

  Watch configured source files and push them when they change.

Options:
  --obsolete-missing        Mark keys the changed files no longer contain as
                            obsolete. Off by default.
  --keep-obsolete           Accepted and ignored: keys removed from changed
                            source files are kept by default now.
  --confirm-obsolete=<int>  Confirm this exact number of keys should be marked
                            obsolete, when the server asks
  -h, --help                Show this message and exit

Inspection and quality

lingvo status

Code example

Usage: lingvo status [<options>]

  Show translation progress for every project locale.

Options:
  -h, --help  Show this message and exit

lingvo verify

Code example

Usage: lingvo verify [<options>]

  Prove a round trip: upload sources, download them again, and diff against
  disk.

Options:
  --file=<text>  Configured source path to verify
  --push         Upload the sources first. Off by default: verification should
                 not change anything.
  -h, --help     Show this message and exit

lingvo usage

Code example

Usage: lingvo usage [<options>]

  Show the workspace plan, seats, and machine-translation credits.

Options:
  -h, --help  Show this message and exit

lingvo keys

Code example

Usage: lingvo keys [<options>] <command> [<args>]...

  Inspect translation keys.

Options:
  -h, --help  Show this message and exit

Commands:
  list  List and filter keys in the active project.

lingvo keys list

Code example

Usage: lingvo keys list [<options>]

  List and filter keys in the active project.

Options:
  --file=<text>    Filter by configured file path or file ID
  --search=<text>  Search key names or source values
  --state=<text>   Filter EMPTY, TRANSLATED, or APPROVED
  --locale=<text>  Target locale shown in the result
  --limit=<int>    Maximum keys to return
  -h, --help       Show this message and exit

lingvo export

Code example

Usage: lingvo export [<options>]

  Export one translated file or a zip bundle.

Options:
  --bundle         Export all files as a zip bundle
  --all            Export everything: strings, translation memory, glossary,
                   comments and history
  --out=<text>     Output file path
  --file=<text>    Configured file path or remote file ID
  --locale=<text>  Locale to export; repeat for bundles
  --format=<text>  Override export format
  --fallback       Fall back to source values
  -h, --help       Show this message and exit

lingvo qa

Code example

Usage: lingvo qa [<options>]

  Check hosted QA, or captured checkout resources with --local.

Options:
  --locale=<text>             Limit QA to one locale
  --local                     Check configured checkout resources without
                              credentials or network
  --locales=<text>            Explicit comma-separated target locales for
                              --local
  --require-reviewed-current  Require a hosted reviewed/current verdict for the
                              captured local resources
  --tag=<text>                Gate on the keys carrying this tag, for a frozen
                              release scope
  --fail-on=(none|error|warning)
                              Exit 1 on issues at this level: none, error,
                              warning. Reviewed-current uses hosted rules and
                              cannot waive its required policy.
  --fail-on-error             Deprecated alias for --fail-on error
  -h, --help                  Show this message and exit

lingvo validate

Code example

Usage: lingvo validate [<options>]

  Check lingvo.yaml, the configured paths and the source files. No network.

Options:
  -h, --help  Show this message and exit

lingvo diff

Code example

Usage: lingvo diff [<options>]

  Show what differs between the repository and Lingvo. Writes nothing.

Options:
  --locale=<text>  Compare one target locale
  -h, --help       Show this message and exit

Translation and providers

lingvo translate

Code example

Usage: lingvo translate [<options>]

  Machine-translate project keys and stream progress.

Options:
  --locale=<text>    Target locale
  --provider=<text>  Translation provider ID
  --only-empty       Translate only empty values
  --tone=<text>      Requested translation tone, such as formal
  --dry-run          Generate suggestions without saving them
  -h, --help         Show this message and exit

lingvo propose

Code example

Usage: lingvo propose [<options>]

  Suggest a translation for review. Writes no translation.

Options:
  --locale=<text>           Target locale, e.g. de.
  --key=<text>              Key name.
  --value=<text>            The proposed text, for a singular string.
  --plural=<category=text>  A plural form, as category=text. Repeat for every
                            category the language uses.
  --rationale=<text>        Why you chose this wording. At most 500 characters.
  --confidence=<text>       How sure you are: high, medium, low. A reviewer
                            reads the low ones first.
  --run=<text>              Groups this proposal with the rest of the pass, so
                            a reviewer can accept them together. Any UUID;
                            reuse it across the whole run.
  -h, --help                Show this message and exit

lingvo providers

Code example

Usage: lingvo providers [<options>] <command> [<args>]...

  List, configure, and test machine-translation providers.

Options:
  -h, --help  Show this message and exit

Commands:
  list  List provider settings without exposing secret keys.
  set   Configure a provider; secret keys are read from stdin or an environment
        variable.
  test  Run a one-string provider connection test.

lingvo providers list

Code example

Usage: lingvo providers list [<options>]

  List provider settings without exposing secret keys.

Options:
  -h, --help  Show this message and exit

lingvo providers set

Code example

Usage: lingvo providers set [<options>] <provider>

  Configure a provider; secret keys are read from stdin or an environment
  variable.

Options:
  --key-env=<text>   Read the API key from this environment variable
  --base-url=<text>  Provider-specific base URL
  --model=<text>     Provider-specific model
  --disable          Disable the provider
  -h, --help         Show this message and exit

Arguments:
  <provider>  Provider ID

lingvo providers test

Code example

Usage: lingvo providers test [<options>] <provider>

  Run a one-string provider connection test.

Options:
  -h, --help  Show this message and exit

Arguments:
  <provider>  Provider ID

Locales and explanations

lingvo explain

Code example

Usage: lingvo explain [<options>] <command> [<args>]...

  Explain a locale, a file format, a QA check or an error code. Offline.

Options:
  -h, --help  Show this message and exit

Commands:
  locale  The plural categories, writing direction and quote marks a language
          really uses.
  format  What a file format can and cannot represent.
  check   What a QA check looks for, and whether it blocks a release.
  error   What an error code means and what to do about it.

lingvo explain locale

Code example

Usage: lingvo explain locale [<options>] <tag>

  The plural categories, writing direction and quote marks a language really
  uses.

Options:
  -h, --help  Show this message and exit

Arguments:
  <tag>  A BCP-47 tag, e.g. ru.

lingvo explain format

Code example

Usage: lingvo explain format [<options>] <format>

  What a file format can and cannot represent.

Options:
  -h, --help  Show this message and exit

Arguments:
  <format>  A format id, e.g. android_xml.

lingvo explain check

Code example

Usage: lingvo explain check [<options>] <check>

  What a QA check looks for, and whether it blocks a release.

Options:
  -h, --help  Show this message and exit

Arguments:
  <check>  A check name, e.g. placeholder_mismatch.

lingvo explain error

Code example

Usage: lingvo explain error [<options>] <code>

  What an error code means and what to do about it.

Options:
  -h, --help  Show this message and exit

Arguments:
  <code>  An error code, e.g. bulk_change_requires_force.

lingvo complete

Code example

Usage: lingvo complete [<options>] <command> [<args>]...

  List the locales, formats, projects or keys that actually exist.

Options:
  -h, --help  Show this message and exit

Commands:
  locale   Locale tags Lingvo knows, filtered by prefix. Offline.
  format   File format ids. Offline.
  project  Project slugs this credential can reach.
  key      Key names in this project.

lingvo complete locale

Code example

Usage: lingvo complete locale [<options>]

  Locale tags Lingvo knows, filtered by prefix. Offline.

Options:
  --prefix=<text>  Only tags starting with this
  -h, --help       Show this message and exit

lingvo complete format

Code example

Usage: lingvo complete format [<options>]

  File format ids. Offline.

Options:
  --prefix=<text>  Only ids starting with this
  -h, --help       Show this message and exit

lingvo complete project

Code example

Usage: lingvo complete project [<options>]

  Project slugs this credential can reach.

Options:
  --prefix=<text>  Only slugs starting with this
  -h, --help       Show this message and exit

lingvo complete key

Code example

Usage: lingvo complete key [<options>]

  Key names in this project.

Options:
  --prefix=<text>  Only names starting with this
  --locale=<text>  Which locale's page to read. Defaults to the source.
  -h, --help       Show this message and exit

lingvo plurals

Code example

Usage: lingvo plurals [<options>] <command> [<args>]...

  Inspect, check and fill the plural categories a language requires.

Options:
  -h, --help  Show this message and exit

Commands:
  required  The CLDR categories a language requires. Offline.
  check     Fail if any plural key is missing a category the language requires.
  set       Propose a complete plural set. Refuses a partial one.

lingvo plurals required

Code example

Usage: lingvo plurals required [<options>]

  The CLDR categories a language requires. Offline.

Options:
  --locale=<text>  A BCP-47 tag, e.g. ru.
  -h, --help       Show this message and exit

lingvo plurals check

Code example

Usage: lingvo plurals check [<options>]

  Fail if any plural key is missing a category the language requires.

Options:
  --locale=<text>  Target locale to check.
  -h, --help       Show this message and exit

lingvo plurals set

Code example

Usage: lingvo plurals set [<options>]

  Propose a complete plural set. Refuses a partial one.

Options:
  --locale=<text>         Target locale.
  --key=<text>            Key name.
  --form=<category=text>  A plural form, as category=text. Repeat for every
                          category the language uses.
  -h, --help              Show this message and exit

Code and source references

lingvo scan

Code example

Usage: lingvo scan [<options>]

  Record where this project's strings are used in your source.

Options:
  --include=<text>  File extensions to read, comma separated. Defaults to
                    common source languages.
  --snippets, --no-snippets / --no-snippets
                    Send the matching line of source alongside its path and
                    line number, so a translator can see the string in place.
                    On by default; --no-snippets sends only the path and line.
  --dry-run         Report what the scan found without sending anything
  -h, --help        Show this message and exit

lingvo generate

Code example

Usage: lingvo generate [<options>]

  Generate typed Kotlin or Swift accessors for project keys.

Options:
  -h, --help  Show this message and exit

Agents and discovery

lingvo describe

Code example

Usage: lingvo describe [<options>]

  Print a machine-readable description of every command.

Options:
  -h, --help  Show this message and exit

lingvo mcp

Code example

Usage: lingvo mcp [<options>]

  Serve Lingvo to an MCP client over stdio.

Options:
  --read-only  Offer only tools that cannot change anything
  -h, --help   Show this message and exit

lingvo agent

Code example

Usage: lingvo agent [<options>] <command> [<args>]...

  Set an MCP client up against this repository.

Options:
  -h, --help  Show this message and exit

Commands:
  install  Write an MCP config and a generated skill into this repository.

lingvo agent install

Code example

Usage: lingvo agent install [<options>]

  Write an MCP config and a generated skill into this repository.

Options:
  --client=<text>     Which client to set up: claude, codex, claude-desktop,
                      cursor, ci, or all.
  --transport=<text>  local runs `lingvo mcp` as you; remote uses an agent
                      connection's token.
  --print             Write nothing and show what would be written, for pasting
                      by hand.
  --force             Overwrite files that already exist.
  -h, --help          Show this message and exit