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)
  7	environment protected (production)	no — publish to staging; a human promotes
  8	plan limit reached	no — a human upgrades
  9	login pending	yes — after the user approves the printed URL

  Exit 3 also covers a read key used for a write.

• With --json, errors go to stderr as one JSON object: {"error":{"message":"…","next_step":"…","exit_code":7}}. next_step is the single action that unblocks you (a command or a dashboard link). MCP tool errors carry the same message and Next step: text.

• 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 — three ways

Login (one command after signup): airstrings init --json in the repo. With no key it logs in through the browser, stores an org key (as_org_…) in ~/.config/airstrings/credentials.json (0600), creates a project named after the folder and writes .airstrings/config.json. It never reuses a project by name: a name collision exits 2 and names the existing project (use --project <id> or --name <other>).