CLI reference

What the CLI is#

Localization OS ships a command-line interface alongside its web UI. Nearly everything you can do in the browser has a command here: create customers and projects, upload and translate documents, manage translation memory and glossaries, build and run workflows, mint API keys, and administer the install, all without a browser. It's built for CI, containers, and scripting. The CLI and the web UI share the same underlying services, so a project created from a script and one created by hand in the UI are indistinguishable. Every command and subcommand supports --help.

Installing and running it#

The CLI has no separate install step. It runs in-process against a working Localization OS checkout:

python -m app.cli <command> [args...]

Wrapper scripts at the repo root forward to the same entry point on Windows:

.\loc-tms.ps1 <command> [args...]   # PowerShell
loc-tms.cmd <command> [args...]     # cmd.exe

Optionally, pip install -e . from the repo root registers a real loc-tms console command, so you can drop the python -m prefix. This is purely a convenience: the CLI's runtime dependencies are the same ones the server and container image already install, so all three forms behave identically.

pip install -e .        # once, in the project virtualenv
loc-tms health           # -> the same in-process CLI

The examples on this page use loc-tms for brevity. Substitute python -m app.cli or a wrapper script as you prefer.

Authentication and identity#

A CLI command runs one of two ways.

In-process (the default)

The CLI acts as the local operator, at the same trust level as direct access to the underlying database. There's no login and no per-command role check: if the install can do it, this mode can do it. Commands are attributed to the acting operator for the audit trail. Commands that make an irreversible change (deleting a project, purging retained data, revoking every key a user holds) ask for confirmation unless you pass --yes, which is required in non-interactive, --json, or --quiet runs.

Before any command runs, the CLI loads the install's stored settings (default provider, per-provider model, keys) exactly as the web server does at boot, so a CLI translation run resolves the same engine a web-triggered one would. A provider key stored in the install takes precedence over the same key supplied only as an environment variable, on both surfaces.

Remote (--remote URL --token <your-api-key>)

A remote-capable command instead becomes a thin HTTP client of a running server's API, authenticated by a per-user API key. Authorization happens entirely server-side, scoped to the token's own organization: a remote call can never see or touch more than that person could see in the web UI, however privileged the local operator running the command happens to be. Behavior is otherwise transport-independent: the same intent, the same output shape, a human table or --json.

• An unreachable server exits 3.
• A rejected request (a permissions failure, a validation error) exits 1 with the server's own message.
• A remote --json response can carry a few extra envelope fields, such as a server-resolved scope, that the in-process form doesn't emit; the underlying rows match.
• Error wording differs slightly by transport, so branch on the exit code in scripts, never on the message text.

A command with no remote form refuses cleanly at exit 2 when you pass --remote, rather than silently running against the local host.

Remote capability at a glance#

Remote capability is decided per command, not per group: a subcommand is reachable over --remote exactly where a matching API route exists. This table is a starting map; the sections further down and each command's own --help confirm the exact leaf.

Global flags#

Global flags precede the subcommand: loc-tms --json config get org_name.

Exit codes: 0 ok · 1 operation failure · 2 usage error · 3 remote unreachable.

Database, backup, and health#

Schema migrations, backup and restore, and integrity checks, for an install with no server running.

loc-tms db migrate
loc-tms db backup --full backup-2026-08-31.tar.gz
loc-tms db verify-backup backup-2026-08-31.tar.gz
loc-tms health

Configuration#

Thin wrappers over the same settings store the web Settings UI writes, so there's one source of truth either way. It's also the way to reach settings that have a store but no dedicated form yet; config list is the authoritative inventory.

loc-tms config get org_name
loc-tms config set org_name "Acme Inc."
loc-tms config apply settings.toml --dry-run

Enterprise features#

One door that turns optional enterprise capabilities on and off: OpenTelemetry tracing, Prometheus metrics, SAML 2.0 SSO, SCIM 2.0 provisioning, PII redaction, the durable job queue, and S3-compatible blob storage. It's the CLI twin of the web enterprise settings panel. Because flipping one of these changes a trust boundary, every verb runs host-only and refuses --remote. Each feature has a preflight check that runs against its proposed configuration before the switch flips, so a missing dependency or a bad endpoint is caught here rather than at the next restart. Every feature takes effect at boot, so restart the server after enabling one.

Feature keys: otel, metrics, saml, scim, pii_ner, jobqueue, s3.

loc-tms config set otel_endpoint http://collector.example.com:4318/v1/traces
loc-tms enterprise preflight otel
loc-tms enterprise enable otel
loc-tms enterprise status

The LLM Ledger#

Control and read the LLM Ledger: an opt-in, read-only recorder of the exact request payload sent to a model on each completion call, so you can see what actually went out even when a local model's own logs truncate it. Off by default; nothing is written until you turn it on, and API keys are never recorded. It's a host-local surface with no remote arm.

loc-tms prompt-tap on
loc-tms prompt-tap export --provider local --tail 50 > local.jsonl

Bootstrap#

init brings the schema up and, only if no user exists yet, seeds the first admin and turns on the login wall. It's idempotent: on an already-seeded install it no-ops and says so, so it's safe to run on every boot.

python -m app.cli init --admin-email admin@example.com --admin-password 'a-strong-passphrase' --issue-key

# or from the environment, for containers and CI
LOC_TMS_ADMIN_EMAIL=admin@example.com LOC_TMS_ADMIN_PASSWORD='a-strong-passphrase' \
  python -m app.cli init --from-env

--issue-key mints a per-user API key and prints it once, so store it immediately; it can't be recovered afterward.

A password passed as a flag argument is visible in shell history and process listings; prefer the --from-env form for containers and CI.

Ask and draft#

Ask answers plain-language questions about a module, grounded only in that module's own shipped guide, the same text the in-app help pages render, so an answer and a help page can never disagree. Draft turns plain-language intent into a pre-filled form you confirm: it writes nothing on its own, printing the drafted values plus the exact existing command that would apply them.

Neither verb writes or launches anything without an explicit --apply --yes; without --apply each just prints what it would do. Both run on a configured assist engine and are billed like any other model call when that engine is a paid one.

loc-tms ask memories "how do I stop it translating our product name?"
loc-tms memory draft "we never translate Acme Cloud" --customer 1 --apply --yes
loc-tms eval draft "is the new model better on my support articles?" --customer 1

Customers and projects#

Customers and projects are the top of the content hierarchy: a project belongs to a customer, holds one or more target locales, and is where documents, translation memory, and glossaries attach.

Customers

Everything else in the customer group (show, update, pairs add / remove, archive, set-default, and similar) is in-process only.

Projects

Project templates

loc-tms customer create "Acme Corp"
loc-tms project create "Handbook" --source en-US --targets "fr-FR,de-DE" --customer-id 1
loc-tms project leverage 1

Documents#

Upload, translate, and export the files inside a project. The CLI shares the same translation, quality, and export services the web editor uses, so a document translated headlessly carries the same checks (tag integrity, glossary and do-not-translate enforcement, placeholder and number checks) as one translated by hand.

A workflow that fills a segment from translation memory before any model call can leave some targets empty on purpose, held back from delivery until a person signs off. doc empties, doc deliver-approve, and doc deliver-revoke list and clear that hold.

loc-tms doc upload 1 ./handbook.docx
loc-tms -v doc translate 1 --locale fr-FR
loc-tms doc export 1 --locale fr-FR -o handbook.fr-FR.docx

The same commands work against a running server with --remote. doc translate enqueues one job per locale; poll it with job status --remote:

loc-tms --remote https://tms.example.com --token <your-api-key> doc upload 1 ./handbook.docx
loc-tms --remote https://tms.example.com --token <your-api-key> doc translate 5 --locale fr-FR
loc-tms --remote https://tms.example.com --token <your-api-key> job status 9

Translation memory and glossaries#

Per-project translation memory and glossaries, plus customer-owned "module" glossaries that can be pinned across projects and carry their own approval lifecycle.

Translation memory

Glossaries

Module glossaries

loc-tms tm import 1 corpus.tmx --source en-US --target fr-FR
loc-tms glossary module create "Brand terms" --customer 1
loc-tms glossary module add-term 3 "Acme Cloud" --target-term "Acme Cloud" --dnt
loc-tms glossary module approve 3

Style guides and language sets#

A style guide is a long-form, approvable block of guidance injected into translation prompts for a customer, content type, or language pair. A Language Set is a reusable named list of target locales, so a project can be created against "our core markets" instead of typing the list out each time.

Style guides

Language sets

loc-tms style-guide create "Acme voice" --customer 1 --body-file voice.md
loc-tms style-guide set-status 1 approved
loc-tms langset create "Core markets" --source en-US --targets "fr-FR,de-DE,es-ES,ja-JP"

Workflows and jobs#

A workflow is an ordered pipeline of steps, translate, quality review, human review, translation-memory match, or dispatch to an external vendor, run over a document and locale. Runs execute synchronously in the CLI process, since a one-shot command has no background worker to hand off to: when a run command returns, its database state is final.

Jobs

Workflows

Batches and multilingual groups

loc-tms workflow create --name "EN to FR review" --scope global
loc-tms workflow add-step 1 --type llm_agent --name Translator --prompt 'Translate: {text}'
loc-tms workflow add-step 1 --type human_review --name "In-country review"
loc-tms workflow run 42 1 fr-FR
loc-tms workflow show-run 5
loc-tms workflow resume 5 --edited-text "reviewed text" --locale fr-FR

Memory#

Typed, scoped memories learned from workflow events (reviewer corrections, quality findings) or written by hand, then recalled selectively into later translate prompts. Every memory belongs to exactly one customer; there's no such thing as a customer-less or cross-customer memory.

A related, opt-in queue, memory suggestions …, drafts proposed changes to a workflow's configuration from the same evidence, each one reviewed and approved by hand. Applying a suggestion is always a separate, explicit step that never happens automatically.

loc-tms memory add-note --customer 1 --kind project_note --body "Always spell out acronyms on first use."
loc-tms memory distill --customer 1
loc-tms memory export --customer 1 --format jsonl > memories.jsonl

Evaluations#

A quality sandbox: build a dataset, define candidates (a workflow, or an inline configuration), run them through selectable scorers, compare with statistical honesty, and promote a winner into production. It never touches production data; pulling a dataset from a live document is a one-directional snapshot.

loc-tms eval dataset create --name "Support replies" --text $'Hello world\nGood morning\tGuten Morgen' --target de-DE
loc-tms eval run start --dataset 1 --candidate 2 --candidate 3 --budget 5.00 --yes
loc-tms eval run compare --dataset 1 --baseline 2 --candidate 3

Connectors#

Two-way integrations with external content systems, among them Airtable, Jira, Strapi, Contentful, Shopify, HubSpot, WordPress, and Akeneo: pull source content in, translate it, and push it back. Credential and configuration management stays in-process; day-to-day operation is also reachable remotely.

OAuth connectors still need one interactive browser-consent step in the web UI; everything else, including a token-authenticated connector end to end, is fully CLI-managed.

loc-tms connector create --kind airtable --name "Marketing" \
  --config base_id=appX --config table=Content --secret api_key
loc-tms connector test 1
loc-tms connector sync 1
loc-tms connector schedule 1 --every-minutes 60

Vendors#

First-class external translation or review vendors: a name, a connection, a per-word-band rate card, and the customers it's linked to. A workflow's external step dispatches its packaged text to a linked vendor, and the run parks until the vendor returns it. Vendor management is host-local; every verb runs in-process only.

Every returned segment goes through the same quality gates as a machine translation: a refusal or a locked segment withholds the text for review; a softer issue, such as a glossary miss, stores the text and flags it.

loc-tms vendor add "Acme Linguistic Services"
loc-tms vendor set-secret 1 --secret signing_secret
loc-tms vendor link-customer 1 3
loc-tms vendor rate-card set 1 --band fuzzy_high --rate 0.06

Images and key-based projects#

Images (Beta)

Localize text inside an image: upload it, review the detected text regions (each becomes an ordinary segment, so translation memory, glossary, and workflows all apply), translate, re-render, and export.

loc-tms image upload 3 ./banner.png
loc-tms image translate 12 --locale es-ES
loc-tms image export 12 --locale es-ES -o banner.es-ES.png

Key-based projects

The continuous-localization project type, where the unit of work is a string key rather than an uploaded file and the deliverable is one key/value file per locale, for syncing an app's own localization catalogue. Fully remote-capable, with its own dedicated API-key scope.

loc-tms keys import --project 7 --file ./en/common.json
loc-tms keys set --project 7 --namespace common --name error::generic --locale de-DE --text "Etwas ist schiefgelaufen."
loc-tms keys export --project 7 --locale de-DE --namespace common -o de/common.json
loc-tms keys changes --project 7 --cursor-file

Users, API keys, and access#

Accounts, per-user API keys, and project membership, in-process only aside from listing keys. The role and lifecycle logic here is the same one the admin Users page calls.

Users

API keys and membership

Account

account show, set-skin, and reset-onboarding manage a user's own preferences. Over --remote the command always acts on the token's own account; in-process it needs an explicit --user, since there's no session to infer one from.

A password passed as a flag argument is visible in shell history and process listings; omit --password to be prompted for it securely instead.

loc-tms user create --email jo@example.com --role translator --password 's3cret-passphrase'
loc-tms apikey issue --user jo@example.com --scopes docs
loc-tms member add jo@example.com 7

Engines, providers, and translation setup#

How a translation call resolves to a model: registered engine profiles, the built-in cloud provider keys, segmentation, and the context and content-type scaffolding around a prompt.

Engine profiles

Reference a profile anywhere a provider is expected as engine:<id>.

Cloud provider keys

Only a four-character fingerprint is ever printed, never the key itself.

Segmentation, context, and content types

loc-tms engine create --name "DeepL prod" --kind deepl --secret api_key=YOUR_KEY --config formality=more
loc-tms providers key set claude
loc-tms providers models --provider claude
loc-tms context set-profile --customer 1 --content-type 2 --tone "friendly,concise" --formality informal

Reports and data export#

Reports

Cost, token, volume, quality, and post-edit reporting over finished work, as a table, JSON, or CSV. Cost figures and named-person breakdowns require a manager-level key over --remote.

loc-tms report run cost --from 2026-07-01 --to 2026-07-31 --group-by provider -o july-cost.csv
loc-tms report run qa --group-by dimension
loc-tms report kinds

Data export

A self-describing dump of everything visible to the caller, or a narrower scope: one archive of per-entity data plus a manifest. Reads are confined to the caller's own visibility; a customer-bound key can only export its own customer.

loc-tms export run --scope customer --ref 7 --history full
loc-tms export status 3
loc-tms export download <run_uuid> -o dump.zip

Databricks export

Ships the install's analytical exhaust, post-edit pairs, spend, quality findings, translation-memory growth, to a customer's own Databricks lakehouse. Runs are manual, read-only against every source table, and strictly additive. Off by default; enabling it means content and translations leave the install for your own warehouse.

loc-tms databricks setup
loc-tms databricks export --stage-only
loc-tms databricks exports

Collaboration#

Queries

Threaded questions and comments on a segment, key, document, or project.

My work and reviewer findings

work list is a reviewer's cross-project worklist: paused review steps that name them, queries assigned to or answered for them, and documents needing quality attention. lqa … logs reviewer-authored quality findings on a segment, separate from the automated score: they feed reports but never change a machine score or a workflow gate.

loc-tms --actor me@example.com query open --segment 42 --subject "tone?" --body "Is this too formal?"
loc-tms --actor me@example.com work list
loc-tms lqa log --document 5 --segment 42 --dimension Accuracy --severity major --note "mistranslation"

Content routing#

Rules that route an inbound submission, by file extension and department, to a specific project and/or provider. A rule is consulted on exactly two paths: the REST API's document-upload call (with no project named) and its translate call. Uploading through the web UI, or through the in-process CLI's own doc upload, doesn't consult routing rules at all. A rule never overrides an explicit project choice.

loc-tms routing rule add --ext srt,vtt --priority 10 --project 3
loc-tms routing rule list

Admin#

Operator surfaces for capabilities outside the everyday content flow: semantic translation-memory matching, custom segmentation rules, data retention, directory identity (LDAP, OIDC), the audit trail, GDPR requests, budgets, and quality rulebooks. Every subcommand is host-only, except one read-only routing-rule lookup.

loc-tms admin semantic enable
loc-tms admin retention config --enabled on --days 90
loc-tms admin retention purge-now --yes
loc-tms admin audit export --since 2026-01-01 -o audit.ndjson
loc-tms admin audit verify

Tag integrity and quality guardrails#

Document filters replace inline formatting (bold, links, placeholders) with tokens so a translation can carry them through intact. A handful of always-on, model-free guards protect that token stream and the glossary, independent of whatever engine is doing the translating. AI-assisted tag repair is present but not enabled in this release.

Two further guards run inside the quality-review correction loop: a fixer's output is checked against the glossary before it's accepted, and a translation-memory match is protected from being silently overwritten by a later automated fix.

loc-tms tagging verify --project 3
loc-tms tagging verify --doc 12 --apply

Organizations, SCIM, and MCP#

Organizations

On a multi-tenant install, organization management (create, rename, suspend, delete) is inherently cross-tenant, so it's in-process only, and once organization scoping is turned on, it requires the operator flag described earlier on this page.

SCIM provisioning

A read-only view of SCIM 2.0 directory provisioning. Provisioning itself is identity-provider-push by design: your provider creates, updates, and deactivates accounts directly; these commands only report what it's done.

The MCP connection helper

Localization OS also runs an MCP server, a sibling surface built for AI agents rather than a shell. This command prints the connection snippet for a running server, matching what the in-app help page would show a browser user.

loc-tms --operator org create --name 'Acme Inc.'
loc-tms scim status
loc-tms mcp connect --base-url https://tms.example.com