Overview ~ SHIP

Send work to the agent fleet from your terminal. Install the CLI, authenticate and choose the correct hand-off.

What the CLI is for

ship sends work to the fleet from a terminal, a script or a coding agent in your repository. It uses the same API as the console. Work that you start with the CLI shows on the board, with the same evidence as work from the console.

Two hand-offs cover most uses of the CLI:

You have	Command	What the fleet does
A plan or spec you already wrote	`ship delegate plan`	Skips the Planner and builds from your spec
A branch you already pushed	`ship delegate pr`	Reviews it, tests it and makes it ready for you to merge

The instruct and status commands are for missions that are already in progress. The ship sandbox command sets up the environment that agents run in. Commands tells how each command works. Capabilities shows what people use the commands for. The Command reference lists every flag.

Install

Point your coding agent at it

If you use a coding agent, give it the skill document. The agent then installs and configures the CLI itself:

set up https://letsship.ai/SKILL.md

This is the same document that ship init writes into your repository. Both copies come from the same source, so the hosted copy does not differ from the installed copy. The agent reads the document and installs the CLI. Then it writes a local copy at .claude/skills/ship-delegate/SKILL.md and asks you for a token.

Coding agents shows this setup with Claude Code and Codex.

Install it yourself

npm install -g @lets-ship/cli
ship --version

Then write the local copy of the skill, so that later agent sessions can load it without a fetch:

ship init          # --force replaces a stale or edited copy

Authenticate

ship needs a personal access token. Create a token in the console under Settings → API tokens. Then export it:

export SHIP_API_TOKEN=pat_...

Each token has scopes, and the API checks the scopes on each route. The commands in this section need these scopes:

Scope	Covers
`missions:run`	`delegate plan`, `delegate pr`
`missions:read`	`ship status`
`missions:write`	`ship instruct`
`agents:read`	`ship sandbox list`, `starters`, `versions`, `logs`
`sandboxes:read`	`ship sandbox capacity`
`agents:write`	`ship sandbox create`, `update`, `build`, `rollback`, `delete`
`projects:admin`	`ship sandbox default`
`connectors:read`, `connectors:write`	`ship sandbox registry list`, and `set` / `remove`

If a token does not have a scope, the command fails with exit code 3 and names the scope. This error is not temporary, so another try does not fix it. When you create a token, you can also bind it to one project. This is a good idea for a token that an agent will hold.

Which project

ship finds the project from your git remote. If the remote matches no project or more than one project, ship tells you. Then pass --project <id> or export SHIP_PROJECT_ID.

Which platform

ship sends its requests to https://api.letsship.ai/v1, unless SHIP_API_BASE_URL sets a different URL. Set this variable for a staging or self-hosted installation. The CLI also uses it for the console links that it prints, so the links go to the same platform as your commands.

Overview