Usage
miucr review is the daily command. It reviews local changes or a GitHub PR and prints a JSON envelope by default. This page covers its flags.
miucr review --staged --gate highOther commands: init, login, whoami, logout, review, trace, history, config, rules, eval, mcp, serve, upgrade, version. See Serve & action, Rules, History, Evaluation, Providers & config, Credentials, and MCP.
Review modes
Section titled “Review modes”Pick exactly one mode per run. The CLI and the MCP review_run tool enforce the same rule.
miucr review --staged # staged changesmiucr review --from main --to HEAD # ref range (--from and --to go together)miucr review --commit HEAD~1 # one commit| Mode | Diff reviewed |
|---|---|
--staged | git diff --cached, with the new side read from the index. What you are about to commit, not your unstaged tree. |
--from / --to | <to> against merge-base(from, to). The changes a PR from from would introduce. |
--commit | One commit against its first parent. |
The severity gate
Section titled “The severity gate”--gate makes review fail CI when a finding reaches a severity.
- Severities, low to high:
info,low,medium,high,critical. --gate nonereports findings and never fails. Default:high.- An unknown gate is rejected before the run starts, so a typo never disables gating.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 | Success. No finding reached the gate. |
1 | Operational error, such as missing credentials or an internal failure. |
2 | A finding reached --gate, or the invocation was invalid (bad gate, conflicting modes, bad --output, bad format or config value). |
130 | Interrupted with Ctrl-C (review.canceled). |
Output formats
Section titled “Output formats”-o / --output is a global flag: json (default), pretty, or sarif.
| Format | Use | Notes |
|---|---|---|
json | Agents and scripts | The miucr.cli/v1 envelope. |
pretty | Humans | Each finding shows a jumpable file:line (or file:start-end), severity and category, rationale, quoted-code excerpt, and a suggested-patch preview. Color only on a TTY. On non-review commands it indents the JSON. |
sarif | Code scanning, IDEs | SARIF 2.1.0. Tool miucr, ruleId = category, level from severity, region from the anchored lines, snippet = quoted code, fixes from the suggested patch. Paths are repo-relative. Review only. |
--sarif-out <file>
Section titled “--sarif-out <file>”--sarif-out writes SARIF next to the normal output (JSON or a posted PR review) from the same run. No second LLM pass. The file is written only on success (temp file plus rename), so a failed run leaves no stale file.
miucr review --staged --sarif-out miucr.sarifmiucr review --pr owner/repo#123 --post --sarif-out miucr.sarifThe GitHub Action uses this for the Security tab. See Action: SARIF.
--filter-mode (PR only)
Section titled “--filter-mode (PR only)”Which findings may be posted inline on --pr. Default diff_context.
| Mode | Inline-eligible findings |
|---|---|
added | Added (+) lines only. |
diff_context | Added or context lines. Default. |
file | Any file in the diff. |
nofilter | Every finding. |
file and nofilter never place a comment on a line GitHub would reject. A finding that cannot sit on its own changed line shares one thread on the nearest changed line, or becomes one PR comment. Info notes in files the PR does not touch are marked irrelevant and do not block. They still appear in the summary, SARIF, and local output.
--format (PR only)
Section titled “--format (PR only)”How the posted comment looks. Render-only: it never changes which findings are produced or posted.
| Format | Comment |
|---|---|
full (default) | Full summary (result line, What changed, tables, review reference) plus severity and priority badges. |
minimal | No summary section and no badges. Inline findings, footer, and hidden markers stay, so re-runs still update the same comment. |
Set per run with --format, or as a default with [review].format (CLI) or review.format (host). Other values fail with flags.invalid_format or config.invalid (exit 2).
--prompt-format
Section titled “--prompt-format”Structure of the prompt sent to the model. Orthogonal to --format.
| Format | Structure |
|---|---|
xml (default) | Untrusted content (diffs, file contents, project context, rules, conversation) is wrapped in entity-escaped XML tags. A forged </file> inside a diff is inert text, so a fork PR cannot fake a file boundary. |
markdown | The earlier fenced form (=== File: === delimiters). Byte-identical to releases up to 0.65. Opt-out only. |
xml is the default for injection hardening. On the labeled eval suite it matches markdown on recall. Pin the old form with --prompt-format markdown or [review].prompt_format = "markdown". Other values fail with flags.invalid_prompt_format or config.invalid (exit 2).
JSON envelope
Section titled “JSON envelope”Stable api_version: "miucr.cli/v1", so a host agent can branch without parsing prose.
{ "ok": true, "api_version": "miucr.cli/v1", "kind": "review.result", "command": "review", "request_id": "req_...", "summary": { "findings": 2, "gate": "high" }, "data": { "findings": [ { "file": "internal/foo/bar.go", "line": 42, "end_line": 42, "severity": "high", "category": "bug", "rationale": "...", "suggested_patch": "...optional minimal fix...", "quoted_code": "...verbatim source the finding anchors to..." } ], "stats": { "files_changed": 3, "files_reviewed": 2, "findings_total": 2, "findings_dropped": 1, "max_severity": "high", "gate": "high", "truncation_level": "full" }, "review_id": "rev_..." }}| Field | Meaning |
|---|---|
data.findings[] | file, line, end_line, severity, category, rationale, suggested_patch, quoted_code. |
stats.findings_dropped | Findings whose quoted code no longer matches the reviewed revision. See How it works. |
stats.truncation_level | full, hunks_only, or filenames_only, depending on how much context fit --token-budget. |
data.review_id | Id of the saved record for History. Empty with --no-save. |
Failures use the same envelope with ok: false and an error object: a stable code, a redacted message, and a hint.
Error codes
Section titled “Error codes”error.code | When | retryable |
|---|---|---|
agent.auth_failed | Invalid API key (401/403). | false |
agent.auth_expired | Expired OAuth token (401/403, including codex still-401 after refresh). | false |
provider.rate_limited | Provider returned 429. | true |
agent.unavailable | Provider returned 5xx or 529. | true |
review.timeout | The review hit a deadline: the job deadline (--timeout), the per-call [review].call_timeout, or a nested deadline of unknown origin. The message says which, with its budget and elapsed time. | true |
review.stalled | No progress for [review].stalled_timeout. | true |
review.canceled | Interrupted (Ctrl-C / SIGINT), exit 130. | false |
config.invalid | Malformed config, bad enum or auth value, or an openai gateway profile with a key but no base_url. Exit 2. | false |
internal.error | Anything unclassified. Never marked retryable. | false |
Messages are redacted. No token fragment appears in any error.
Provider calls retry 429, 5xx/529, and transient transport errors before they fail. Tuning lives in [review.provider_retry] (see Providers). Auth and invalid-request errors are never retried. The codex backend also retries response.failed events and honors Retry-After. On a codex usage cap, provider.rate_limited carries error.details.resets_in_seconds (or retry_after_seconds) and a hint such as usage cap reached, resets in ~2h.
On --pr --post, failures are also written to the PR summary. See GitHub PR review.
Selection flags
Section titled “Selection flags”miucr review --staged --ext go,tsmiucr review --staged --include 'internal/**' --exclude '**/*_test.go'| Flag | Default | Meaning |
|---|---|---|
--repo <dir> | . | Repository directory. |
--ext | all | Comma-separated file extensions. |
--include / --exclude | none | Repeatable doublestar globs. |
Context and budget flags
Section titled “Context and budget flags”These can also be set under [review] in ~/.config/miu/cr/config.toml. An explicit flag wins. Keys are listed in Providers & config.
| Flag | Default | Meaning |
|---|---|---|
--expand <n> | 5 | Context lines above and below each hunk. 0 disables. |
--token-budget <n> | 0 (no cap) | Approximate budget. Over budget, context degrades down the truncation ladder. |
--timeout <dur> | see note | Whole-review timeout. |
--deep-context | off | Heavier defaults for large reviews: --expand 20, automatic related-file hops, and root AGENTS.md / CLAUDE.md from the reviewed revision. Explicit flags still win. |
--context-hops <n> | auto | Related-file depth from changed files. 0 disables, max 5. Overrides the automatic depth from --deep-context. |
--instruction <text> | none | Extra steer for this review, e.g. "focus on the auth changes". Fenced, context-only, length-capped. It cannot change the finding schema. |
--timeout: the review default is30munless--timeoutor[review].timeoutis set.--deep-contextkeeps that default.- Stalled-run watchdog:
[review].stalled_timeout, default8m."0s"disables it for debugging. - Per-call cap:
[review].call_timeout, unset by default (a call may use the time left on--timeout). See Providers. - Hops follow Go package imports, reverse imports, and basic relative JS/TS/Python imports. They are capped by file count and bytes. Fork PRs skip root project context and hop context.
Subagents and symbol context
Section titled “Subagents and symbol context”[review.subagents]splits a large review into scoped passes by glob. It is still one review: candidate findings are merged, re-anchored, deduped, and gated as usual. A failed required subagent marks the run degraded, so--approvalwill not approve and checks will not report success.symbol_contextis a built-in read-only tool, next tofile_readandgrep. It answers cross-file questions: definitions, references, callers, implementations, and dependencies. Languages: Go, TypeScript/JavaScript, Python, PHP, SQL, Rust, Java/C#, C/C++, and Astro/Vue/Svelte components.
Config keys ([review.subagents], [review.tools], [review.tools.symbol_context]) are in Providers & config. Runtime behavior is in How it works.
Provider flags
Section titled “Provider flags”--provider anthropic|openai|auto(defaultauto), or any profile name from config. See Providers.--api-key,--base-url,--auth-token,--model: per-run overrides. Never persisted.--auth-tokenis Anthropic only.
Project rules
Section titled “Project rules”Each review gets the built-in rules plus any .miu/cr/rules/*.md (repo) and ~/.config/miu/cr/rules/*.md (user) that match the changed files. Rules are context only and never gate. Scaffold with miucr rules init, and check selection with miucr rules check <path>. See Project rules.
PR review (--pr)
Section titled “PR review (--pr)”Details and examples are in GitHub PR review.
| Flag | Default | Meaning |
|---|---|---|
--pr <url or owner/repo#N> | none | Review a GitHub PR. A public PR dry run needs no token. |
--post / --no-post | --no-post | Publish, or dry run. Mutually exclusive. |
--token <pat> | GITHUB_TOKEN, then GH_TOKEN | PAT with repo scope. Needed only for --post. Never persisted. |
--mode review|checks | review | Inline comments and summary, or a GitHub Check Run named miu-cr. |
--min-severity | no floor | none to critical. Floor for inline comments only. Lower findings still appear in the summary and SARIF. |
--suggest | off | One-click suggestions for proven fixes. Requires --post. |
--approval off|clean|threshold | off | Submit APPROVE by policy. Requires --post. |
--approval-max-priority | P4 | Threshold mode: approve when the worst blocking finding is at or below this priority (P0 to P4). |
--approval-note | always | Approval body: none, on_findings, or always. |
--conversation | off | Inject the prior PR conversation as untrusted context. One extra read, no extra LLM call. Dropped on fork PRs. |
--force | off | Re-review even when the head SHA was already reviewed. |
--walkthrough | on | ”What changed” bullets in the summary. |
--walkthrough-diagram | off | Optional Mermaid change diagram in the summary. |
--file-change-summary | off | ”Important Files Changed” table in the summary. |
Serve and the GitHub Action have their own defaults for suggest and approval. See Serve & action.
version
Section titled “version”miucr version # {"ok":true,"data":{"version":"v0.x.y"}, ...}