Shipd CLI (@shipd-ai/cli)

shipd is the admin command line for Shipd quests. Point it at a Harbor task directory (or an existing task) and it runs the quest's checks on the quest's own infrastructure, then returns the same structured output the product shows. The CLI is quest-agnostic: every command takes --quest <quest>, and any quest that implements the small adhocChecks:* contract works the same way. shipd quests lists the quests available (olympus today, which is also the default when --quest is omitted).

Admins only: every quest entrypoint checks the caller's effective admin role.

Install and log in

Admin docs, the supported checks, and a copy-paste setup prompt for coding agents live at https://shipd.ai/admin/cli (admins only; direct link to the prompt: https://shipd.ai/admin/cli#agent-setup-prompt).

npm install -g @shipd-ai/cli
shipd login            # opens https://shipd.ai/cli-auth (one token for every quest); or: shipd login --token <jwt>
shipd whoami
shipd quests           # which quests this CLI can talk to

login opens the token page in your browser; paste the token back into the terminal. --no-browser prints the page URL instead of opening it. The token is stored at ~/.shipd/credentials.json (mode 0600). It is personal: never commit or share it. Typing --token by hand leaves it in your shell history, so prefer the prompt there. shipd logout deletes it.

Three input modes

| Mode | Command | What happens | Writes to production | | --- | --- | --- | --- | | Harbor, stateless (default) | shipd checks run <harbor-dir> --check … | Adapts the bundle, runs the checks on the quest's infrastructure, returns their normal output. | Nothing. | | Harbor, create | shipd checks run <harbor-dir> --create --check … | Turns the bundle into a real draft task under your account (every authoring guard applies), then runs the checks live on it. | A draft task + version and the normal job rows. Not submitted for review. | | Existing task | shipd checks run --task <problemId> --check … | Runs the checks live on the task's latest version. | The normal job rows; the version's visible results are re-pointed. |

Both live modes print a Writes to production: line before anything is dispatched; --create prints the new task URL as soon as the draft exists. Checks cost real compute: use --dry-run first and confirm --all with a human when an agent is driving.

Harbor layout

Only these paths are read; everything else in the directory is ignored.

| Path | Used as | Required for | | --- | --- | --- | | task.toml | [metadata] (problem_title, category, language, difficulty, repository_url, base_commit_hash), [environment].docker_image, [verifier].timeout_sec | all | | instruction.md | task description | description-bearing checks | | environment/Dockerfile | sandbox image | sandbox checks without docker_image | | tests/test.patch | test patch | every check except verifyBuild | | tests/test.sh | carried for future native runs | unused by v1 checks | | solution/solution.patch | solution patch | solution-bearing checks | | solution/solve.sh | carried for future native runs | unused by v1 checks |

A missing or unparsable task.toml is a bundle error (exit 2). The seven files may total at most 4 MiB. --repo, --commit, --title, --category, --language and --difficulty override the task.toml metadata, which is how a non-Olympus bundle fills in what it lacks.

Commands

shipd checks list --quest olympus
shipd checks run ./task --all --dry-run                  # eligibility + adapted inputs, spends nothing
shipd checks run ./task --check verifyBuild,descriptionQuality
shipd checks run ./task --all --json --out report.json
shipd checks run ./task --create --check autoReview      # creates a draft, runs live
shipd checks run --task <problemId> --check scopeGate     # runs live on an existing task
shipd checks run ./task --check verifyBuild --no-wait     # prints handles as JSON lines
shipd checks status '<handle json>'                      # or: shipd checks status report.json
shipd checks cancel '<handle json>'                      # or: shipd checks cancel report.json

run options: --quest (default olympus), --check a,b or --all, --dry-run, --no-wait, --json, --out <file>, metadata overrides, --model and --effort low|medium|high|xhigh (honored where the production dispatcher honors them), --poll <seconds> (default 15), --timeout <minutes> per step (default 180, the longest worker timeout).

Checks whose required bundle parts are missing are reported as skipped with the missing list. With --all that is informational; with --check it fails the run. Multi-step checks (for example autoReview) run as a step plan the quest describes: independent steps in parallel, each later step fed the earlier outputs, a failed step marking its dependents skipped: upstream failed. Prechecks (precheck:<stage>) run synchronously.

Ctrl-C asks whether to cancel the in-flight steps; a second Ctrl-C leaves them running. Handles stay in the JSON report, so checks status and checks cancel keep working on them afterwards.

Exit codes

| Code | Meaning | | --- | --- | | 0 | every run check passed or warned | | 1 | a check failed or errored (or an explicitly requested check was skipped) | | 2 | usage, auth, or bundle error (nothing was dispatched) | | 3 | cancelled |

Report

--json and --out produce the same document: quest, mode, source (bundle directory and inputHash, or the task ids, title and URL), a top-level taskUrl in live modes, one entry per check with status, verdict, output, error, durationMs, and steps (each step's handle and output), plus prechecks keyed by stage id.

Environment

| Variable | Effect | | --- | --- | | SHIPD_AUTH_URL | Override the platform login page shipd login opens (default https://shipd.ai/cli-auth). | | SHIPD_<QUEST>_URL | Override the quest's base URL (for example SHIPD_OLYMPUS_URL). | | SHIPD_<QUEST>_CONVEX_URL | Skip /api/cli/config and talk to this Convex deployment. | | SHIPD_HOME | Credentials and caches directory (default ~/.shipd). | | SHIPD_NO_UPDATE_CHECK=1 | Skip the version check. | | NODE_ENV=development | Use the localhost quest URLs. |

Developer notes

pnpm --dir packages/shipd-cli typecheck
pnpm --dir packages/shipd-cli test
pnpm --dir packages/shipd-cli build
pnpm --dir packages/shipd-cli cli checks list --quest olympus          # runs src/ with tsx
NODE_ENV=development pnpm --dir packages/shipd-cli cli checks list     # against a local quest

The CLI contains no quest logic. It calls adhocChecks:* by name through Convex's anyApi; the shared argument and return shapes live in src/contract.ts, and each quest mirrors them with validators. The plan executor (src/plan.ts) and bundle reader (src/harbor.ts) are unit-tested against a fake quest and a fixture bundle in test/.

Publishing: pnpm --dir packages/shipd-cli build && npm publish --access public from an account in the @shipd-ai npm org.