ship

Hand work off to the SHIP AI agent team from your terminal.

Two hand-offs:

• You planned it, SHIP builds it. Write the spec, delegate it, and the platform skips its own planning and builds from what you wrote.
• You built it, SHIP ships it. Open the pull request, delegate it, and the platform reviews it, tests it, and drives it to merge — recovering CI on the way if it is red.

Install

npm install -g @lets-ship/cli

Authenticate

Create a token in the SHIP console under Settings → API tokens, then:

export SHIP_API_TOKEN=pat_...
export SHIP_PROJECT_ID=proj_...   # optional; saves typing --project

The token carries your own permissions and nothing more, and always expires.

Use

# Hand over a plan
ship delegate plan SHIP-412 --file docs/plan.md
ship delegate plan --title "Rate-limit search" --file docs/plan.md   # creates the issue too

# Hand over a branch (open the PR first; --pr is auto-detected via gh)
ship delegate pr SHIP-412
ship delegate pr SHIP-412 --at qa

# Give one role extra instructions, for this mission only
ship delegate pr SHIP-412 --prompt-file security-review.md
ship delegate pr SHIP-412 --prompt-file security-review.md --prompt-mode extend

# Check on it
ship status SHIP-412
ship status SHIP-412 --json
ship mission list --activity needs_attention

# Control it
ship instruct SHIP-412 -m "Keep the current Node range"
ship mission pause SHIP-412
ship mission resume SHIP-412          # also approves a checkpoint
ship mission merge SHIP-412
ship mission override set SHIP-412 --role reviewer --harness codex
ship mission auto-merge SHIP-412 on

# See what each agent did
ship run list --mission SHIP-412
ship run logs builder-ship-412-3f9c41aa-coding-1 --part system

# Run a mission every week
ship schedule create --name deps --template dependency-upgrades

# Who am I, and what is left
ship whoami
ship credits
ship credits ledger
ship token list

# Teach your local coding agent every command (one skill per capability)
ship init

Exit codes

Distinct per failure class, so a script can branch on them without parsing prose.

| Code | Meaning | |---|---| | 0 | Success | | 1 | Unexpected runtime failure | | 2 | Usage error | | 3 | Not permitted, or no token set | | 4 | Not found, or not visible to this token | | 5 | Precondition not met (e.g. a review hand-off naming no PR, no credits, a merge conflict) | | 6 | Platform not ready (finish onboarding) | | 7 | A sandbox build the command waited on failed | | 8 | Too many requests, or a daily limit reached |

What this is

A pure consumer of the public /v1 API — it can do exactly what your token can do, and nothing more. It never pushes to your repository, never opens a pull request on your behalf, and holds no credential for your code host: the PR auto-detection reads your own gh login, locally.