Commands

The Command reference lists every flag. This page tells you when to use each command, and why.

Hand over a plan

Write the plan to a file. Then delegate it:

# Against an issue that already exists
ship delegate plan SHIP-412 --file docs/plan.md

# No issue yet: create one and start in the same call
ship delegate plan --title "Rate-limit the search endpoint" --file docs/plan.md

The fleet skips the Planner and builds from your spec as you wrote it. It does not make a new plan from the issue. That is the purpose of this hand-off: you already made the decisions, and you want the fleet to implement them, not reconsider them.

If you know which files the plan will change, name them with --file-plan <path.json>. That file is a JSON array of {path, action, description}. Without it, the Builder decides which files to change.

Hand over a branch

Open the pull request yourself. SHIP opens no pull request for a branch that you hand over, and the Builder pushes only fixes to that branch. Then delegate the pull request. If the gh CLI is available, ship detects the pull request for --pr from the current branch.

ship delegate pr SHIP-412              # review, then test, then merge
ship delegate pr SHIP-412 --at qa      # already reviewed; just test it
ship delegate pr                       # no ticket: the mission is named after the PR

If CI fails on that pull request, the fleet fixes the failure before the review. This is the normal behavior and is not an error.

Pin the harness or model

The --harness and --model flags change how this mission runs, and they do not change your ship.yml. They apply to the role that you delegate to. For delegate plan, that role is the Builder. For delegate pr, it is the Reviewer, or the QA agent with --at qa.

ship delegate plan SHIP-412 --file docs/plan.md --harness codex
ship delegate pr SHIP-412 --at qa --model claude-opus-5

Use these flags to get a specific agent or model, or to compare two of them on the same work. Otherwise, do not use them, because the project's configuration is the setting that your team already agreed on.

Pin the sandbox

The --sandbox flag runs the role that you delegate to on one of your custom sandboxes, for this mission only. Identify the sandbox by its name or its id. The --size flag changes the size of that sandbox.

ship delegate pr SHIP-412 --at qa --sandbox python-uv
ship delegate plan SHIP-412 --file docs/plan.md --sandbox ml --size 2x8192x16000

Both flags take priority over ship.yml, the repository's .ship/sandbox.Dockerfile and the project default. Use them to try a sandbox on one mission before you make it the project's sandbox.

Give one role extra instructions

Sometimes one mission needs instructions that the repository does not have. For example, this change needs a security review, or the agents must follow a rule that you just decided on. The --prompt-file flag sends instructions from a local file to the role that you delegate to, for this mission only. The instructions do not go into the repository.

ship delegate pr SHIP-412 --prompt-file security-review.md

If the instructions are already in the repository, use --prompt-path instead. You can also give a specific ref:

ship delegate pr SHIP-412 --prompt-path .ship/lanes/security.md
ship delegate pr SHIP-412 --prompt-path .ship/lanes/security.md --prompt-ref main

Replace or extend

If your repository already has a .ship/agents/<role>.md file (see Agent prompts), --prompt-mode sets what happens to that file:

# Just this lane, ignoring the repo's reviewer conventions
ship delegate pr SHIP-412 --prompt-file security-review.md

# The repo's conventions, plus this lane on top
ship delegate pr SHIP-412 --prompt-file security-review.md --prompt-mode extend

extend is usually the better choice when you want to keep the repository's conventions and add emphasis, not a new way to work. Use replace when the mission is a different job, because a security audit reads a diff differently from a normal review.

In both modes, SHIP's own charter for that role still applies. Neither mode can disable the charter, because both modes add instructions after it.

SHIP records the two layers separately. The mission's Prompt tab shows the repository's file and your override as separate blocks, so you can see what the agent read. Cost and outcome comparisons treat "repo layer only", "override only" and "both" as different configurations. They do not average across them.

Steer a running mission

If you make a decision about work that you already delegated, send it as an instruction. The decision can be an answer to a question, review comments for the agents or a correction to a choice. The instruction goes to the agents and starts the Builder again on the open pull request of the mission.

ship instruct SHIP-412 -m "Keep the current Node range, override nopt instead"
ship instruct SHIP-412 --file review-notes.md
ship instruct SHIP-412 -m "FYI staging is down until 14:00" --note

The --note flag records context for the next agent that runs. It does not start any work.

Send an instruction. Do not re-run the mission. A re-run checks the unchanged pull request again against the verdicts that it already has. It finds that nothing changed and correctly does nothing. That looks like a success, but the agents never get your feedback.

Check on it

ship status SHIP-412
ship status SHIP-412 --json

Every command accepts --json for machine-readable output. Each command also exits with a distinct code, so a script can branch on the result.

Set up a sandbox

The ship sandbox command manages the custom sandboxes that agents run in, without the console. With --wait, a build streams its log. If the build fails, the command exits with 7 and gives the reason, so a script can use it:

ship sandbox create --name python-uv --starter python --wait
ship sandbox default python-uv --project prj_123

After that, you can change the sandbox and roll it back to an earlier version:

ship sandbox update python-uv --file sandbox.Dockerfile --wait
ship sandbox versions python-uv
ship sandbox rollback python-uv --to 1

The ship sandbox registry set command reads the token of a private package registry from a file, so the token is never in your shell history:

ship sandbox registry set --host npm.pkg.github.com --token-file gh-packages.txt

Custom sandboxes explains what a definition can contain and how the platform selects a sandbox for each role.