airstrings-cli: Instructions file for Codex

AirStrings CLI — agent guide

airstrings manages localized strings for the AirStrings platform. This file is the contract for driving it from an AI agent or script. Read it once; every command below is stable and machine-friendly.

Golden rules

• Add --json to any command for structured stdout. Human text goes to stdout, errors and progress go to stderr.

• Branch on the exit code, not on message text:

  code	meaning	retry?
  0	ok	—
  1	generic error	no
  2	usage / bad input	no (fix the command)
  3	auth (bad/expired key)	no (fix credentials)
  4	not found	no
  5	network	yes (backoff)
  6	rate limited	yes (backoff)

• Any command + --help/-h prints its help text and exits 0 — nothing is executed, no side effects. Safe to probe usage this way.

• Unknown flags exit 2 (usage) — the command does not run. Fix the invocation.

• Set NO_COLOR=1 (or just pipe — non-TTY auto-disables color) for clean output.

Auth — two ways

Workspace (interactive / committed repo): airstrings init <api-key> writes .airstrings/config.json (mode 0600) at the repo root. Found by walking up from the cwd, like .git. Survives restarts.

Environment variables (headless / CI / ephemeral agent): set AIRSTRINGS_API_KEY and skip init. It overrides any workspace credential.

AIRSTRINGS_API_KEY      scoped key; project + default env resolved from it
AIRSTRINGS_PROJECT_ID   optional — skip project lookup (one fewer API call)
AIRSTRINGS_ENV_ID       optional — skip environment lookup
AIRSTRINGS_BASE_URL     optional — default https://api.airstrings.com

A scoped key maps to exactly one project + one environment. With just the key, the CLI resolves both automatically; supply the IDs to make calls fully stateless (zero discovery round-trips).

Confirm what you're pointed at any time: airstrings status --json → {source, project_id, env_id, base_url, protection, environments[...], mode, workspace_dir}. source is "workspace" or "env". protection is "protected" (production sealed — changes reach it via promote), "yolo" (direct publish to production enabled), or "unknown"; it is derived from one best-effort API call and degrades to "unknown" rather than failing, so status never errors on it.