Command reference
Every ship command, every flag, generated from the CLI's own definition.
This page is generated from the CLI's own command definition, so it describes the version you can
install rather than the version someone last wrote prose about. ship --help renders from the same
source.
Commands
delegate plan: Hand over a plan you already wrote.delegate pr: Hand over work you already built.instruct: Tell a running or finished mission what to change.status: Read a mission's current state.init: Write the ship-delegate skill into this repository.
delegate plan
ship delegate plan [<ISSUE>] --file <spec.md> [options]The platform skips its own planning and builds straight from your spec. With <ISSUE> the plan is attached to that existing issue. With --title and no <ISSUE>, the issue is created for you and the run starts on it.
ship delegate plan SHIP-412 --file docs/spec.md
ship delegate plan --title "Rate-limit search" --file docs/spec.md
ship delegate plan SHIP-412 --file docs/spec.md --harness codex| Flag | What it does |
|---|---|
--file <path> | Plan/spec markdown to hand over, or the instruction body. |
--file-plan <path> | JSON array of {path, action, description} naming the files the plan expects to touch. Without it the builder chooses for itself. |
--title <text> | Name the mission created for you. Required with no <ISSUE> for delegate plan; optional for delegate pr, which takes the pull request's own title when you omit it. |
--description <text> | Issue body used with --title. |
--harness <id> | Run THIS mission on a specific harness, overriding ship.yml. Applies to the role the mission enters at: the builder for delegate plan, the reviewer or QA agent for delegate pr. One of claude-code, codex, pi, kilo-code, open-code. |
--model <id> | Same, for the model. Usable with or without --harness. |
--prompt-file <path> | Extra instructions for that same role, read from a local file. Never committed to the repository. The instructions apply to this mission only. |
--prompt-path <path> | Same, but naming a file already in the repository. |
--prompt-ref <ref> | Git ref to read --prompt-path at. Defaults to the branch the mission is based on. |
--prompt-mode <mode> | replace (default) or extend, against the repo's own role prompt. replace uses your instructions INSTEAD of the repository's .ship/agents/<role>.md; extend appends them after it, keeping the repository's conventions. |
--project <id> | Project id. Required unless SHIP_PROJECT_ID is set. |
--json | Print the raw API response instead of a human summary. |
delegate pr
ship delegate pr [<ISSUE>] [--pr <N>] [--at reviewer|qa] [options]The platform reviews, tests, and drives it to merge. Open the pull request first; --pr is auto-detected from the current branch when the gh CLI is available. Without an <ISSUE> the mission is created for you and named after the pull request, so you do not need a ticket to hand over a branch.
ship delegate pr
ship delegate pr SHIP-412 --pr 418 --at qa
ship delegate pr --at qa --model claude-opus-5| Flag | What it does |
|---|---|
--title <text> | Name the mission created for you. Required with no <ISSUE> for delegate plan; optional for delegate pr, which takes the pull request's own title when you omit it. |
--description <text> | Issue body used with --title. |
--pr <number> | Pull request to hand over. |
--at <stage> | reviewer (default) or qa. |
--harness <id> | Run THIS mission on a specific harness, overriding ship.yml. Applies to the role the mission enters at: the builder for delegate plan, the reviewer or QA agent for delegate pr. One of claude-code, codex, pi, kilo-code, open-code. |
--model <id> | Same, for the model. Usable with or without --harness. |
--prompt-file <path> | Extra instructions for that same role, read from a local file. Never committed to the repository. The instructions apply to this mission only. |
--prompt-path <path> | Same, but naming a file already in the repository. |
--prompt-ref <ref> | Git ref to read --prompt-path at. Defaults to the branch the mission is based on. |
--prompt-mode <mode> | replace (default) or extend, against the repo's own role prompt. replace uses your instructions INSTEAD of the repository's .ship/agents/<role>.md; extend appends them after it, keeping the repository's conventions. |
--project <id> | Project id. Required unless SHIP_PROJECT_ID is set. |
--json | Print the raw API response instead of a human summary. |
instruct
ship instruct <ISSUE> -m <text> | --file <path> [--note]The instruction reaches the agents and dispatches the builder against the mission's open pull request. Use this rather than re-running a mission: a re-run re-checks an unchanged pull request against its cached verdicts and does nothing.
ship instruct SHIP-412 -m "Override nopt instead of narrowing Node support"
ship instruct SHIP-412 --file review-notes.md
ship instruct SHIP-412 -m "FYI the staging box is down" --note| Flag | What it does |
|---|---|
-m, --message <text> | The instruction text. |
--note | Record context without dispatching the builder. Use it for background a later agent should have; use the default for anything you want acted on. |
--file <path> | Plan/spec markdown to hand over, or the instruction body. |
--json | Print the raw API response instead of a human summary. |
status
ship status <ISSUE> [--project <id>]Prints the mission's stage, review and test state, and pull request. --json for piping.
ship status SHIP-412
ship status SHIP-412 --json| Flag | What it does |
|---|---|
--project <id> | Project id. Required unless SHIP_PROJECT_ID is set. |
--json | Print the raw API response instead of a human summary. |
init
ship init [--force]Writes .claude/skills/ship-delegate/SKILL.md stamped with the installed version, so a local coding agent loads it without a fetch and can tell when it has fallen behind the CLI. --force replaces a stale or edited copy.
ship init
ship init --force| Flag | What it does |
|---|---|
--force | Replace a stale or edited skill copy. |
Environment
| Variable | Required | Purpose |
|---|---|---|
SHIP_API_TOKEN | Yes | Personal access token. Create one at <console>/settings/tokens. |
SHIP_API_BASE_URL | No | Override the API base URL. |
SHIP_PROJECT_ID | No | Default for --project. |
Exit codes
Distinct so scripts can branch on them.
| Code | Name | Meaning |
|---|---|---|
| 0 | ok | Success. |
| 1 | runtime | Unexpected runtime error. |
| 2 | usage | Bad arguments. The message names the problem. |
| 3 | forbidden | Missing token, or a token without the scope the route needs. |
| 4 | not found | No such mission or project. |
| 5 | precondition | The action needs something that is not true yet (e.g. a review hand-off with no pull request). |
| 6 | unavailable | The platform needs onboarding finished. |
How is this page?