Skip to content

Review command

Jump to bottom
Muhammet Şafak edited this page May 27, 2026 · 1 revision

Review (default command)

When invoked without a subcommand, commitbrief runs a code review against the active scope.

Synopsis

commitbrief [scope-flag] [global-flags...]

Scope flags (mutually exclusive)

Flag Short Default What it reviews
--staged -s yes Staged changes (git diff --cached).
--unstaged -u no Working-tree changes (git diff).

If neither is set, --staged is the default. The two flags are mutually exclusive — passing both is a cobra-level error.

For historic ranges (HEAD~3 HEAD, main...feature, <merge-sha>) use the diff subcommand instead. The v0.x --commit/--branch/--pull-request scope flags were collapsed into diff in v0.9.0.

Path filters

Flag Short Repeatable Notes
--file <path> -f yes Review only these files. Combines with the scope flag.
--dir <path> -d yes Review only files under these directories. 
commitbrief --staged -f src/main.go -f src/util.go
commitbrief --unstaged -d database/seeder -d app/Models

Path filters apply after the diff is parsed and after the ignore layers; see Filtering for the full pipeline.

Pipeline (what happens, in order)

  1. Resolve context — load merged config, pick active provider, resolve language.
  2. Load rules — read COMMITBRIEF.md (or fall back to the embedded default) and OUTPUT.md (template).
  3. Fetch diff — staged/unstaged from the git layer (go-git or git CLI per ADR-0002).
  4. Filter — built-in ignore patterns → .commitbriefignore → --file/--dir path filters.
  5. Pre-send guards:
    • .commitbrief/ guard (ADR-0007): if the diff touches files under .commitbrief/, prompt for confirmation in a TTY; abort in a non-TTY unless --yes is set.
    • Secret scanner: if guard.secret_scan is true and the diff contains credential-shaped patterns, prompt or abort. Bypass with --allow-secrets. --yes does NOT bypass the scanner (since v0.9.1).
  6. Build prompt — wraps rules content in <project_rules>...</project_rules> XML, appends a language directive, appends the diff.
  7. Cache lookup — SHA-256 cache key over diff + system_prompt + provider + model + lang + schema_version. Hit replays the cached response; miss continues.
  8. Cost preflight — estimates token cost; if it exceeds the configured cost.warn_threshold_usd, prompts (TTY) or aborts (non-TTY). Bypass with --no-cost-check. --yes does NOT bypass the preflight (since v0.9.1).
  9. Provider call — sends the prompt; receives structured findings JSON (API providers) or pre-formatted plain text (CLI-tool-backed providers).
  10. Render — cards (default TTY), JSON, or markdown.
  11. Copy (optional) — pushes findings to clipboard via OSC 52 plus native tools.
  12. Fail-on — if --fail-on=<severity> is set, exits non-zero when any finding meets or exceeds that severity.

Inherited global flags

Every flag on Global flags applies. Most relevant:

  • Output: --json, --markdown, --output <file>, --copy, --compact, --verbose/-v, --quiet/-q, --color.
  • Provider override: --provider <name>, --model <name>, --cli <claude|gemini> (shorthand for --provider <name>-cli; mutually exclusive with --provider AND with --json / --markdown since CLI providers emit pre-formatted text).
  • Cache: --no-cache to bypass.
  • Guards: --allow-secrets, --no-cost-check, --yes.
  • CI gating: --fail-on=<critical|high|medium|low|info|any|none>.
  • Locale: --lang en|tr.

Exit codes

Code Meaning
0 Review completed; no --fail-on threshold reached.
1 An error occurred (git failure, provider error, parse failure, guard abort, etc.) OR --fail-on threshold was reached.

See Exit codes for the precise --fail-on semantics.

Examples

# Standard review of staged changes, default rendering.
commitbrief

# Working-tree review, plain markdown to a file.
commitbrief --unstaged --markdown --output review.md

# Pipe JSON into jq for tooling.
commitbrief --json | jq '.findings[] | select(.severity=="critical")'

# CI gate: exit non-zero on any high-or-worse finding.
commitbrief --staged --fail-on=high

# Restrict to a single subdirectory.
commitbrief --staged --dir cmd/server

# Override the configured provider for this one invocation.
commitbrief --provider gemini --model gemini-2.5-flash

# Use the locally-installed Claude Code CLI as the backend.
commitbrief --cli claude --staged

Clone this wiki locally