Lexique
Docs

Lexique CLI reference

Install and authenticate the Lexique CLI, configure repositories, pull and push translation files safely, and automate checks in CI.

Install the CLI

The official CLI is distributed as @lexique/cli and requires Node.js 20.12 or newer. A global installation makes the lexique command available in every repository.

npm install --global @lexique/cli
lexique --version
lexique --help

Sign in for local development

Run lexique login for browser-based account authentication. The CLI uses PKCE, stores credentials outside the repository, rotates refresh tokens, and uses macOS Keychain for the refresh token when available.

Use whoami to inspect the active account and logout to revoke the saved CLI session. For local or self-hosted deployments, pass an explicit HTTPS base URL; plain HTTP is accepted only for loopback development URLs.

lexique login
lexique whoami
lexique logout

Choose and configure a project

Project IDs are numeric. List accessible projects, save a project selection, then configure the translation adapter and paths used by pull and push. The configuration is stored in lexique.config.json without authentication secrets.

Supported sync adapters are flat JSON, localized JSON, Symfony YAML, and i18next JSON. XLIFF metadata is detected but XLIFF sync is rejected until server import and export support is available. The older setup command remains a deprecated alias for config.

lexique projects
lexique projects use 123
lexique config --project-id 123
lexique config print

Pull translations

A configured lexique pull writes the repository files defined in lexique.config.json. A full configured pull also records .lexique/state.json as the trusted local sync baseline.

Filter with repeatable --locale, --key, or --tag options, or use --match and --only-completed. Filtered pulls deliberately do not advance the baseline because they represent only part of the remote project.

lexique pull
lexique pull --all
lexique pull --locale en --locale fr --match '^checkout\.'

Push local changes safely

By default, configured push uploads only keys changed since .lexique/state.json. If no trusted baseline exists, it fails safely and asks for a full pull or an explicit all-files preview.

The default merge behavior keeps existing remote values and creates missing keys. Use --overwrite only when replacing existing values is intentional. Dry runs never contact Lexique. Pushes advance the baseline only when the server confirms that nothing was skipped.

lexique push --all --dry-run
lexique push
lexique push --since main --dry-run
lexique push --skip-invalid --batch-max-bytes 4mb

Inspect and validate local changes

Status prints the effective project, authentication source, sync configuration, and baseline state. Diff shows the same changed-input view as a push dry run without uploading.

The staged check is offline and read-only. It reads exactly what is staged in Git, requires a non-empty default-locale value for new keys, warns about missing secondary locales, and never changes Lexique or the local sync baseline.

lexique status
lexique diff
lexique check --staged

Use machine tokens in CI

CI and agents should use account-owned machine tokens restricted to explicit project IDs and the smallest required scopes. Tokens are shown once and belong in LEXIQUE_TOKEN, never lexique.config.json.

When a token is supplied, repository-controlled baseUrl values are ignored. Self-hosted CI must set LEXIQUE_BASE_URL explicitly as well as LEXIQUE_TOKEN.

lexique tokens create --name CI --project 123 --scope projects:read --scope translations:read
export LEXIQUE_TOKEN="lxq_mch_<selector>_<secret>"
lexique pull

Configuration and security boundaries

  • Flags override environment variables, which override repository configuration and saved account settings.
  • Configured paths are anchored to the directory containing lexique.config.json and cannot escape it or traverse symbolic links.
  • Catalog files are limited to 10 MiB; API responses are limited to 20 MiB and time out after 30 seconds.
  • Legacy project tokens remain readable for migration, emit security warnings, and are removed when config rewrites the repository file.
  • .lexique/state.json is per working copy and should be ignored by Git.