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 agent team 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 agent team 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 agent team 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 opus

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

Choose the role

The instructions go to the role that the mission starts at. To give them to a different role, add --prompt-role with planner, builder, reviewer or qa. The flags also work on ship mission create and ship mission start, which start a full mission at the Planner:

# The Planner of a full mission
ship mission start SHIP-412 --prompt-file plan-notes.md

# The QA agent of a pull request hand-off, not the Reviewer
ship delegate pr SHIP-412 --prompt-role qa --prompt-file qa-notes.md

ship delegate plan and ship delegate pr skip the Planner, so they refuse --prompt-role planner. A restart of a mission that has an open pull request also skips the Planner: SHIP continues from the pull request. So name the role with --prompt-role.

A start with prompt flags replaces the override that the mission has, for example a base branch that an earlier PUT /v1/missions/{issueId}/agents-override set.

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.

The status lists the agent runs of the mission with their ids, and the run whose artifacts are the proof of the work. To see all your missions, run ship mission list.

Control a mission

ship mission pause SHIP-412
ship mission resume SHIP-412
ship mission stop SHIP-412
ship mission merge SHIP-412

A pause holds the mission before its next stage. When a checkpoint holds a mission, resume approves the result of that stage. A stop ends every agent of the mission and keeps the pull request open. ship mission start starts it again. When a mission stops at its credit limit, ship mission approve-ceiling lets it continue.

Change one mission

ship mission override set SHIP-412 --role reviewer --harness codex
ship mission override get SHIP-412
ship mission auto-merge SHIP-412 on
ship mission archive SHIP-412

An override changes the harness, the model or another setting of one role for one mission, and ship.yml does not change. The next run of that role uses it. With auto-merge on, SHIP merges the pull request when the checks, the review and the test pass. An archived mission is not on the board. The command ship mission disposition records why a mission ended, for the delivery statistics.

Read what an agent did

ship run list --mission SHIP-412
ship run get builder-ship-412-3f9c41aa-coding-1
ship run logs builder-ship-412-3f9c41aa-coding-1 --part system
ship run watch builder-ship-412-3f9c41aa-coding-1

A run is one agent in its own sandbox. The get command gives the status, the resource use and the cost of a run. The logs command prints the event stream of the agent, the output of the sandbox or the prompt text from your repository. The watch command prints each event of an active run as the agent emits it, and stops when the run ends.

Run a mission on a schedule

ship schedule create --name deps --template dependency-upgrades
ship schedule runs aut_123

At each run, SHIP files an issue from the prompt of the task, and a normal mission starts on it. While the mission of the last run is open, SHIP skips the next run.

Credits, tokens and projects

ship credits ledger
ship credits offers
ship credits request -m "Two more missions this week"
ship token list
ship project update prj_123 --status paused

The ledger shows where the credits went. The command ship credits buy prints the address of a payment page, and ship credits plan changes the monthly plan. The command ship token revoke revokes one of your tokens at once. You create tokens in the console, because a token cannot create a token.

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.