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 api-key current --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, and breeze studio delete / bulk-delete) 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. Errors returned by the Breeze API also carry http_status, api_code, and, when the API provides it, meta, such as the latest edit token of a Studio conflict.

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

For API inputs, use OpenAPI to inspect field types, enum values, and constraints. Discover account-available models with List models: use the returned model_id and languages[].language_id values together. Retrieve language, gender, age, tone, and language-dependent accent codes from Metadata options. Category codes are published in the List voices parameter enum. Use List voices to obtain a saved voice_id; a generated preview must be saved before its voice ID can be used for synthesis.

breeze models list --agent
breeze voice metadata-options --agent
breeze voice list --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

The installer and breeze update include the exact Skills shipped with the CLI version. The default auto target detects Codex (CODEX_HOME or ~/.codex), Claude Code (~/.claude), and Cursor (~/.cursor); it uses Codex when no agent home exists. Previously managed targets also stay synchronized.

curl -fsSL https://breezeblue.ai/cli/install.sh | sh
breeze update --yes
breeze skills check --agent

To add an agent target, choose auto, codex, claude, cursor, or all:

breeze skills install --target claude --yes
breeze skills update --target all --yes

skills install and skills update synchronize the local CLI package; they do not fetch a different release. skills check validates the version and file contents without changing installed Skills. These commands work offline, do not use your API key, and do not call generation APIs. The installer accepts --skills-target on macOS/Linux and -SkillsTarget on Windows. breeze update accepts --skills-target. Explicit selection also updates other Breeze-managed targets. Breeze-owned directories are replaced together; keep custom Skills in separate directories. Restart or reload the agent session after updating files that it has already loaded.

Write prompts in your agent harness

Use the LLM already running in your harness to draft voice descriptions and performance instructions. The BreezeBlue CLI executes the reviewed request; it does not require an additional LLM provider for drafting.

Give your agent the spoken text, target language, speaker role, listener, and intended delivery.
For Voice Design, draft a reusable identity in voice_description and separate preview text. For TTS, preserve the spoken text and draft passage-specific instructions in the same language.
Review the fields before generation. Pass a voice description through breeze voice design --description; pass performance direction through breeze tts --instructions. Both commands accept --guidance-scale, but Voice Design uses a top-level API field and TTS uses voice_settings.guidance_scale.
Run with --agent when generation is authorized. Generating audio or previews consumes credits; local prompt drafting does not. Audition the output before accepting the delivery.

The breeze-audio skill includes a local prompt-writing reference; breeze-audio-studio applies it to multi-segment scripts. Skills are versioned with the CLI package, so skills update only restores the instructions bundled with your installed release.

Voice instruction prompting

Direct the situation, intent, and delivery of each passage.

Voice Design prompting

Describe a reusable voice identity and write a representative preview script.

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

Write prompts in your agent harness

Voice instruction prompting

Voice Design prompting

​Agent mode

​Error envelope

​Exit codes

​Long-running commands

​Capabilities discovery

​CI and headless credentials

​Install agent skills

​Write prompts in your agent harness

Voice instruction prompting

Voice Design prompting

Agent mode

Error envelope

Exit codes

Long-running commands

Capabilities discovery

CI and headless credentials

Install agent skills

Write prompts in your agent harness