> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breezeblue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Breeze CLI scripting and agents

> Run Breeze CLI from scripts and AI agents: --agent JSON output, exit codes, capabilities discovery, and skill install.

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.

```bash theme={null}
breeze voice list --agent
breeze tts "Hello from Breeze" -o hello.wav --agent
```

## 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.                                              |

## 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.

```bash theme={null}
breeze capabilities --agent
```

## 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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
breeze skills update --target codex --yes
breeze update --yes --with-skills --skills-target codex
```