Command reference

A script generates this page from the CLI's own command definition. Because of this, the page describes the version that you can install, not the version that someone last described by hand. ship --help uses the same definition.

Commands

• delegate plan: Hand over a plan you already wrote.
• delegate pr: Hand over work you already built.
• instruct: Tell an active or finished mission what to change.
• status: Read a mission's current state.
• init: Write the ship-delegate skill into this repository.
• sandbox list: List your organization's custom sandboxes.
• sandbox starters: List the starter definitions to create a sandbox from.
• sandbox capacity: Show how many agents your missions run at once, compared with your limit, and which missions wait.
• sandbox create: Create a sandbox from a Dockerfile or a starter, and build it.
• sandbox update: Change a sandbox. A new definition or size is a new version.
• sandbox build: Build the active version now.
• sandbox logs: Print a build's log.
• sandbox versions: List a sandbox's versions, newest first.
• sandbox rollback: Make an earlier version the active one.
• sandbox default: Set the sandbox a project's agents run on.
• sandbox delete: Delete a sandbox.
• sandbox registry: Manage private package registries your sandboxes install from.
• mcp list: List the MCP servers a project's repository declares, and each binding.
• mcp bindings: List every MCP binding in your organization's projects.
• mcp bind: Bind a declared server, or change its binding.
• mcp tools: Show a server's tools, refresh the list, or set which ones agents may call.
• mcp connect: Start the sign-in for a remote server that uses OAuth.
• mcp remove: Remove a binding and its stored credential.
• mcp file: Set the repository file that declares the project's MCP servers.

delegate plan

ship delegate plan [<ISSUE>] --file <spec.md> [options]

SHIP skips the Planner and builds from your spec. If you give <ISSUE>, SHIP attaches the plan to that issue. If you give --title and no <ISSUE>, SHIP creates the issue for you and starts the mission 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

delegate pr

ship delegate pr [<ISSUE>] [--pr <N>] [--at reviewer|qa] [options]

SHIP reviews the work, tests it and makes the pull request ready to merge. Open the pull request first. If the gh CLI is available, the command gets the --pr value from the current branch. If you do not give an <ISSUE>, SHIP creates the mission and names it after the pull request. You do not need an issue 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

instruct

ship instruct <ISSUE> -m <text> | --file <path> [--note]

The instruction goes to the agents and starts the Builder on the mission's open pull request. Use this command, not a re-run of the mission. A re-run checks the unchanged pull request against its cached verdicts again 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

status

ship status <ISSUE> [--project <id>]

The command prints the mission's stage, its review state, its test state and its pull request. Use --json when you pipe the output to another command.

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

init

ship init [--force]

The command writes .claude/skills/ship-delegate/SKILL.md with the installed version stamped in it. A local coding agent then loads the skill without a fetch, and can tell when the skill is older than the CLI. With --force, the command replaces a stale or edited copy.

ship init
ship init --force

sandbox list

ship sandbox list

A sandbox adds extra steps to the platform base, for the runtimes and tools that your agents need. The list shows each sandbox with its active version, its size and whether its latest build is ready.

ship sandbox list
ship sandbox list --json

sandbox starters

ship sandbox starters

There are starters for Python, Java, Go, Rust and Ruby. Each starter has a size that fits it.

ship sandbox starters

sandbox capacity

ship sandbox capacity

Your organization can run as many agents at the same time as its plan allows. If a new agent would go over that number, its mission waits until one of your agents finishes. A mission can also wait when all agent slots on the platform are in use. The numbers come from the platform's capacity check, which runs every minute.

ship sandbox capacity
ship sandbox capacity --json

sandbox create

ship sandbox create --name <text> --file <path> | --starter <id>

The Dockerfile holds steps only: RUN, ENV, ARG and WORKDIR. The platform supplies the base, so the file has no FROM. There is also no build context to COPY from. The first build starts immediately. With --wait, the command streams the build log. If the build fails, the command exits 7 with the reason.

ship sandbox create --name python-uv --starter python --wait
ship sandbox create --name ml --file ml.Dockerfile --size 2x8192x16000

sandbox update

ship sandbox update <SANDBOX> [--file <path>] [--size <size>] [--wait]

A changed definition or size becomes the next version, and SHIP makes that version active and builds it. A mission that starts before the build finishes waits for it. If the build fails, that mission stops with the reason for the failure. A rename alone does not start a build. <SANDBOX> is an id or a name.

ship sandbox update python-uv --file sandbox.Dockerfile --wait
ship sandbox update sbt_1a2b --size standard-4

sandbox build

ship sandbox build <SANDBOX> [--wait]

If a build is already in progress, the command returns that build. Builds also run automatically when the platform base changes, and before an idle snapshot reaches its 30-day retention.

ship sandbox build python-uv --wait

sandbox logs

ship sandbox logs <SANDBOX> [--build <id>] [--follow]

The command prints the log of the latest build, unless --build names a different build. With --follow, the command streams the log until the build finishes.

ship sandbox logs python-uv --follow
ship sandbox logs sbt_1a2b --build tbd_9f8e

sandbox versions

ship sandbox versions <SANDBOX>

You cannot change a version. Missions start from the active version.

ship sandbox versions python-uv

sandbox rollback

ship sandbox rollback <SANDBOX> --to <N> [--wait]

If the snapshot of that version still exists, the rollback is instant. If not, SHIP builds the version again, and missions that start during the rebuild wait for it.

ship sandbox rollback python-uv --to 2

sandbox default

ship sandbox default <SANDBOX> | none [--project <id>]

This command sets the project default. Three settings have priority over it: agents.<role>.sandbox in ship.yml, a .ship/sandbox.Dockerfile in the repository and a mission's --sandbox. The value none returns the project to the platform base.

ship sandbox default python-uv --project prj_123
ship sandbox default none

sandbox delete

ship sandbox delete <SANDBOX>

SHIP refuses to delete a sandbox while a project uses it as its default. If a ship.yml entry still names the sandbox, the dispatch for that role fails, and the error names the sandbox. Change that entry before you delete the sandbox.

ship sandbox delete python-uv

sandbox registry

ship sandbox registry list | set --host <host> ... | remove <ID|HOST>

SHIP adds the credential to requests for that host when the requests leave the sandbox. Because of this, the credential never enters the sandbox, its build log or its snapshot. The command reads secrets from files, so they stay out of your shell history. Use a bearer token (--token-file) or a username and password (--username, --password-file).

ship sandbox registry set --host npm.pkg.github.com --token-file gh.txt
ship sandbox registry set --host acme.io --username ci --password-file pw
ship sandbox registry list
ship sandbox registry remove npm.pkg.github.com

mcp list

ship mcp list [--project <id>]

The servers come from the repository's own MCP file. That file is .mcp.json, unless ship.yml or the project names a different file. A binding sets which agents may use a server, which of its tools they may call, and the credential that the gateway attaches. The command never shows credential values. It shows only the names of the fields that are set.

ship mcp list --project prj_123
ship mcp list --json

mcp bindings

ship mcp bindings

The command prints one line for each binding, with its project, server, status, roles and authentication method. Run it to find the bindings that use a credential.

ship mcp bindings
ship mcp bindings --json

mcp bind

ship mcp bind <SERVER> --roles <list> [options]

--roles lists every agent that may use the server, and without --transport or --url the binding keeps its current server. Reviewer and QA get only read-only tools, and cannot use a server that runs inside the sandbox. Pass credentials as files, so they stay out of your shell history. Use --header-file for a remote server, or --env-var-file with --allow-host for an isolated one, which implies --transport isolate. Without a credential flag the stored credential stays, and --no-credential removes it. Approve tools afterwards with ship mcp tools.

ship mcp bind github --roles planner,qa --header-file Authorization=gh.txt
ship mcp bind sentry --roles qa --env-var-file KEY=t --allow-host sentry.io
ship mcp bind linear --roles planner,builder --no-credential
ship mcp bind github --roles planner,builder

mcp tools

ship mcp tools <SERVER> [--refresh] [--approve <list>] [--attest <list>]

Without flags, the command prints the server's last tool list. For each tool, the list shows its approval and whether it only reads. With --refresh, the command first asks the server for its current list. With --approve, the tools that you name replace the approved set. A tool without a server annotation goes to the reviewer and qa roles only if you also confirm with --attest that it only reads.

ship mcp tools github --refresh
ship mcp tools github --approve get_issue,get_file --attest get_file

mcp connect

ship mcp connect <SERVER> [--project <id>]

The command prints a link. Open it in a browser where you are signed in to the console. The provider then sends you back to the console, which stores the credential. You can use the link one time only, and it expires.

ship mcp connect linear --project prj_123

mcp remove

ship mcp remove <SERVER> [--project <id>]

From their next run, agents no longer get the server. The command does not change the repository's MCP file.

ship mcp remove notion --project prj_123

mcp file

ship mcp file <PATH> | default [--project <id>]

<PATH> is that file, for example .cursor/mcp.json or .vscode/mcp.json. The value default sets the file back to .mcp.json. SHIP refuses the command while the repository's ship.yml sets mcp.config, because that setting has priority.

ship mcp file .cursor/mcp.json --project prj_123
ship mcp file default

Environment

Exit codes

Each result has its own exit code, so a script can branch on the code.