Configuration

Flags override environment variables, which override a config file.

Common options

Most commands accept these shared options:

Flag	Env	Default	Notes
`-t, --token <token>`	`LB_TOKEN`	stored login	Bearer token (`lb_pat_…` PAT or a project API token). Falls back to the token saved by `lb login`.
`-u, --url <url>`	`LB_URL`	`http://localhost:3000`	Server base URL.
`-p, --project <slug>`	`LB_PROJECT`	—	Project slug. Required except for `login`/`logout`/`whoami`.
`-l, --locale <code>`	—	project source locale	Locale to act on. Keys are identical across locales, so the source locale is enough for type generation.
`-n, --namespace <name>`	—	all	Repeatable; restrict to specific namespaces.
`--include-drafts`	—	off	Include unpublished values.
`--json-dir <dir>`	—	`.language-bridge/locales`	Raw JSON location (pull/generate).
`-H, --header <name:value>`	`LB_HEADERS`	—	Extra HTTP header on every request (auth proxies). Repeatable.
`--verbose`	`LB_DEBUG=1` / `DEBUG=lb`	off	Log requests and responses.

Config file

Config is discovered by cosmiconfig — language-bridge.json, .language-bridgerc[.json|.yaml], language-bridge.config.js, or a languageBridge key in package.json. Scaffold one with lb init:

{ "url": "https://lb.example.com", "project": "my-app", "out": "src/@types/resources.d.ts" }

Header commands

A headers value in the config can also be a command — its stdout becomes the header on every run, so expiring tokens (auth proxies) resolve themselves and nobody exports a fresh JWT by hand:

{
  "headers": {
    "cf-access-token": { "command": "cloudflared access token -app=https://lb.example.com" }
  }
}

The command runs once per invocation (chunked pushes and multi-project runs reuse the value). Because the config file is committed to the repo, an unknown command asks for your approval the first time and is then remembered — per command and server URL, so a cloned repo can never silently send an already-trusted helper's output to a different server — in ~/.config/language-bridge/trusted.json. Set LB_TRUST_HEADER_COMMANDS=1 to skip the prompt in CI.

Multiple projects

A monorepo can consume several projects from one config via a projects list. Each entry names a project slug and may override locale, namespaces, out, jsonDir, params, session; anything omitted inherits the top-level defaults, then a per-slug default (src/@types/<slug>.d.ts, .language-bridge/<slug>) so outputs never collide.

{
  "url": "https://lb.example.com",
  "projects": [
    { "project": "main-app", "out": "src/@types/main.d.ts" },
    { "project": "marketing", "namespaces": ["landing"] }
  ]
}

Commands (pull, generate, sync, push) run for every listed project; --project <slug> narrows to one. With several projects resolved, the single-project flags (--out, --json-dir, --locale, --namespace) are rejected as ambiguous — set them per entry instead.

Where the token is stored

lb login stores the token per server URL in

$XDG_CONFIG_HOME/language-bridge/credentials.json (Linux/macOS, default ~/.config)
%APPDATA%\language-bridge\credentials.json (Windows)

with 0600 permissions — never in the project tree, so it can't be committed.