Output formats

Home / Output / Output formats

Output formats

CommitBrief renders review findings in three primary forms. The choice is driven by the 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. Panels are severity-coded (color of the left border) and include the finding's title, location, description, suggestion, and a snippet block when present.

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

This is the format the user sees in their terminal during a normal commitbrief --staged session.

Markdown

Plain markdown — no ANSI escapes, no lipgloss boxes. 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 (non-TTY).

The template has access to .Findings (typed []Finding{Severity, File, Line, Title, Description, Language, Snippet, Suggestion, LineEnd}) 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": "<raw markdown response from the LLM>",
  "findings": [ /* see JSON schema page */ ],
  "summary": { /* aggregate counters */ },
  "meta": { /* provider/model/lang/tokens/cost/latency */ }
}

Triggered by --json. Bypasses cards/markdown renderers entirely. See JSON schema for the full field list.

The schema is v1 and frozen at v1.0.0; v1.x will not change it.

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> since v0.9.2). --json and --markdown are rejected upfront with these providers.

Output destinations

Flag	Effect
--output <path> (-o)	Write the rendered output to a file. Applies to cards, markdown, JSON, AND plain-text emit (CLI providers, since v0.9.2).
--copy	Copy a finding summary (severity, path, title, description) to the system clipboard via OSC 52 + native tools (wl-copy / xclip / xsel). Best-effort; failures silent.
--compact	Dense one-line-per-finding output. 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.

Splash logo

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 output — commitbrief --json | jq stays clean.

The one exception is commitbrief --version: it suppresses the logo so the command emits a single machine-parseable line. --help and every other invocation keep the logo.

See also

• COMMITBRIEF.md — the rules file sent as the system prompt.
• OUTPUT.md — the markdown template.
• JSON schema — the --json contract.