Install
// docs · v1.0

Output formats

Cards, JSON, markdown, --copy, --compact, --verbose — every way CommitBrief renders review findings.

CommitBrief renders review findings in three primary forms. The choice is driven by global output flags; if none are set and the destination is a TTY, the colored cards renderer is the default.

Cards (default TTY)

Lipgloss-styled header / status / footer with one panel per finding. Each panel is severity-coded (color of the left border) and includes the finding’s title, location, description, suggestion, and a code snippet when present.

Triggered when: TTY stdout AND no --json / --markdown flag AND --color resolves to ON.

This is the format you see in your terminal during a normal commitbrief --staged session. The output is not designed to be parsed; it is designed to be read.

Markdown

Plain markdown — no ANSI escapes, no lipgloss boxes. The same finding content rendered through the OUTPUT.md template (or its embedded default).

Triggered by --markdown, by --color=never, or by a non-TTY stdout. The bare commitbrief --staged > review.md path also produces markdown.

The template has access to .Findings (typed []Finding{Severity, File, Line, LineEnd, Title, Description, Suggestion, Language, Snippet}) plus helpers like groupBySeverity, upper, countFiles. See OUTPUT.md for the template reference.

JSON (schema v1)

Strict machine-readable form. Top-level shape:

{
  "schema": "v1",
  "content": "",
  "findings": [
    {
      "severity": "high",
      "file": "internal/handlers/auth.go",
      "line": 42,
      "line_end": 56,
      "title": "Missing authorization check on admin route",
      "description": "...",
      "suggestion": "...",
      "language": "go",
      "snippet": "..."
    }
  ],
  "summary": { "total": 4, "by_severity": { "high": 1, "medium": 3 } },
  "meta": {
    "provider": "anthropic",
    "model": "claude-opus-4-7",
    "lang": "en",
    "tokens": { "input": 2105, "output": 526, "cached": 0 },
    "cost_usd": 0.0731,
    "latency_ms": 4123
  }
}

Triggered by --json. Bypasses cards / markdown renderers entirely. The schema is v1, locked at v1.0.0, and follows strict semver — additive changes (new optional fields) are allowed in v1.x; renames, removals, or type changes require a v2 bump.

CLI-tool-backed providers — plain text passthrough

claude-cli and gemini-cli emit pre-formatted plain text from the host CLI, not structured findings. The cards renderer is skipped; the host CLI’s output is streamed verbatim to stdout (or to --output <file>). --json and --markdown are rejected upfront when paired with a CLI provider — cobra error before any work runs. See CLI providers.

Output destinations

FlagEffect
--output <path> (-o)Write the rendered output to a file. Applies to cards, markdown, JSON, AND plain-text emit (CLI providers).
--copyCopy a finding summary to the system clipboard via OSC 52 (works over SSH) plus native tools (pbcopy / wl-copy / xclip / xsel / clip.exe). Payload format: [<severity>] <path>:<line>\n<title>\n\n<description> per finding, joined with \n---\n\n.
--compactDense one-line-per-finding output: [icon] SEVERITY • file:line — title. Works in cards and markdown modes.
--verbose (-v)Append a footer with provider / model / tokens / cost / latency.
--quiet (-q)Suppress stderr info messages (progress, rule-source hints).

--json is a renderer choice, not a destination choice; the JSON still goes to stdout (or --output <file>). Combine flags freely:

commitbrief --staged --json --output review.json --quiet

Color resolution

Default --color=auto:

  • TTY stdout + no NO_COLOR env + no COMMITBRIEF_NO_COLOR env → color ON.
  • Otherwise → color OFF.

--color=always forces ON (still overridden by NO_COLOR / COMMITBRIEF_NO_COLOR); --color=never forces OFF unconditionally. Color OFF in cards mode falls back to markdown.

The colored splash logo prints to stderr at the start of every invocation, gated on a TTY-capable stderr. It is NOT part of stdout — commitbrief --json | jq and commitbrief > out stay clean. To suppress it entirely, set NO_COLOR=1 in the environment.

See also