lexa-cli

Command-line client for Lexa, a translation management system. Sync translation files between your repository and Lexa, inspect progress, and script localization workflows in CI.

Zero runtime dependencies. Requires Node 18+ (uses native fetch).

Install

npm install -g lexa-cli

Or run without installing:

npx lexa-cli status --project my-app

Authenticate

Create an API key in Lexa under Settings → API Keys, then:

lexa login --url https://lexa.example.com --key sk-...

The key is verified before being saved, so a typo fails immediately rather than on your next command. Credentials are written to ~/.lexa/credentials.json with 0600 permissions.

In CI, skip login and set environment variables instead — they take precedence over the stored file, so nothing is written to disk:

export LEXA_URL=https://lexa.example.com
export LEXA_API_KEY=sk-...

Key scopes: pull, status, projects, and languages work with a read-only key. push requires a read/write key.

Set up a repository

lexa init --project my-app

This writes a .lexarc recording the project, its languages, and an output directory. It contains no secrets and is safe to commit — teammates then run lexa pull with no flags.

{
  "project": "my-app",
  "languages": ["fr", "de"],
  "out": "./locales"
}

Sync translations

Pull approved translations into local files:

lexa pull                          # every language in .lexarc
lexa pull --lang fr                # one language
lexa pull --nested                 # nested JSON for i18next/ngx-translate
lexa pull --all-states             # include unapproved drafts

By default pull writes only approved translations, matching what Lexa's own export produces — so the files you commit are publishable. Keys are sorted, giving stable diffs across pulls.

Push local edits back:

lexa push --lang fr --dry-run      # preview what would change
lexa push --lang fr

push only updates values for keys that already exist in the project, and only those whose value actually differs. Keys not present in Lexa are reported and skipped rather than created — importing new terms is a deliberate operation that belongs in the web UI or your repo sync, not a side effect of pushing a file.

Inspect

lexa projects                      # projects visible to this key
lexa languages --project my-app    # configured languages and coverage
lexa status --project my-app       # approval progress per language
lexa whoami                        # check stored credentials still work

$ lexa status --project my-app
My App (my-app)
  fr        84% approved  (412/490 approved, 470 translated)
  de       100% approved  (490/490 approved, 490 translated)

Use in CI

Every command exits non-zero on failure, so failures stop a pipeline. To fail a build when translations drift from what's committed:

lexa pull --lang fr --out ./locales
git diff --exit-code ./locales

Reference

| Command | Purpose | | --- | --- | | login --url <url> --key <key> | Verify and store credentials | | whoami | Check stored credentials | | init --project <ref> [--out <dir>] | Write .lexarc | | projects | List accessible projects | | languages [--project <ref>] | List languages with coverage | | status [--project <ref>] | Approval progress per language | | pull [--lang <code>] [--out <dir>] [--nested] [--all-states] | Write translations to files | | push --lang <code> [--file <path>] [--dry-run] | Upload translation values |

Projects can be referenced by slug, name, or UUID. --project overrides .lexarc.

| Environment variable | Purpose | | --- | --- | | LEXA_URL | API base URL (overrides stored config) | | LEXA_API_KEY | API key (overrides stored config) | | LEXA_CONFIG_DIR | Override ~/.lexa |