CLI reference

Configuration

A committed langctl.json describes how your repository syncs; environment variables and flags handle credentials and per-run settings.

langctl.json

langctl init creates this file. Commit it — then langctl pull and langctl push work with no arguments, on every machine and in CI.

langctl.json

{
"project": "web-app",
"format": "json",
"output": "src/locales/{lang}.json"
}

Field	Description
`project`	Project slug (see `langctl projects list`).
`format`	`json` (default), `nested-json`, `android`, `ios` or `arb`. See formats.
`output`	Path template for translation files, relative to `langctl.json`.
`languages`	Languages to pull, e.g. `["en", "es"]` (default: all project languages).
`sourceLanguage`	Language `push` uploads by default (default: the project’s default language).
`includeDrafts`	Also pull unpublished keys (default `false`).
`module`	Only pull/push keys in this module.

Path template variables:

Variable	Example for `pt-BR`	Typical use
`{lang}`	`pt-BR`	`locales/{lang}.json`, `{lang}.lproj/Localizable.strings`
`{lang_}`	`pt_BR`	Flutter: `lib/l10n/app_{lang_}.arb`
`{android}`	`values-pt-rBR` (default language: `values`)	`res/{android}/strings.xml`

langctl looks for langctl.json in the current directory and then its parents, so commands work from any subfolder. Command-line flags override the file. Unknown fields are reported as errors, so typos don’t fail silently.

Environment variables

Variable	Purpose
`LANGCTL_API_KEY`	API key — the standard way to authenticate in CI. Overrides the stored key.
`LANGCTL_API_URL`	API base URL (default `https://api.langctl.com/api/v1`).
`LANGCTL_TIMEOUT`	Request timeout in seconds (default `30`).
`LANGCTL_CONFIG_DIR`	Where the user config is stored (default `~/.langctl`).
`CI`	When set, langctl never prompts and shows no spinners. Set automatically by most CI providers.
`NO_COLOR`	Disable colored output.
`NODE_EXTRA_CA_CERTS`	Trust a corporate proxy’s certificate authority.

Global flags

These work with every command, before or after it (langctl --json pull or langctl pull --json):

Flag	Description
`--json`	Machine-readable JSON on stdout (errors too).
`-q, --quiet`	Only print results and errors.
`--verbose`	Log each HTTP request (method, path, status, time) to stderr.
`-y, --yes`	Skip confirmation prompts. Required for destructive commands when not interactive.
`--api-key <key>`	API key for this run (prefer `LANGCTL_API_KEY`).
`--api-url <url>`	API base URL for this run.
`--timeout <seconds>`	Request timeout for this run.
`--no-color`	Disable colors.

Output

Results go to stdout; progress, warnings and errors go to stderr. With --json, stdout contains only JSON, so it is safe to pipe:

terminal

langctl projects list --json | jq -r '.[].slug'
langctl push --dry-run --json | jq '.results[].created'

Failures with --json print an error object to stdout as well:

terminal

$ langctl pull missing-project --json
{
"error": {
  "message": "Project \"missing-project\" not found.",
  "exitCode": 4,
  "hint": "Available projects: web-app, mobile-app",
  "status": null
}
}

Exit codes

Code	Meaning
`0`	Success
`1`	Error — including a cancelled confirmation or `pull --require-complete` finding missing translations
`2`	Invalid usage — unknown flag, language or format; destructive command refused without `--yes`
`3`	Not authenticated, invalid or revoked key, or missing scope
`4`	Project, key, member or file not found
`5`	Network error, timeout, or the API is unavailable
`6`	Plan limit reached
`7`	`pull --check`: translation files are out of date

Reliability

Requests time out after 30 seconds (--timeout).
Safe-to-repeat requests (reads, imports, publishes) are retried up to 3 times with backoff on network errors, 429 and 5xx, honoring Retry-After.
Large uploads are split into chunks automatically.
Files are only rewritten when their translations change, and output is sorted without timestamps — a pull never creates a noisy diff.

Stored user config

~/.langctl/config.json holds the API key saved by langctl auth / init. It is written with owner-only permissions (600). langctl config prints the effective configuration and the source of each value:

terminal

$ langctl config
api url       https://api.langctl.com/api/v1
api key       lc_3f1a…9c2e  (LANGCTL_API_KEY)
user config   /home/ci/.langctl/config.json
project file  /work/app/langctl.json
project: "web-app"
format: "json"
output: "src/locales/{lang}.json"

Tip

langctl config makes no network calls — it’s a quick way to debug “which key and project is this pipeline using?”.