CLI reference

Authentication

langctl authenticates with an organization API key. Store it once on your machine, or provide it as an environment variable in CI.

Create an API key

1. Open app.langctl.com → API Keys and click New API Key.
2. Choose the permissions (scopes) the key needs — see below.
3. Copy the key. It starts with lc_ and is shown only once.

Scopes

Every key can read basic organization and project details. Give CI keys only what the job needs — translations:read is enough for langctl pull --check. Deleting the organization or transferring ownership is never possible with an API key.

On your machine

The easiest way is langctl init, which asks for the key when needed. To store a key directly:

langctl auth

auth prompts for the key with hidden input, verifies it against the API, and saves it to ~/.langctl/config.json (readable only by you). To pipe it in instead — for example from a password manager:

echo "$LANGCTL_API_KEY" | langctl auth --stdin

Check which organization and key you’re using:

$ langctl whoami
Acme Inc (acme, pro plan)
key      lc_3f1a…9c2e  from /Users/you/.langctl/config.json
scopes   translations:read, translations:write, projects:read
api      https://api.langctl.com/api/v1  142ms

Remove the stored key:

langctl logout

In CI/CD

Don’t run auth in CI. Store the key as a secret and expose it as LANGCTL_API_KEY — no config file or login step is needed:

- run: npx langctl@0 pull --check
env:
  LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}

Verify a key in a pipeline with langctl whoami --json.

Where credentials come from

langctl uses the first one it finds:

1. --api-key <key> flag
2. LANGCTL_API_KEY environment variable
3. The stored key in ~/.langctl/config.json (or $LANGCTL_CONFIG_DIR/config.json)

langctl config shows the effective key (masked) and where it came from, without making any network call.

Errors

See Configuration for every exit code.