CLI reference

Troubleshooting

Every langctl error explains what went wrong and usually how to fix it. Start here when something doesn’t behave as expected.

First steps

langctl --version          # 0.3.0 or newer?
langctl config             # which key, API URL and langctl.json are in effect (no network)
langctl whoami             # does the key work, which org and scopes, API latency
langctl pull --verbose     # log every HTTP request with status and timing

The exit code tells you the category: 3 auth, 4 not found, 5 network, 6 plan limit, 7 out-of-date files.

Installation

langctl: command not found — the global npm bin directory isn’t on your PATH. Check npm prefix -g, or use npx langctl@latest instead.

Errors about unsupported syntax or engines — langctl needs Node.js 20 or newer. Check node --version and upgrade (for example with nvm: nvm install 22).

Authentication (exit code 3)

Not authenticated — run langctl init or langctl auth, or set LANGCTL_API_KEY.

Your API key is invalid or has been revoked — create a new key at API Keys. If you just rotated keys, check that the CI secret was updated too.

That does not look like a Langctl API key — a key is lc_ followed by 64 hex characters. Surrounding spaces and quotes are stripped automatically; anything else usually means the key was truncated when copying.

API key missing required scope: … — the key lacks a permission. CI keys typically need translations:read (pull) or translations:write (push); team commands need org:admin. See scopes.

The wrong organization or key is used — langctl config shows the source. LANGCTL_API_KEY and --api-key take precedence over the stored key, and langctl logout warns if the env var is still set.

Projects and keys (exit code 4)

Project “x” not found — the error lists the available project slugs. Slugs never change when a project is renamed.

No project given — pass the slug, or add "project" to langctl.json (langctl init).

Key “x” not found — key names are exact and case-sensitive. Search with langctl keys list <project> --search <text>.

Pull and push

A key is missing from my files — it’s probably still a draft: only published keys are pulled. Check with langctl keys get <project> <key>, then langctl keys publish <project> <key> (or pull --include-drafts to preview).

One language of a published key is missing — if that translation was made with AI, it’s left out until someone approves or edits it on the dashboard’s Translations page (filter Needs review).

Language “xx” not in project (exit 2) — add it with langctl projects add-language <project> xx, or fix languages in langctl.json.

Output has no {lang} placeholder (exit 2) — several languages can’t share one file. Use a template such as locales/{lang}.json, or pull a single language with --languages.

Keys collide when converted to Android/ARB names — e.g. home.title and home_title both become home_title. Rename one key, or use a JSON format.

These keys can’t be represented as nested JSON — a key such as home is a string and also the parent of home.title. Rename one, or use --format json (flat).

push reports “unchanged” although my file differs — existing translations are only replaced with --overwrite. Without it, push adds new keys and fills in missing languages only. Preview with --dry-run.

Placeholders became {{1}} — pushing Android or iOS files can’t recover placeholder names. Push your JSON/ARB source instead, or fix the keys afterwards.

CI/CD

pull --check fails with exit 7 — translations changed since the files were committed. Run langctl pull locally and commit the result. Formatting-only differences don’t trigger this.

A destructive command fails with “Refusing to … without confirmation” (exit 2) — non-interactive runs never prompt; add --yes if the deletion is intended.

The job hangs — langctl doesn’t prompt or animate when CI is set or output isn’t a terminal, and every request times out after 30 seconds (--timeout). If a job still stalls, run with --verbose to see the last request.

Network (exit code 5)

Could not connect / Cannot resolve api.langctl.com — check connectivity and DNS. If you set LANGCTL_API_URL, make sure it ends in /api/v1.

TLS errors behind a corporate proxy — point NODE_EXTRA_CA_CERTS at your proxy’s CA bundle.

Request timed out — langctl already retries safe requests with backoff. On slow links raise the limit: --timeout 60 or LANGCTL_TIMEOUT=60.

Plan limits (exit code 6)

Errors like Project limit reached mean your plan’s quota is used up. langctl org plan shows usage and limits.

Still stuck?