Overview ~ SHIP

Hand work to the agent fleet from your terminal. Install, authenticate, and pick the right hand-off.

What the CLI is for

ship hands work to the fleet from wherever you already are: a terminal, a script, or a coding agent working in your repository. It talks to the same API the console does, so anything you start here appears on the board and carries the same evidence.

There are two hand-offs, and they cover most of what the CLI is for:

You have	Command	What the fleet does
A plan or spec you already wrote	`ship delegate plan`	Skips its own planning and builds from your spec
A branch you already pushed	`ship delegate pr`	Reviews it, tests it, and drives it to merge

Everything else, meaning instruct and status, is about work already in flight. See Commands for how each one behaves, Capabilities for what people actually use them for, and the Command reference for every flag.

Install

Point your coding agent at it

If you work through a coding agent, give it the skill document and it will install and configure the CLI itself:

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

That document is the same one ship init writes into your repository, served from the same source, so the hosted copy cannot drift from the installed one. The agent reads it, installs the CLI, writes a local copy at .claude/skills/ship-delegate/SKILL.md, and asks you for a token.

Coding agents walks through what that looks like with Claude Code and Codex.

Install it yourself

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

Then write the local skill copy, so future agent sessions load it without a fetch:

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

Authenticate

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

export SHIP_API_TOKEN=pat_...

Tokens carry scopes, enforced per route. For the commands in this section:

Scope	Covers
`missions:run`	`delegate plan`, `delegate pr`
`missions:read`	`ship status`
`missions:write`	`ship instruct`

A token missing a scope fails that command with exit 3 and names the scope. It is not transient, so retrying will not fix it. You can also bind a token to a single project when you create it, which is worth doing for a token an agent will hold.

Which project

ship resolves the project from your git remote. If the remote matches no project, or more than one, it says so, and you pass --project <id> or export SHIP_PROJECT_ID.

Which platform

ship talks to https://api.letsship.ai/v1 unless SHIP_API_BASE_URL says otherwise. Set it for a staging or self-hosted install; the console links the CLI prints derive from it, so they point at the same place your commands do.

Overview