Overview
Send work to the SHIP agent team from your terminal. Install the CLI, authenticate and choose the correct hand-off.
What the CLI is for
ship sends work to the SHIP agent team 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 agent team 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 mission commands list missions and control them, and ship run reads the agent runs of a mission and their logs. The ship schedule commands run missions on a schedule, and ship sandbox 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.mdThe document is a setup skill. The agent reads it and installs the CLI. Then it runs ship init, which writes one skill for each SHIP capability into .claude/skills/, and it asks you for a token. The skills cover delegation, missions, agent runs, scheduled tasks, MCP servers and sandboxes. The same skills, from the same source, are listed at https://letsship.ai/.well-known/agent-skills/index.json.
The skills CLI reads that index. Run it to install the same skills from the website or from GitHub:
npx skills add https://letsship.ai
npx skills add letsship/skillsCoding agents shows this setup with Claude Code and Codex.
Install it yourself
npm install -g @lets-ship/cli
ship --versionThen write the skills into the repository, so that later agent sessions can load them without a fetch:
ship init # --force replaces copies that are stale or editedAuthenticate
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, ship mission create, start, approve-ceiling, ship schedule run |
missions:read | ship status, ship mission list |
missions:write | ship instruct, ship mission pause, resume, stop, merge, decline, auto-merge, archive, unarchive, disposition |
inspect:read | ship mission inspect |
sandboxes:read | ship run list, get, logs |
sandboxes:stop | ship run stop (an org admin's token) |
environments:read, environments:write | ship preview list / get, and destroy |
artifacts:read | ship artifact list, get |
projects:read | ship project list, get |
scheduled-tasks:read, scheduled-tasks:write | ship schedule list / get / runs / templates, and create / update / delete |
agents:read | ship sandbox list, starters, versions, logs, and ship mission override get / set |
sandboxes:read | ship sandbox capacity |
agents:write | ship sandbox create, update, build, rollback, delete, and ship mission override set / clear |
projects:admin | ship sandbox default, ship project update |
connectors:read, connectors:write | ship sandbox registry list, and set / remove |
The ship whoami, ship credits, ship setup, ship token and ship notice commands need no scope. The ledger, a purchase and a plan change also need an owner or an admin behind the token. 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
A command that acts on one project takes --project <id>, or reads SHIP_PROJECT_ID. On a list command, --project is optional and narrows the list. SHIP_PROJECT_ID does not narrow a list. To find the id, run ship project list. It lists the projects that your token can reach, each with its repository.
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.
How is this page?