Skip to content

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.

Terminal window
miucr review --staged --gate high

Other 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.

Pick exactly one mode per run. The CLI and the MCP review_run tool enforce the same rule.

Terminal window
miucr review --staged # staged changes
miucr review --from main --to HEAD # ref range (--from and --to go together)
miucr review --commit HEAD~1 # one commit
ModeDiff reviewed
--stagedgit 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.
--commitOne commit against its first parent.

--gate makes review fail CI when a finding reaches a severity.

  • Severities, low to high: info, low, medium, high, critical.
  • --gate none reports findings and never fails. Default: high.
  • An unknown gate is rejected before the run starts, so a typo never disables gating.
CodeMeaning
0Success. No finding reached the gate.
1Operational error, such as missing credentials or an internal failure.
2A finding reached --gate, or the invocation was invalid (bad gate, conflicting modes, bad --output, bad format or config value).
130Interrupted with Ctrl-C (review.canceled).

-o / --output is a global flag: json (default), pretty, or sarif.

FormatUseNotes
jsonAgents and scriptsThe miucr.cli/v1 envelope.
prettyHumansEach 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.
sarifCode scanning, IDEsSARIF 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 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.

Terminal window
miucr review --staged --sarif-out miucr.sarif
miucr review --pr owner/repo#123 --post --sarif-out miucr.sarif

The GitHub Action uses this for the Security tab. See Action: SARIF.

Which findings may be posted inline on --pr. Default diff_context.

ModeInline-eligible findings
addedAdded (+) lines only.
diff_contextAdded or context lines. Default.
fileAny file in the diff.
nofilterEvery 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.

How the posted comment looks. Render-only: it never changes which findings are produced or posted.

FormatComment
full (default)Full summary (result line, What changed, tables, review reference) plus severity and priority badges.
minimalNo 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).

Structure of the prompt sent to the model. Orthogonal to --format.

FormatStructure
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.
markdownThe 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).

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_..."
}
}
FieldMeaning
data.findings[]file, line, end_line, severity, category, rationale, suggested_patch, quoted_code.
stats.findings_droppedFindings whose quoted code no longer matches the reviewed revision. See How it works.
stats.truncation_levelfull, hunks_only, or filenames_only, depending on how much context fit --token-budget.
data.review_idId 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.codeWhenretryable
agent.auth_failedInvalid API key (401/403).false
agent.auth_expiredExpired OAuth token (401/403, including codex still-401 after refresh).false
provider.rate_limitedProvider returned 429.true
agent.unavailableProvider returned 5xx or 529.true
review.timeoutThe 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.stalledNo progress for [review].stalled_timeout.true
review.canceledInterrupted (Ctrl-C / SIGINT), exit 130.false
config.invalidMalformed config, bad enum or auth value, or an openai gateway profile with a key but no base_url. Exit 2.false
internal.errorAnything 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.

Terminal window
miucr review --staged --ext go,ts
miucr review --staged --include 'internal/**' --exclude '**/*_test.go'
FlagDefaultMeaning
--repo <dir>.Repository directory.
--extallComma-separated file extensions.
--include / --excludenoneRepeatable doublestar globs.

These can also be set under [review] in ~/.config/miu/cr/config.toml. An explicit flag wins. Keys are listed in Providers & config.

FlagDefaultMeaning
--expand <n>5Context 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 noteWhole-review timeout.
--deep-contextoffHeavier 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>autoRelated-file depth from changed files. 0 disables, max 5. Overrides the automatic depth from --deep-context.
--instruction <text>noneExtra 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 is 30m unless --timeout or [review].timeout is set. --deep-context keeps that default.
  • Stalled-run watchdog: [review].stalled_timeout, default 8m. "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.
  • [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 --approval will not approve and checks will not report success.
  • symbol_context is a built-in read-only tool, next to file_read and grep. 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 anthropic|openai|auto (default auto), or any profile name from config. See Providers.
  • --api-key, --base-url, --auth-token, --model: per-run overrides. Never persisted. --auth-token is Anthropic only.

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.

Details and examples are in GitHub PR review.

FlagDefaultMeaning
--pr <url or owner/repo#N>noneReview a GitHub PR. A public PR dry run needs no token.
--post / --no-post--no-postPublish, or dry run. Mutually exclusive.
--token <pat>GITHUB_TOKEN, then GH_TOKENPAT with repo scope. Needed only for --post. Never persisted.
--mode review|checksreviewInline comments and summary, or a GitHub Check Run named miu-cr.
--min-severityno floornone to critical. Floor for inline comments only. Lower findings still appear in the summary and SARIF.
--suggestoffOne-click suggestions for proven fixes. Requires --post.
--approval off|clean|thresholdoffSubmit APPROVE by policy. Requires --post.
--approval-max-priorityP4Threshold mode: approve when the worst blocking finding is at or below this priority (P0 to P4).
--approval-notealwaysApproval body: none, on_findings, or always.
--conversationoffInject the prior PR conversation as untrusted context. One extra read, no extra LLM call. Dropped on fork PRs.
--forceoffRe-review even when the head SHA was already reviewed.
--walkthroughon”What changed” bullets in the summary.
--walkthrough-diagramoffOptional Mermaid change diagram in the summary.
--file-change-summaryoff”Important Files Changed” table in the summary.

Serve and the GitHub Action have their own defaults for suggest and approval. See Serve & action.

Terminal window
miucr version # {"ok":true,"data":{"version":"v0.x.y"}, ...}