Breeze CLI scripting and agents

Breeze CLI is built to run inside scripts and AI agent harnesses such as Codex, Claude Code, and Cursor. Machine callers depend on JSON output and exit codes, never on human-readable text.

Agent mode

--agent is a one-flag bundle equivalent to --output json --non-interactive --quiet with audio autoplay disabled. Successful JSON results go to stdout; error envelopes go to stderr. Read the JSON payload and exit code. Do not parse status text.

breeze voice list --agent
breeze tts "Hello from Breeze" --voice <voice_id> -o hello.wav --agent

Non-interactive rules to build against:

breeze tts requires --voice or --random-voice; there is no interactive voice pick.
Streaming breeze tts JSON reports response_header_ms, ttfa_ms, and first_audio_byte_ms for client-observed first-audio latency measurement without local playback.
Destructive commands (voice delete, history delete, cache clean) require --yes; without it they fail with a usage error instead of prompting.
Automatic update checks are skipped in agent, JSON, quiet, non-interactive, and CI runs, so machine output stays clean.

Error envelope

In JSON mode, failures write a single envelope to stderr:

{
  "error": {
    "code": "quota",
    "message": "Not enough credits to complete this request.",
    "suggestion": "Top up credits, then retry.",
    "exit_code": 4,
    "retryable": false
  }
}

code matches the exit code table below; detail and suggestion appear when available; retryable marks errors worth retrying, such as transient network failures.

Exit codes

Exit codes are stable across releases. Branch on them to choose a recovery action: retry on network, top up on quota, or re-authenticate on auth.

Code	Value	Meaning
`success`	0	Command succeeded.
`general`	1	Unexpected or uncategorized failure.
`usage`	2	Invalid arguments or invocation.
`auth`	3	Missing or failed authentication.
`quota`	4	Not enough credits or quota.
`timeout`	5	Request timed out.
`network`	6	Network or upstream connection failure, including upstream 5xx.
`not_found`	7	Requested resource does not exist.
`policy_blocked`	10	Blocked by policy.

Long-running commands

breeze jobs wait streams one JSON progress line per poll to stderr and writes the final job result to stdout, so a caller can show progress and still parse a single result:

breeze tts --async "Long narration..." --voice <voice_id> --agent
breeze jobs wait <generation_job_id> --timeout 5m -o narration.mp3 --agent

Capabilities discovery

breeze capabilities prints a single-shot manifest of legal flag values, default endpoints, enum values, and the exit code mapping, so an agent can discover the command surface without trial and error. Pass --agent or --output json to get JSON.

breeze capabilities --agent

CI and headless credentials

Non-browser environments provide credentials explicitly. Prefer stdin when writing a key into a local profile; --api-key and BREEZE_API_KEY work per invocation.

printf '%s' "$BREEZE_API_KEY" | breeze config set api-key --stdin
breeze tts "Hello from Breeze" --voice <voice_id> -o hello.wav --agent

See Login and auth for the full resolution order.

Install agent skills

breeze skills install writes the Breeze agent skill bundle into a harness’s skills directory. Choose the target harness with --target: codex, claude, cursor, or all. Skills commands do not use your API key and do not call Breeze generation APIs. Use breeze skills check to report the installed skill state.

breeze skills install --target claude --yes
breeze skills install --target codex --yes
breeze skills check --target codex --agent

To install Breeze CLI and skills together from an agent, use the installer opt-in:

curl -fsSL https://breezeblue.ai/cli/install.sh | sh -s -- --with-skills codex

To keep skills aligned with the CLI release, either update them directly or ask breeze update to refresh them after a CLI update:

breeze skills update --target codex --yes
breeze update --yes --with-skills --skills-target codex

Get started

Workflows

Automation

Setup and reference

Breeze CLI scripting and agents

Agent mode

Error envelope

Exit codes

Long-running commands

Capabilities discovery

CI and headless credentials

Install agent skills

​Agent mode

​Error envelope

​Exit codes

​Long-running commands

​Capabilities discovery

​CI and headless credentials

​Install agent skills

Agent mode

Error envelope

Exit codes

Long-running commands

Capabilities discovery

CI and headless credentials

Install agent skills