Quickstart

Run your first advisory review in five minutes. Every command and every output snippet below is real shipmoor review behavior.

1. Install the CLI

Shipmoor installs as one universal local executable named shipmoor:

curl -fsSL https://dl.shipmoor.dev/install.sh | bash

The binary lands at ~/.shipmoor/bin/shipmoor. Community, Pro, and Team behavior are determined by your account entitlements, not by which installer URL you used. The advisory review surface ships in the universal binary as of 0.6.0:

shipmoor version          # shipmoor 0.6.0
shipmoor review --help    # confirm your build has the review subcommand

Full install options (channels, pinned versions, PATH) are in Installation.

2. Sign in (the cli_pro entitlement)

shipmoor review is a Pro feature gated behind the cli_pro entitlement. If you run it without that entitlement, it stops before doing any work: no git, no agent, no review.

$ shipmoor review .
shipmoor pro: requires entitlement 'cli_pro'. IC features are available after sign-in; run `shipmoor login`.

$ shipmoor review . --json
{"schema_version": "shipmoor.paid_feature_error.v1", "status": "locked", "entitlement": "cli_pro", "reason": "not_logged_in", "message": "requires entitlement 'cli_pro'. IC features are available after sign-in; run `shipmoor login`.", "next_command": "shipmoor login", "billing_url": null, "authenticated": false, "plan": "community", "entitlement_state": "signed_out"}

Both of those exit with code 2. Sign in with the device flow:

shipmoor login

Check your capability state any time:

shipmoor capabilities --json   # .capabilities.cli_pro.enabled is true or false

3. Configure an agent

A review needs a reviewer. You bring it with --agent. The easiest way is the built-in claude preset, which drives your locally installed claude CLI:

shipmoor review . --agent claude

claude here is a bundled preset, not a shell command. Shipmoor ships a small adapter inside the binary that flattens the review request into a prompt, runs claude, and translates its answer into review findings. There is nothing extra to install or wire up. You just need claude on your PATH. To point the preset at a different invocation, set SHIPMOOR_REVIEW_CLAUDE_CMD, for example SHIPMOOR_REVIEW_CLAUDE_CMD="claude -p --model …". The codex preset works the same way via --agent codex (override it with SHIPMOOR_REVIEW_CODEX_CMD).

A custom —agent command must speak the wire contract. Apart from the built-in presets (claude, codex), —agent <command> is shlex-split and executed as a subprocess, and Shipmoor pipes a JSON review request to its stdin and reads a JSON response from its stdout. A raw claude -p does not speak that protocol. It just takes a prompt and prints text, which is exactly why the claude preset exists. To bring your own, point —agent at a program that implements the wire contract. A copyable, runnable reference (example-agent.py) is described in AI coding agents.

The self value you will see in the Shipmoor Skills (shipmoor review —agent self) is a Skills-context placeholder meaning “the agent already running this skill”. The agent substitutes its own invocation. The bare CLI has no self sentinel. Passing it literally tries to run a program called self and exits 2 with agent command ‘self’ not found ….

You can also set the agent (and other defaults) once in .shipmoor.yaml. See step 6.

4. Preview before you spend a token

--preview resolves the change selection and plans the run without invoking your agent, which is handy to confirm what would be reviewed:

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

--preview needs no --agent and always exits 0.

5. Run a review on your working tree

With no selector, shipmoor review reviews your working tree (tracked changes plus untracked files). A run with findings looks like this:

$ shipmoor review . --agent claude
Advisory code review — findings are informational and never gate
review complete: 1 advisory finding(s)
  ○ calc.py:2 Subtraction where addition is expected; this inverts the result.

The header (findings are informational and never gate) and the dim ○ markers are deliberate: they distinguish an advisory review from the scan gate. A clean run reads review complete: no advisory findings. Either way the exit code is 0. A review never fails your build (see exit codes).

Reading the machine output

--json writes the shipmoor.scan.v1 contract. A review finding is an ordinary scan finding stamped with category: "code_review" and rule_id: "shipmoor.review.llm":

$ shipmoor review . --agent claude --json

{
  "schema_version": "shipmoor.scan.v1",
  "tool": {
    "name": "shipmoor",
    "version": "0.6.0",
    "rules": [
      {
        "rule_id": "shipmoor.review.llm",
        "name": "Shipmoor Code Review",
        "short_description": "Advisory review comment from the Shipmoor code reviewer.",
        "full_description": "An advisory finding produced by the Shipmoor code reviewer running the developer's own agent. These comments are informational: they are never counted toward the scan's fail-on gate.",
        "default_severity": "medium",
        "category": "code_review"
      }
    ]
  },
  "summary": { "total_files": 1, "scanned_files": 1, "findings_count": 1 },
  "findings": [
    {
      "id": "SHM-08f43e50eb9285ce",
      "rule_id": "shipmoor.review.llm",
      "language": "python",
      "severity": "medium",
      "confidence": "medium",
      "category": "code_review",
      "path": "calc.py",
      "start_line": 2,
      "start_col": 1,
      "end_line": 2,
      "end_col": 1,
      "message": "Subtraction where addition is expected; this inverts the result.",
      "root_cause": "",
      "recommendation": "return a + b",
      "evidence": { "existing_code": "return a - b  # bug" },
      "change_status": "introduced",
      "fingerprint": "08f43e50eb9285ce728d71d025cae3dcfca048ab20ffa7d70fb03a7c8ca4b478"
    }
  ]
}

Notable fields: recommendation carries the agent’s suggested fix, evidence.existing_code is the line it flagged, and change_status is introduced for lines your diff added (versus existing or unknown). Write SARIF 2.1.0 with --sarif, and send either format to a file with --output:

shipmoor review . --agent claude --sarif --output review.sarif

6. Make it the default (.shipmoor.yaml)

So you do not repeat --agent every time, add a review: block to your project config. shipmoor init writes a commented template. Uncomment and fill it in:

review:
  agent: "claude"        # built-in preset (drives your `claude` CLI); or any wire-contract command
  concurrency: 8          # per-file worker pool (default 8)
  timeout: 120            # per-file timeout in seconds (default 120)
  background: false
  exclude:
    - "**/generated/**"   # extra excludes for whole-file (--scan) mode

Flags override config, and config overrides the built-in defaults. The review: block is additive: older parsers ignore it and it never bumps the config schema_version.

Next

• The complete flag set, selectors, and exit-code model: CLI reference.
• Wire your agent or drive a review then fix loop: AI coding agents.
• See findings in your editor: IDE.