polycli run

The main translation engine. Reads your source file, calculates the delta, translates, and writes output files.

Usage

bash
# Pass the key directly
npx @polycli/cli run --key <YOUR_API_KEY>

# Or set the env var and omit the flag
POLYCLI_API_KEY=<YOUR_API_KEY> npx @polycli/cli run

Flags and environment variables

Flag / Env varRequiredDescription
--key <key>One of --key or POLYCLI_API_KEYYour PolyCLI API key (starts with bt_live_). Takes precedence over the env var.
POLYCLI_API_KEYOne of --key or POLYCLI_API_KEYYour PolyCLI API key set as an environment variable. Useful for CI/CD pipelines and .env files.
POLYCLI_API_URLNoOverride the backend URL. Defaults to https://app.polycli.dev. Set to http://localhost:3000 during local development.

Execution flow

  1. Load and validate buildtranslator.json
  2. Read the source JSON file (e.g. locales/en.json)
  3. Compare against .translator-lock.json to compute the JSON delta
  4. If no JSON delta: skip to Markdown phase
  5. For each target language: POST delta to /api/translate with type: "json"
  6. Merge translated keys into existing target file, write to disk
  7. Update .translator-lock.json
  8. If markdownPath is set: scan source language Markdown folder
  9. For each file × language: compute block hash delta against .polycli-md-cache.json
  10. POST changed blocks to /api/translate with type: "markdown"
  11. Reconstruct full translated Markdown file, write to target language directory
  12. Update .polycli-md-cache.json

Exit codes and errors

Exit code / ErrorCause
0Success — all translations completed or nothing to translate.
1 + "buildtranslator.json not found"npx @polycli/cli init has not been run in this directory.
1 + "API key is required"Neither --key nor POLYCLI_API_KEY was provided.
1 + "Invalid API key"The key passed to --key (or POLYCLI_API_KEY) does not match any user in the database.
1 + "Insufficient credits"Your credit balance is lower than the words required. Purchase more from your dashboard.
1 + "Failed translating to <lang>"Network error during translation. The lockfile is NOT updated — re-running is safe.
Commit .translator-lock.json and .polycli-md-cache.json to version control. These files are what allows PolyCLI to calculate the delta. Without them, every run re-translates everything.