One universal shipmoor binary serves every tier; a local license unlocks the paid commands. This page is the full surface. Narrative guides live in Community CLI, Claim Check, Agent Skills, and the Agent Harness.
Commands
| Command | What it does | Tier |
|---|---|---|
scan [path] | Structural scan: human, shipmoor.scan.v1 JSON, or SARIF | Community |
scan --changed / --staged / --diff <range> / --patch <file> | Scope the scan to git changes or an unapplied patch | Community |
scan --intent / --prompt / --session | The claim check: does the change earn the claim the task made? | IC (intent_scan) |
scan --intent … --agent "<cmd>" | Escalate the long tail to BYO-Judge (your own agent) | IC (agent_harness) |
rules [--json] | List the rule catalog | Community |
explain <rule-or-finding-id> [--from <report>] | Explain a rule or a specific finding | Community |
resolve-intent | Resolve an intent (no scan, no probes); same resolver as scan | IC (intent_scan) |
repair-guidance --from <report> [--json] | Repair guidance for findings in a report | IC (repair_guidance) |
skills {list,install,uninstall,status} [agent] [--json] | Install Agent Skills into your agent | IC (agent_skills) |
harness <cmd> | Run the scan-to-feedback loop around your agent. See Agent Harness | IC (agent_harness) |
login / logout / whoami [--json] | Device-flow license auth and identity | — |
capabilities --json | This machine’s entitlement contract (shipmoor.capabilities.v1) | — |
upgrade [--non-interactive] | Self-update the binary (channel-aware) | — |
init | Generate a starter .shipmoor.yaml | Community |
version | Version and identity | — |
intent-scan still works as a deprecated alias for scan --intent. Team commands surface only their entitlement-gated availability today; the Team tier is coming soon.
scan flags
Scope (mutually exclusive with a positional path):
| Flag | Scope |
|---|---|
--changed | Staged + unstaged changes |
--staged | Staged only (pre-commit) |
--diff <range> | A git range; main...HEAD gates what the branch adds |
--patch <file> | A unified diff, analyzed in memory without applying |
Output:
| Flag | Effect |
|---|---|
--json / --sarif | Machine output (scan.v1 / SARIF 2.1.0) |
--output <path> | Write the report to a file (stdout otherwise) |
--markdown-summary <path> | Also write a human-readable digest (CI job pages) |
--no-color | Suppress ANSI color (also via NO_COLOR, or automatically when not a TTY) |
Gating:
| Flag | Effect |
|---|---|
--fail-on <none|critical|high|medium> | The structural threshold (default high) |
--config <path> | Explicit .shipmoor.yaml |
Claim Check (IC):
| Flag | Effect |
|---|---|
--intent "<goal>" | One-line intent source |
--prompt "<prompt>" | The agent prompt as a second source (two agreeing sources → medium confidence) |
--session <transcript> | Claude Code / Cursor session: first user turn → intent; plan → plan drift |
--verdict-policy <path> | The gating policy file (Turning on the gate) |
--would-block | Compute the gate as if enabled; always exit 0 |
--explain | Per-expectation probe detail |
--quiet-intent | Collapse the claim check to one badge line |
--agent "<cmd>" | The BYO-Judge agent command |
--judge-role <name> | Role label for the judge invocation |
--author-model-id <id> | Declare who authored the diff (judge isolation) |
--strict-judge-isolation | Author == judge becomes a hard error |
shipmoor harness
The harness automates the scan-to-feedback loop around your coding agent: it invokes the CLI against your edits, feeds the findings back so the agent can self-correct, and records what it saw. It is bundled into the shipmoor binary and invoked as the harness subcommand; there is no separate install. (The standalone shipmoor-harness script is a recognized legacy alias from before the 0.5.0 bundling.) The narrative guides are in Agent Harness; the full subcommand surface is below.
| Command | What it does | Tier |
|---|---|---|
harness status [--json] | Entitlement + install + mode + watch state (harness.status.v1) | IC (agent_harness) |
harness mode {observe|feedback|block} [--force-structural] | Set what findings do. --force-structural pins structural-only checks | IC (agent_harness) |
harness install {aider|claude|codex|cursor|all} [--soft] [--replace-existing] | Wire the loop into an agent’s config | IC (agent_harness) |
harness uninstall {aider|claude|codex|cursor|all} | Remove the harness’s managed wiring | IC (agent_harness) |
harness scan (alias check) [--emit none|json] | One scan of the current change-set, then exit; the one-shot a hook calls | IC (agent_harness) |
harness watch [--emit json|file] [--once] [--daemon] [--stop] | Debounced scan-on-change + event stream | IC (agent_harness) |
harness codex -- <args> | Run Codex with the feedback loop wrapped around it | IC (agent_harness) |
harness inbox [--once] | Consume editor send-back payloads from .shipmoor/agent-inbox/ | IC (agent_harness) |
harness hook {claude-code|cursor} <event> | Internal hook handler invoked by editor hooks (not called by hand) | IC (agent_harness) |
Install and the paid loop are gated by agent_harness; without it the harness prints an upgrade message. The deterministic intent advisories use intent_scan when present and degrade cleanly to structural-scan mode when it’s absent, so Community-tier checks still produce findings. The harness reads this state from shipmoor capabilities --json; it never checks a license itself.
Modes decide what findings do:
| Mode | Behavior |
|---|---|
observe | Scan and record; never interrupt. |
feedback | Return concise findings into the agent’s context so it can self-correct. |
block | Exit non-zero on a threshold breach (foreground dev loops / CI). |
Install adapters. Each surface is marker-managed so it coexists with the Agent Skills installer and is reversible:
| Adapter | Surface written |
|---|---|
claude | .claude/settings.json (PostToolUse + Stop hooks; never edits CLAUDE.md) |
aider | .aider.conf.yml (lint-cmd Aider feeds into its repair loop) |
codex | AGENTS.md (guidance block; run Codex via the codex wrapper) |
cursor | .cursor/hooks.json (native afterFileEdit + stop); --soft writes a guidance-only .cursor/rules/shipmoor-harness.md instead |
install aider --replace-existing overwrites a pre-existing user lint-cmd (otherwise a conflict). harness watch --daemon runs the watcher detached (pidfile + size-capped logfile under .shipmoor/, survives SIGHUP); harness watch --stop stops it; --once, --daemon, and --stop are mutually exclusive. A daemon must run in observe or feedback; block is a foreground gate and is refused.
The watch loop and the scan one-shot record .shipmoor/last-watch.json (shipmoor.harness.report.v1), whose findings[] are the CLI’s scan.v1 objects forwarded verbatim. See Output contracts & schemas.
The harness wrapper has its own exit codes (
0ok ·1blocked ·2error), distinct from the CLI’s0/1/2/3. The Codex wrapper adds3for a Codex failure.
Exit codes
scan: 0 clean · 1 gate fired (report still written) · 2 usage · 3 scan failed. The full contract, including how the claim-check gate unifies with --fail-on, is in Output formats & exit codes. upgrade has its own codes (0 ok/no-op · 2 usage/platform · 20 network · 21 checksum · 22 permissions · 23 replacement failed).
Environment variables
| Variable | Effect |
|---|---|
SHIPMOOR_OFFLINE=1 | Kill switch: disables the registry lookup, BYO-Judge, and telemetry recording |
SHIPMOOR_LICENSE_TOKEN / SHIPMOOR_LICENSE_FILE | License for CI / non-interactive machines |
SHIPMOOR_INTENT_DRIFT_STAGE3=1 | Opt in to BYO-Judge |
SHIPMOOR_AUTHOR_MODEL_ID | Same as --author-model-id |
SHIPMOOR_VERSION / SHIPMOOR_CHANNEL / SHIPMOOR_INSTALL_DIR | Installer controls (pin, staging, custom path) |
NO_COLOR | Suppress color |
Next
- Configuration:
.shipmoor.yaml, the harnessmode/watchkeys, and the policy files. - Output contracts & schemas: what
--jsonand the harness report emit.