brittle

Terminal + MCP access to Brittle — query runs, sessions, and AI failure analysis from a shell, a CI script, or an AI coding agent.

One binary, three surfaces over a single typed /api/cli/* namespace:

• CLI commands — brittle runs list, brittle sessions logs, etc. for terminals and CI scripts.
• MCP server — brittle mcp exposes the same operations as MCP tools, so Claude Code / Cursor / Aider users get inline access to failure context while editing code.
• JSON pipe — every command takes --json for jq / shell automation.

Install

npm install -g @brittlehq/cli
# or
pnpm add -g @brittlehq/cli

Verify:

brittle --help

First-run setup

Brittle's CLI authenticates with an API token minted from the dashboard.

1. Mint a token. Open your project's dashboard → Tokens → New token → copy the value (it's shown once).

2. Log in. Run:

   brittle login

   The CLI prompts for the Brittle URL (default https://hub.brittle.dev) and the token (hidden input — no echo, no shell history exposure). Token is validated against GET /api/cli/me before anything is written to disk.

3. Verify.

   brittle whoami

Credentials are stored at ~/.config/brittle/credentials.json with mode 600. To rotate, run brittle logout then brittle login again. Server-side token revocation happens in the dashboard.

Non-interactive (CI)

Skip brittle login entirely — set two env vars:

export BRITTLE_TOKEN=gw_...
export BRITTLE_URL=https://hub.brittle.dev
brittle runs list --failed --limit 5

The CLI checks env vars first and falls through to the credentials file only when they're unset.

Commands

brittle runs <list|show|failures|watch>

List, inspect, and tail CI runs.

# 30 most recent runs in the active project, newest first
brittle runs list

# Only failed runs on a specific branch
brittle runs list --branch main --failed --limit 10

# Full detail for one run
brittle runs show cmpb9p0ir00in5xacoxau9ocy

# AI-detected failure groups for a run — root cause + key errors + severity
brittle runs failures cmpb9p0ir00in5xacoxau9ocy

# Tail a run until terminal status (passed/failed/cancelled)
brittle runs watch cmpb9p0ir00in5xacoxau9ocy

brittle sessions <list|show|logs>

Drill from a run into the individual test sessions inside it.

# All failed sessions in a run
brittle sessions list cmpb9p0ir00in5xacoxau9ocy --result failed

# One session's full detail + error
brittle sessions show cmpb9pj3g00l85xac0n9p3rtl

# WebdriverIO command timeline (JSON — pipe into jq for analysis)
brittle sessions logs cmpb9pj3g00l85xac0n9p3rtl | jq '.[] | select(.duration > 1000)'

brittle failures show <groupId>

Drill into one AI failure group with root cause, key errors, suggested fix, and the list of failing sessions.

brittle failures show cmpbdn9z...

brittle whoami

Show the active session — org, project, token name, scopes, expiry.

brittle whoami
brittle whoami --json

--json on every read command

Every list/show/failures command takes --json and emits the raw /api/cli/* response on stdout for scripting:

# Find the slowest 5 sessions in the latest failed run
brittle runs list --failed --limit 1 --json \
  | jq -r '.items[0].id' \
  | xargs -I {} brittle sessions list {} --json \
  | jq '.items | sort_by(.durationMs) | reverse | .[0:5]'

MCP server

brittle mcp boots an MCP (Model Context Protocol) server on stdio. AI coding agents (Claude Code, Cursor, Aider, Continue) can wire this in to query your test failures inline while editing code.

Claude Code

Add to your Claude Code config:

claude mcp add brittle brittle mcp

Or edit ~/.claude/mcp.json directly:

{
  "mcpServers": {
    "brittle": {
      "command": "brittle",
      "args": ["mcp"],
    },
  },
}

Cursor

Edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "brittle": {
      "command": "brittle",
      "args": ["mcp"],
    },
  },
}

Authentication

The MCP server inherits whatever credentials brittle login set up — no separate config. For CI / containerized / shared-machine setups, pass the token via the client's env block instead of relying on the file:

{
  "mcpServers": {
    "brittle": {
      "command": "brittle",
      "args": ["mcp"],
      "env": {
        "BRITTLE_TOKEN": "gw_...",
        "BRITTLE_URL": "https://hub.brittle.dev",
      },
    },
  },
}

Available tools

The MCP server exposes 8 tools — same operations as the CLI:

| Tool | Returns | | ------------------------- | ------------------------------------------------- | | whoami | Org / project / token of the active session | | list_runs | Paginated runs list (filters: branch, failed) | | get_run | Single run detail | | get_run_failures | AI failure groups + root causes for a run | | list_run_sessions | Sessions within a run (filters: browser, result) | | get_session | Single session detail + error text | | get_session_command_log | wdio command timeline (parsed JSON) | | get_failure_group | Single failure group: root cause, key errors, fix |

Tool descriptions are tuned for agent decision-making — open the source at packages/cli/src/mcp/tools.ts if you want to see exactly what an agent sees.

Exit codes

Useful for scripting:

| Code | Meaning | | ---- | ----------------------------------------- | | 0 | success | | 1 | generic failure / 404 / not found | | 2 | auth — token missing, invalid, or revoked | | 3 | network / timeout | | 4 | usage error (bad input) |

Operator commands

The CLI also ships brittle k8s <install|values> for Helm-chart operators on self-hosted Brittle installs. Those are unrelated to the auth-scoped read surface above; run brittle k8s --help for usage.

Development

This package lives at packages/cli/ in the Brittle monorepo.

pnpm install
pnpm --filter @brittlehq/cli dev runs list   # run from source via tsx
pnpm --filter @brittlehq/cli typecheck
pnpm --filter @brittlehq/cli build

See milestones/v6.1.md for the architecture overview.

License

Apache-2.0