CLI reference

The complete, verified surface of the advisory review command. This is the live help text:

usage: shipmoor review [-h] [--config REVIEW_CONFIG] [--staged |
                       --commit COMMIT | --scan] [--from FROM_REF]
                       [--to TO_REF] [--agent AGENT]
                       [--concurrency CONCURRENCY] [--timeout TIMEOUT]
                       [--background] [--preview] [--json] [--sarif]
                       [--output OUTPUT] [--no-color]
                       [target]

shipmoor review is a peer subcommand of shipmoor scan. Free includes five Review invocations per month; Pro is unlimited. On Free, allowance admission occurs after validation and before the review engine or agent starts.

Positional argument

What gets reviewed: the selectors

By default shipmoor review reviews your working tree (tracked changes plus untracked files) as a diff. The selectors below change that. --staged, --commit, and --scan are mutually exclusive (argparse rejects combining them). --from and --to form a range and must be given together.

shipmoor review                                    # working tree (default)
shipmoor review --staged                           # the staged index
shipmoor review --commit HEAD                       # the last commit vs its parent
shipmoor review --from origin/main --to HEAD        # everything since main
shipmoor review --scan src/                          # whole files under src/

Invalid combinations are usage errors (exit 2) with a specific message:

• --from without --to (or the reverse) gives --from and --to must be given together.
• --scan with any diff selector gives --scan cannot be combined with a diff selector (--from/--to/--commit/--staged).

There is no --changed flag on review (the working tree is the default, and --changed is a shipmoor scan flag). There is no --fail-on either: a review never gates, so there is no threshold to set.

The reviewer: --agent

The simplest form is the built-in claude preset (it drives your local claude CLI, no wiring required):

shipmoor review . --agent claude

Omitting --agent (without --preview) is a usage error:

$ shipmoor review .
shipmoor: --agent is required to run a review (or use --preview); try --agent claude (the built-in preset that drives your `claude` CLI), or set the review.agent config key.

Apart from the presets, the value is shlex-split and executed as a command. See AI coding agents for the request and response wire contract and how to adapt an agent that is not already a stdin-to-stdout filter (a raw claude -p is not one, which is what the claude preset solves). Override the preset’s underlying command with SHIPMOOR_REVIEW_CLAUDE_CMD (or SHIPMOOR_REVIEW_CODEX_CMD). The --agent self form in the Shipmoor Skills is a Skills-context placeholder, not a CLI keyword. The bare CLI has no self sentinel.

Execution knobs

shipmoor review . --agent claude --concurrency 4 --timeout 300

--preview plans without spending a token and always exits 0:

$ shipmoor review . --preview
Advisory code review — preview (no agent invoked)
preview: 1 file(s) to review, 0 excluded (1 changed)

--background returns a handle and exits 0:

$ shipmoor review . --agent claude --background
Advisory code review — launched
review launched (handle: review-run-local)

--background and --preview cannot be combined (usage error: --background and --preview cannot be combined.).

Output

The human, JSON, and SARIF output reuse the exact shipmoor scan plumbing. A review finding is a shipmoor.scan.v1 finding with category: "code_review" and rule_id: "shipmoor.review.llm". The human output adds an advisory header so it never reads like the gate. See the Quickstart for a full JSON sample.

Config

Defaults come from a review: block in .shipmoor.yaml. The precedence is flags, then config, then built-in defaults:

review:
  agent: "claude"
  concurrency: 8
  timeout: 120
  background: false
  exclude:
    - "**/generated/**"   # extra excludes applied in whole-file (--scan) mode

Exit codes

shipmoor review shares the CLI’s exit-code constants but uses a narrowed subset. The defining rule: review never returns 1 (the “threshold breached” code the scan gate uses). A review with findings is still a success.

So:

• Found 10 issues, all critical? Exit 0. Advisory never gates.
• Authentication or allowance denied? Review does not execute; human-facing guidance stays on stderr for machine-output commands.
• Passed --agent self, or an agent that is not on PATH? Exit 2 with agent command '…' not found (a usage mistake: fix the --agent value).
• Your agent crashed or timed out on every file? Exit 3 with a header Advisory code review — failed.

Combining with the gate (shipmoor scan --fail-on)

Use the two commands together. The gate is shipmoor scan with --fail-on. The advice is shipmoor review:

# 1) The deterministic local gate.
shipmoor scan . --changed --fail-on high

# 2) The advisory review.
shipmoor review . --from "origin/main" --to HEAD --agent claude --json --output review.json || true

shipmoor scan --fail-on high returns 1 when a blocking finding crosses the threshold. shipmoor review returns 0 regardless of what it finds. The code_review category is excluded from the gate by construction. Self-managed CI currently supports Scan only; see CI availability.