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, RuleID, Fingerprint}) plus helpers like groupBySeverity, upper, countFiles. See OUTPUT.md for the template reference.

JSON (schema v1)

Strict machine-readable form. Top-level shape:

{
  "schema": 1,
  "content": "",                      // empty on the happy path; raw response only when parsing degraded
  "findings": [ /* see JSON schema page */ ],
  "summary": {},
  "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.

SARIF

--sarif writes a SARIF 2.1.0 log for GitHub Code Scanning. Requires v1.19.0 or later. Exclusive with --json, --markdown, --suggest-commit, --cli and --show-prompt. See SARIF.

CLI-tool-backed providers (plain text passthrough)

claude-cli, gemini-cli, and codex-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). Combining the --cli flag with --json, --markdown or --sarif is rejected upfront.

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.
• SARIF — Code Scanning output.
• Rule IDs — the closed list behind rule_id.

See also: Output formats