Agents & MCP

The CLI is built to be driven by scripts and AI agents: every command has structured output, stable exit codes, and a headless auth path. This page is the contract.

Prompt, don't type

Once a workspace exists (airstrings init <api-key>, once, at the repo root), you don't run these commands yourself. You describe the change and let your agent drive the CLI. A real Claude Code session, given only this prompt:

We're adding a free-trial CTA button to the pricing section. Add the string pricing.cta_trial with en="Start your free trial" plus translations for all our locales, using the airstrings CLI. Don't publish yet.

The agent first read the project's existing strings to match each locale's register (informal in Italian, German, and Spanish; formal vous in French), then set all five locales in one command:

airstrings strings set pricing.cta_trial --format text --push \
  en="Start your free trial" it="Inizia la tua prova gratuita" \
  de="Starte deine kostenlose Testphase" es="Empieza tu prueba gratuita" \
  fr="Commencez votre essai gratuit"

✓ Set pricing.cta_trial — 5 locale(s) [text] (pushed)

and verified its own work before reporting back:

airstrings strings get pricing.cta_trial

Key:    pricing.cta_trial
Format: text
Values:
  de: Starte deine kostenlose Testphase
  en: Start your free trial
  es: Empieza tu prueba gratuita
  fr: Commencez votre essai gratuit
  it: Inizia la tua prova gratuita

The contract on the rest of this page is what makes sessions like this converge instead of flail. In the same session, the agent's first set attempt omitted --format: the CLI exited 2 with --format is required — must be 'text' or 'icu', and the agent fixed the command on the next try. A deterministic error costs one correction, not a guessing loop.

To make this the default way strings get edited in your repo, add one line to your project's CLAUDE.md or AGENTS.md:

All user-visible copy lives in AirStrings — manage it with
`airstrings strings set <key> --format text|icu --push`. Never hardcode strings.

After that, "using the airstrings CLI" in the prompt becomes optional: the workspace and the agent file carry the context.

Structured output

Add --json to any command for machine-readable stdout. Human-readable text goes to stdout; errors and progress go to stderr.

airstrings strings ls --json
airstrings project --json | jq '.name'

Exit codes

Branch on the exit code, not on message text:

Only 5 and 6 are retryable; everything else is deterministic and will fail the same way again.

Env-var auth (headless / CI)

For ephemeral agents and CI, skip init entirely and authenticate with environment variables. They override any workspace credentials.

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

Confirm what you are pointed at any time with airstrings status --json, which returns source ("workspace" or "env"), project_id, env_id, base_url, and the available environments.

Env-var auth is CLI-only. The MCP tools require an initialized workspace. Run airstrings init in the project before using the MCP server. AIRSTRINGS_API_KEY does not apply to MCP.

Paging large lists

strings ls --json returns { "data": [...], "pagination": { "has_more": bool, "next_cursor": string } }. Loop by passing next_cursor back via --cursor until has_more is false.

airstrings strings ls --limit 50 --json
airstrings strings ls --cursor <next_cursor> --json
airstrings strings ls --key-prefix home. --json

Prefer --limit/--cursor or a --key-prefix filter over an unbounded ls so results stay small.

Typical agent flow

export AIRSTRINGS_API_KEY=ask_live_xxx
airstrings status --json
airstrings strings set welcome.title en="Welcome" --format text --push
airstrings strings ls --key-prefix welcome. --json
airstrings publish en --json

MCP server

airstrings-mcp is a separate stdio binary that exposes workspace operations as MCP tools, for AI clients without shell access (e.g. Claude Desktop). It ships with the CLI install.

airstrings mcp install
airstrings mcp install --claude-desktop

mcp install targets Claude Code by default; pass --claude-desktop for Claude Desktop. Restart Claude and the tools are available.

The tools mirror the workspace commands (init, set/rm, ls, push, pull, publish) and your AI picks them automatically. A separate set of variant tools — airstrings_variant_set, airstrings_variant_status, airstrings_variant_start, airstrings_variant_stop, and airstrings_variant_promote — exposes the variants workflow (set variant text, inspect status, start/stop, promote a winner) to agents without shell access. Prompt in product terms:

Translate the welcome module into all our locales.

Add a string checkout.cta with en="Place order", translated for every locale, and publish it.

Prefer the CLI when you have a shell

The MCP server exposes a subset of the CLI. If your agent has shell access, drive airstrings directly. It is more composable and supports paging, --json, and the exit codes above.