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 skills into this repository.
• mission list: List missions, with what each one does now.
• mission create: File a new issue and start a full mission on it.
• mission start: Start a full mission on an issue, or start a stopped mission again.
• mission pause: Hold a mission before its next stage.
• mission resume: Continue a paused mission, or approve the stage that a checkpoint holds.
• mission stop: Stop a mission and every agent that runs for it.
• mission approve-ceiling: Let a mission that stopped at its credit limit continue.
• mission merge: Merge the pull request of a mission.
• mission decline: Close the pull request of a mission without a merge.
• mission inspect: Print the full record of a mission, to find why it failed.
• mission override: Read, set or clear the agents override of one mission.
• mission auto-merge: Turn auto-merge on or off for one mission.
• mission archive: Hide a mission from the board and from ship mission list.
• mission unarchive: Show an archived mission on the board again.
• mission disposition: Record why a mission ended, for the delivery statistics.
• run list: List agent runs, newest first.
• run get: Read one run: its status, resources, sessions and cost.
• run logs: Print a run's log.
• run watch: Follow a run live until it ends.
• run stop: Stop one agent run before it finishes.
• whoami: Show who the token is, its role and its scopes.
• credits: Show the credit balance, and whether a new mission can start.
• setup: Show what the organization set up so far, and the next step.
• setup mark: Mark a step of the setup checklist as completed or skipped.
• setup mark-group: Mark all the open steps of a setup group.
• project list: List the projects that the token can reach, with their ids.
• project get: Read one project: its repository, tracker and settings.
• project update: Change the settings of a project.
• preview list: List the preview environments that SHIP deployed for pull requests.
• preview get: Read one preview environment.
• preview destroy: Remove a preview environment before it expires.
• artifact list: List the proof that agent runs produced: traces, screenshots, videos and logs.
• artifact get: Read one artifact, with a link that opens it.
• notice list: List what needs attention in the organization.
• notice dismiss: Close a warning notice for yourself.
• credits ledger: List where the credits of the organization went, newest first.
• credits offers: List the credit packs, the monthly plans and Enterprise, with their prices.
• credits buy: Open a payment page for a credit pack, a monthly plan or credits on a plan.
• credits plan: Change the monthly plan, or cancel it at the end of the month.
• credits request: Ask for more credits, and say what they are for.
• token list: List your API tokens, with their scopes and when each one expires.
• token revoke: Revoke one of your API tokens at once.
• schedule list: List the scheduled tasks of your projects.
• schedule templates: List the templates to start a scheduled task from.
• schedule get: Read one scheduled task, with its prompt.
• schedule create: Add a mission that runs on a schedule.
• schedule update: Change a scheduled task, or turn it off and on.
• schedule run: Run a scheduled task now.
• schedule runs: List the past runs of a scheduled task, with their missions and cost.
• schedule delete: Delete a scheduled task and its run history.
• 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.
• connect jira: Connect a Jira site to the organization of your token, with the code from the SHIP app in Jira.

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 opus
ship delegate pr --pr 418 --prompt-role qa --prompt-file qa.md

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. It also lists the agent runs of the mission, each with the id that the ship run commands take. The proof line names the run whose artifacts prove the work. 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 one skill for each SHIP capability to .claude/skills/<name>/SKILL.md, and stamps the installed version in each. A local coding agent then loads the skills without a fetch, and can tell when a skill is older than the CLI. If a copy already exists, the command writes nothing and names the file. With --force, the command replaces every copy, and edits to the copies are lost.

ship init
ship init --force

mission list

ship mission list [--activity <activity>] [--search <text>] [--project <id>]

The list shows each mission with its activity, its stage and its pull request. Archived missions are not in the list. The --activity flag takes the values of the status filter in the console, for example queued, ready_to_merge, needs_attention, paused or merged.

ship mission list
ship mission list --activity needs_attention
ship mission list --search "rate limit" --json

mission create

ship mission create --title <text> [options]

SHIP creates the issue in the tracker of the project and starts the mission at the Planner. Write the acceptance criteria as checkboxes in --description, because the Planner reads them and the QA agent tests against them. To start from a plan that you wrote, use ship delegate plan. The prompt flags give one role instructions for this mission.

ship mission create --title "Rate-limit the search endpoint"
ship mission create --title "Fix login" --description "- [ ] Login works"
ship mission create --title "Fix login" --prompt-file notes.md

mission start

ship mission start <ISSUE> [--project <id>] [options]

The mission starts at the Planner. Use the command for an issue that is already in your tracker, or to restart a mission that stopped, failed or needs attention. To give an active mission new information, use ship instruct. A restart of a mission with no changes does nothing. The prompt flags give one role instructions for this mission. A restart of a mission with an open pull request skips the Planner, so name the role with --prompt-role.

ship mission start SHIP-412 --project prj_123
ship mission start SHIP-412 --prompt-file notes.md --prompt-mode extend

mission pause

ship mission pause <ISSUE>

The stage that runs now finishes, and the next stage waits until you resume the mission. A pause starts no new agent and stops no agent.

ship mission pause SHIP-412

mission resume

ship mission resume <ISSUE>

A checkpoint in ship.yml pauses a mission after a stage, so that a person can read the result first. Then ship status shows paused (checkpoint:<role>). Resume the mission to approve that result and start the next stage. To ask for changes to the result instead, use ship instruct.

ship mission resume SHIP-412

mission stop

ship mission stop <ISSUE>

The agents stop, and their work in progress is lost. The pull request stays open. Start the mission again with ship mission start.

ship mission stop SHIP-412

mission approve-ceiling

ship mission approve-ceiling <ISSUE> [--project <id>]

Each mission can use a fixed number of credits. At that limit, the mission pauses until a member lets it continue. This command raises the limit of the mission by one step and runs the stage again. The token needs the missions:run scope. Without --project or SHIP_PROJECT_ID, the command reads the project from the mission, and the token also needs missions:read.

ship mission approve-ceiling SHIP-412

mission merge

ship mission merge <ISSUE>

SHIP merges the pull request with the merge method of the repository. Then the mission becomes done. If the branch of the pull request is only behind its base branch, SHIP updates the branch first, then merges it once the checks pass. The command exits 0 for that case too.

If the pull request cannot merge for another reason, the command exits 5 with the reason. On a merge conflict, SHIP also starts the Builder to fix the conflict, and merges the pull request when the mission is ready again. Do not run the command again for that.

ship mission merge SHIP-412

mission decline

ship mission decline <ISSUE>

SHIP closes the pull request, and the mission becomes declined. You cannot undo this command.

ship mission decline SHIP-412

mission inspect

ship mission inspect <ISSUE> [--sections <list>] [--project <id>]

The record holds a section for each source of data. Examples are the task state, the reason for a retry, the latest review and test results, and the configuration of each attempt. The token needs the inspect:read scope.

ship mission inspect SHIP-412
ship mission inspect SHIP-412 --sections taskState,retryReason

mission override

ship mission override get|set|clear <ISSUE> [--role <role>] [settings]

An override changes the harness, the model or another setting of a role for one mission, and ship.yml does not change. The action set changes the role that --role names and keeps the other roles and fields. The flag --unset removes stored fields, for example the model when you change the harness, and clear removes the whole override. The next run of a role uses the override. Without --project, the command reads the project from the mission. SHIP_PROJECT_ID does not apply here, because an override saved for the wrong project changes no run.

ship mission override get SHIP-412
ship mission override set SHIP-412 --role reviewer --harness codex
ship mission override set SHIP-412 --role builder --checkpoint on
ship mission override clear SHIP-412

mission auto-merge

ship mission auto-merge <ISSUE> on|off

With auto-merge on, SHIP merges the pull request of the mission when the checks, the review and the test pass, and no person merges it. For this mission, the setting replaces the auto-merge of the project. ship project get shows the auto-merge of the project.

ship mission auto-merge SHIP-412 on
ship mission auto-merge SHIP-412 off

mission archive

ship mission archive <ISSUE>

Archive a mission that ended, to keep the board clean. Nothing else changes, and ship mission unarchive shows the mission again. Only an owner or an admin can archive a mission.

ship mission archive SHIP-412

mission unarchive

ship mission unarchive <ISSUE>

Only an owner or an admin can unarchive a mission.

ship mission unarchive SHIP-412

mission disposition

ship mission disposition <ISSUE> <value> [--superseded-by <ISSUE>]

The value is product, probe, superseded, takeover or none. A product mission is real work, judged on its merits, and a probe is a test on purpose. With superseded, another mission replaced this one: give that mission with --superseded-by. With takeover, a person finished the work outside SHIP, and none clears the value. Record what a person decided, never a guess. Only an owner or an admin can set the disposition.

ship mission disposition SHIP-412 probe
ship mission disposition SHIP-412 superseded --superseded-by SHIP-420

run list

ship run list [--mission <ISSUE>] [--role <role>] [--status <status>]

Each run is one agent in its own sandbox. The list shows the id of each run, its mission, its role, its status and its harness. The filters apply before --limit, so the list holds up to --limit runs that match. When more runs match, the last line gives the --cursor for the next page. The statuses are given under --status.

ship run list --mission SHIP-412
ship run list --status running
ship run list --mission SHIP-412 --role qa --json

run get

ship run get <SANDBOX_ID>

The command prints the mission and role of the run, its status, and the reason when a run ended early. It also prints the harness, the size, the start and end time, and the latest CPU, memory and disk use. The session line is the run's own session, with its outcome and cost. Sessions of other runs of the same role are on their own line, and their cost is not part of this run's cost.

ship run get builder-ship-412-3f9c41aa-coding-1
ship run get qa-ship-412-77d0e2c1-qa-1 --json

run logs

ship run logs <SANDBOX_ID> [--part session|system|prompt] [--session <id>]

The session part is the event stream of the agent, one JSON event on each line: its thoughts, its tool calls and their results. The system part is the output of the sandbox: the clone, the dependency install, the checks before a push, and git. The prompt part is the text that your repository added to the prompt of the agent. The command reads the session of the run itself, unless --session names another one. The platform saves a log when the agent ends, so an active run has no log yet.

ship run logs builder-ship-412-3f9c41aa-coding-1
ship run logs builder-ship-412-3f9c41aa-coding-1 --part system
ship run logs qa-ship-412-77d0e2c1-qa-1 --json | jq -r .content

run watch

ship run watch <SANDBOX_ID> [--max-seconds <n>] [--since <id>]

The command prints the last events of the agent. Then it prints each new event on one line as the agent emits it, for example a thought, a tool call or an error. It also prints a line when the mission moves to another stage. When the run ends, the command exits 0 if the run completed, and 7 if it ended in another way, for example failed or stopped. With --max-seconds, the command stops after that time and exits 5 if the run is still active, and its message gives the --since value to continue from. With --json, each event is one JSON object on its own line.

ship run watch builder-ship-412-3f9c41aa-coding-1
ship run watch qa-ship-412-77d0e2c1-qa-1 --max-seconds 300
ship run watch builder-ship-412-3f9c41aa-coding-1 --json | jq -c .data

run stop

ship run stop <SANDBOX_ID>

The command stops the agent in the sandbox that <SANDBOX_ID> names. The agent's work in progress is lost, and the status of the run becomes stopped a few seconds later. The command stops one run, not the mission. ship run list gives the id of each run. The console shows it in the Sandbox ID field of the run. The token needs the sandboxes:stop scope, and an org admin must own it.

ship run stop builder-ship-412-3f9c41aa-coding-1
ship run stop builder-ship-412-3f9c41aa-coding-1 --json

whoami

ship whoami

The command prints the user and organization behind SHIP_API_TOKEN, the role in that organization and the scopes of the token. It also prints the project that a project token is bound to. Run it first, to check a token.

ship whoami
ship whoami --json

credits

ship credits

The command prints the balance of the organization, the credit limit of each mission and the number of agents that your missions run at once. Read it before you start work, and when a mission waits for credits.

ship credits
ship credits --json

setup

ship setup

The command prints each step of the setup checklist, and whether it is done or skipped. For an open step, it also prints a link to its page. The checklist stays in the console until each step is done or skipped.

ship setup
ship setup --json

setup mark

ship setup mark <STEP> <completed|skipped|open>

Use it for a step that you did in a different way, or for a step that you do not want. The mark applies to your own checklist only. Use open to remove the mark. A step that SHIP saw done stays done. The output of ship setup --json gives the id of each step.

ship setup mark custom_sandbox skipped
ship setup mark agent_to_pr completed

setup mark-group

ship setup mark-group <GROUP> <completed|skipped|open>

The groups are first_mission, team and explore. The mark goes on each open step of the group, and a step that you marked before keeps its mark. Use open to remove the marks that you set in the group.

ship setup mark-group explore skipped
ship setup mark-group explore open

project list

ship project list

Each project connects one repository and one tracker. Give a project id to --project, or set SHIP_PROJECT_ID, for the commands that need one.

ship project list
ship project list --json

project get

ship project get <PROJECT_ID>

The command prints the repository, the tracker, the issue code, the default sandbox and auto-merge.

ship project get prj_123

project update

ship project update <PROJECT_ID> [--name <text>] [--status <status>] [...]

Only the settings that you give change. A paused or archived project starts no new missions, and active starts them again. With auto-merge on, SHIP merges a ready pull request with no person. The flags --repo, --linear-team and --jira-project connect the project to another repository, Linear team or Jira project, through the connections of your organization. To set the default sandbox, use ship sandbox default. Only an owner or an admin can change a project.

ship project update prj_123 --name web-app
ship project update prj_123 --status paused
ship project update prj_123 --auto-merge on
ship project update prj_123 --tracker linear --linear-team ENG

preview list

ship preview list [--mission <ISSUE>] [--project <id>]

SHIP deploys a preview of each pull request through the delivery pipeline of your repository, and the QA agent tests that preview. The list shows each preview with its mission, its pull request and its status.

ship preview list --mission SHIP-412

preview get

ship preview get <ENVIRONMENT_ID>

The command prints the status, the pull request and when the preview expires.

ship preview get env_123

preview destroy

ship preview destroy <ENVIRONMENT_ID>

The platform asks the delivery pipeline of your repository to remove the preview. A mission that tests against it then has no preview.

ship preview destroy env_123

artifact list

ship artifact list [--mission <ISSUE>] [--run <SANDBOX_ID>] [--project <id>]

The proof of a mission is the artifacts of its QA run that passed. ship status prints that run, so give its id to --run. Each artifact has a link that opens it, and a trace also has a link to the trace viewer.

ship artifact list --mission SHIP-412
ship artifact list --run qa-ship-412-77d0e2c1-qa-1

artifact get

ship artifact get <ARTIFACT_ID>

The command prints the kind of the artifact, the criterion that it proves, and its links.

ship artifact get art_123

notice list

ship notice list

A notice is, for example, a tracker to connect again or credits that run low. A critical notice stops work until someone fixes its cause. Each notice says what to do, and gives a link when you can do it.

ship notice list

notice dismiss

ship notice dismiss <NOTICE_ID>

You can close a warning, but not a critical notice. A critical notice stays until its cause is fixed.

ship notice dismiss credits_low:grant_123

credits ledger

ship credits ledger [--limit <n>] [--cursor <cursor>]

Each entry is a mission and the credits that it used, a grant, an adjustment or an expiry. When more entries exist, the last line gives the --cursor for the next page. Only an owner or an admin can read the ledger.

ship credits ledger
ship credits ledger --limit 100 --json

credits offers

ship credits offers

The prices are in US dollars. The list is the same as the pricing page. Each offer has the name that ship credits buy takes.

ship credits offers
ship credits offers --json

credits buy

ship credits buy <offer> [--plan starter|scale] [--quantity <n>] --start-now

The command prints the address of a payment page. Nothing is charged until you pay on that page, and SHIP adds the credits when the payment is confirmed. A monthly plan is the offer team with --plan. A workspace on a plan adds credits with the offer team_credits and --quantity. The purchase starts only with your consent to start the credits at once: without --start-now, the command shows the text of that consent and stops. Only an owner or an admin can buy.

ship credits buy credit_pack_50 --start-now
ship credits buy team --plan starter --start-now
ship credits buy team_credits --quantity 20 --start-now

credits plan

ship credits plan [starter|scale] [--cancel | --resume]

A new plan starts at the next renewal. SHIP charges and refunds nothing for the current month. With --cancel, the plan ends at the end of the month that you paid for, and --resume keeps it before then. The command prints the plan as it now stands. Only an owner or an admin can change the plan.

ship credits plan scale
ship credits plan --cancel
ship credits plan --resume

credits request

ship credits request -m <text> | --file <path>

Any member can ask. The answer says who has the request: SHIP, or the owners and admins of the organization. A second request while one is open joins the open request.

ship credits request -m "Two more missions for the release this week"

token list

ship token list

The list shows only the tokens that you created, never a secret. Other members cannot see your tokens, and you cannot see theirs. You create a token in the console, because a token cannot create a token.

ship token list
ship token list --json

token revoke

ship token revoke <TOKEN_ID>

Every call with the token fails after this command, and you cannot undo it. A script or a CI job that uses the token stops. If you revoke the token in SHIP_API_TOKEN, the next command fails too.

ship token revoke tok-pat-9b8e2a3f

schedule list

ship schedule list [--project <id>]

A scheduled task is a prompt with a cadence. At each run, SHIP files an issue with the prompt as its description, and a normal mission starts on it. The list shows each task with its cadence, its next run and whether it is on. --project lists the tasks of one project. A token for one project lists only the tasks of that project.

ship schedule list
ship schedule list --project prj_123 --json

schedule templates

ship schedule templates

Each template has a prepared prompt and a suggested cadence.

ship schedule templates

schedule get

ship schedule get <TASK_ID>

The command prints the cadence, the next and the last run, and the prompt of the task.

ship schedule get aut_123

schedule create

ship schedule create --name <text> --file <path> | --template <key> [schedule]

The schedule is --every daily, weekly or monthly, with --time and --timezone. A weekly task also needs --day with a weekday, and a monthly task --day with a day from 1 to 28. With --template, the task uses the prompt of the template, and its suggested schedule unless you give one. With --file too, the prompt of the file replaces the prompt of the template. Write the acceptance criteria in the prompt as checkboxes. While the mission of the last run is still open, SHIP skips the next run.

ship schedule create --name deps --template dependency-upgrades
ship schedule create --name flaky --file f.md --template flaky-test-sweep

schedule update

ship schedule update <TASK_ID> [options] [--enable | --disable]

Only the values that you give change. To change the schedule, give --every, --time and --timezone together, and --day when the interval needs it. --disable stops the runs and keeps the task and its history.

ship schedule update aut_123 --disable
ship schedule update aut_123 --every daily --time 07:30 --timezone UTC

schedule run

ship schedule run <TASK_ID>

The run starts a mission now, outside the schedule. It runs also when the mission of the last run is still open. The token needs the missions:run scope, because the run uses credits.

ship schedule run aut_123

schedule runs

ship schedule runs <TASK_ID> [--limit <n>] [--cursor <cursor>]

Each run shows its status and the mission that it started. A dispatched run filed its issue. The mission itself shows whether the work passed. When older runs exist, the last line gives the --cursor for the next page.

ship schedule runs aut_123
ship schedule runs aut_123 --json

schedule delete

ship schedule delete <TASK_ID>

Missions that the task already started continue. To stop new runs only, use ship schedule update --disable.

ship schedule delete aut_123

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

connect jira

ship connect jira <code>

A Jira admin opens Apps, then SHIP, in Jira and selects Connect to SHIP. The link that opens holds the code after code=. The code works once and expires 10 minutes after Jira made it. The command prints the Jira connection. Only an owner or an admin can connect a site, and a site connects to one organization.

ship connect jira Vb3n0r9cXbI7t1nK2wQ8aZ4yJm6LfH5sPdGe0uTqRkA

Environment

Exit codes

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