Global flags

Home / Configuration / Global flags

Global flags

Every flag below is PersistentFlags() on the root command, so it works on the bare review (commitbrief --staged) and on every subcommand that does not override it (commitbrief dry-run --json, commitbrief diff HEAD --copy, …).

The --staged / --unstaged scope flags are also re-bound on dry-run — they are scope-specific, not strictly global. Most subcommands ignore them.

Output

Flag	Short	Type	Default	Notes
--json	—	bool	false	Emit machine-readable JSON output (schema v1). Suppresses the cards renderer.
--markdown	—	bool	false	Emit plain markdown (no ANSI).
--output <path>	-o	string	(stdout)	Write output to file instead of stdout. Honored by both the structured renderers and the plain-text emit path used by CLI-tool-backed providers (UC-07).
--copy	—	bool	false	Copy findings (severity, path, title, description) to the system clipboard via OSC 52 + native tool (wl-copy / xclip / xsel). Best-effort; failures are silent.
--compact	—	bool	false	One-line-per-finding dense output.
--verbose	-v	bool	false	Show token / cost / latency footer below the findings.
--quiet	-q	bool	false	Suppress info messages on stderr (progress, "using built-in rules", etc.).
--color <mode>	—	string	auto	auto / always / never. Auto detects TTY. NO_COLOR / COMMITBRIEF_NO_COLOR env vars override always.
--lang <code>	—	string	(config / en)	AI output language (any recognized language, e.g. tr/fr/de). The CLI interface localizes only for en/tr, else English. Chain: --lang → repo output.lang → user output.lang → English; invalid/empty falls through (ADR-0021).

Filtering

Flag	Short	Type	Default	Notes
--file <path>	-f	string slice	(none)	Review only these files (repeatable).
--dir <path>	-d	string slice	(none)	Review only files under these directories (repeatable).

Both combine with the active scope flag and apply after the ignore layers. See Filtering.

Provider / model

Flag	Type	Default	Notes
--provider <name>	string	(from config)	Override configured provider for this invocation. Mutually exclusive with --cli.
--model <name>	string	(from config)	Override configured model for this invocation.
--cli <claude|gemini|codex>	string	(none)	Shorthand for --provider claude-cli / gemini-cli / codex-cli. Mutually exclusive with --provider, --json, --markdown (UC-07).
--with-context	bool	false	CLI providers only. Let the host CLI read project files beyond the diff (read-only, in the repo root) to ground the review (ADR-0017). Errors with an API provider. Prints a security caution each run — the agent may read files outside the diff (incl. untracked secrets) and the pre-send secret scan covers the diff only. See Provider: CLI tools.

Cache + guards

Flag	Type	Default	Notes
--no-cache	bool	false	Bypass cache (read AND write). Forces a fresh provider call.
--allow-secrets	bool	false	Bypass the pre-send secret scanner. Use with care.
--no-cost-check	bool	false	Skip the pre-send cost estimate prompt.
--show-prompt	bool	false	Print the exact system + user prompt that would be sent to the model, then exit. No provider call, no cache lookup, no cost. Reflects every prompt-shaping flag (scope, --with-context, --cli / --provider, --lang) and honours --output. A transparency inspector for "what exactly leaves my machine?" — fuller than dry-run, which shows only metadata.
--yes (-y)	bool	false	Auto-confirm prompts (pre-send .commitbrief/ guard, init overwrite, cache clear). Since v0.9.1, --yes does not bypass the secret scanner or cost preflight — use the dedicated flags above.

CI gating

Flag	Type	Default	Notes
--fail-on <sev>	string	"" (off)	Exit 1 if any finding meets/exceeds severity. Values: critical, high, medium, low, info, any, none. See Exit codes.
--min-severity <sev>	string	"" (off)	Display-only filter: hide findings below this severity in the rendered output (Cards, Markdown, --copy). Values: critical, high, medium, low, info, none. --json stays complete (machine contract) and --fail-on always evaluates the full set, so CI gating is never weakened. An invalid value errors.
--suggest-commit	—	bool	false

Hidden flags

Flag	Type	Default	Notes
--gen-man <dir>	string	(none)	Generate man pages into <dir> and exit. Used by make manpage; hidden from --help.

Mutually exclusive groups

Enforced by cobra; passing both flags is an error before any work begins.

• --provider × --cli
• --cli × --json
• --cli × --markdown
• --staged × --unstaged
• (compress) --dry-run × --out

Version

commitbrief --version

Prints commitbrief vX.Y.Z (commit <sha>, built <iso-ts>) and nothing else — the splash logo is suppressed for --version so the output is a single machine-parseable line (safe to pipe into a script). The commit and date are ldflags-injected at release time; go install fills the version from runtime/debug.BuildInfo but leaves commit/date as none / unknown.

Help

commitbrief --help
commitbrief <subcommand> --help

Standard cobra-rendered help. commitbrief list is the richer, human-curated reference.

See also

• Filtering — how --file / --dir narrow scope.
• Output formats — --json, --markdown, cards.
• Exit codes — --fail-on and CI gating.
• Configuration files — config that flags override.