# Brizz CLI

Install and authenticate the brizz CLI — read sessions, issues, intents, and metrics from the terminal, and hand structured investigations to an AI coding agent.

The **Brizz CLI** (`brizz`) reads your Brizz analytics from the terminal. It's built for AI coding agents — Claude Code, Cursor, and the like — to answer questions about your agent's behavior through a stable interface instead of scraping the dashboard, and it's equally usable directly.

## Install

:::tabs
:::tab[macOS (Homebrew)]
```bash
brew install brizzai/tap/brizz-cli
```
:::tab[macOS & Linux]
```bash
curl -fsSL https://raw.githubusercontent.com/brizzai/brizz-cli/master/install.sh | sh
```
:::tab[Windows]
```text
Download the Windows .zip from github.com/brizzai/brizz-cli/releases,
extract it, and add it to your PATH.
```
:::

`brizz upgrade` updates it in place.

## Authenticate

```bash
brizz auth login          # opens your browser (OAuth)
brizz auth whoami         # who you are, and the active tenant
```

OAuth covers every tenant your account can access. For CI and agents, use a **Platform API key** from **Settings → User Settings → Platform API Keys** — not a telemetry key, which returns `401` here:

```bash
brizz auth login --api-key "$BRIZZ_API_KEY"
```

`BRIZZ_API_KEY` in the environment works on its own. A Platform API key is pinned to one tenant and carries the role chosen when it was created. See the [API overview](/docs/api/overview.md) for the credential classes.

## Pick a tenant and app

```bash
brizz tenant list
brizz tenant switch acme        # persist a default
brizz app switch checkout-agent
```

Tenant resolution is `--tenant`, then `BRIZZ_TENANT`, then the persisted default. One accessible tenant is picked automatically; with several and no choice made, the command stops with an error rather than guessing.

## Read your data

```bash
brizz sessions list
brizz sessions view <id>               # one session's detail
brizz sessions conversation <id>       # turns and tool calls
brizz sessions browse                  # interactive picker

brizz issues list
brizz issues evidence <issue-id>       # the occurrences behind an issue
brizz issues investigate <id>          # structured investigation bundle

brizz intents list
brizz metrics query --metric cost
brizz status
```

Session and issue ids accept unique prefixes, resolved against 200 records — the newest sessions, but the highest-priority issues. Anything outside that needs a full UUID. `intents list` adds open-issue counts to the first 30 clusters only.

## Output

On a terminal you get tables and cards. Piped, you get JSON: `tenant`, `app`, and `metrics list` emit true NDJSON, while the session, issue, intent, evidence, and conversation commands emit one indented JSON envelope — pipe those to `jq` rather than reading line by line. `whoami`, `status`, and `summarize` fall back to YAML, and `version` prints text regardless of `--output`.

Override with `--output json|ndjson|yaml|tty|wide` (or `--json`). Disable color with `--no-color` or `NO_COLOR`.

## Agent mode

`--agent` (or `BRIZZ_AGENT=1`) switches to Markdown and adds a next-commands trailer on the supported analytics commands, so an agent can navigate an investigation without knowing command names in advance. It also suppresses update nudges; add `--no-pager` if long output must not be paged.

```bash
brizz issues investigate <id> --agent
```

`brizz agent-guide` prints a workflow guide and `brizz explain <resource>` the built-in field reference. Both are curated summaries — `brizz <command> --help` is the complete one.

## Availability

The CLI reads only what your role already allows. Command-usage logs are **on by default**; opt out with `brizz config telemetry disable`, `BRIZZ_TELEMETRY=0`, or `DO_NOT_TRACK=1`. Crash reporting is separate.

## See also

- [API overview](/docs/api/overview.md) — the Platform API key, and how it differs from a telemetry key.
- [MCP server](/docs/integrations/mcp-server/overview.md) — giving an agent access to Brizz over MCP instead.
- [Issues](/docs/platform/issues.md) and [Sessions](/docs/platform/sessions.md) — what these commands read.