CLI
Every shipmantis command, its flags and its exit codes.
npx shipmantis <command>The CLI reads .env.local, then .env, from the folder you run it in. Every command but init
needs MANTIS_URL and MANTIS_SECRET_KEY, which init writes there.
init
npx shipmantis@latest init [--new <name> | --project <slug>] [--team <slug>]Signs you in through the browser, picks or creates a project, writes its keys to .env.local
and sets the folder up for Claude Code and Codex. See the quickstart
for the files it writes.
| Flag | What it does |
|---|---|
--new <name> | Create a project with this name instead of asking. |
--project <slug> | Use an existing project instead of asking. |
--team <slug> | The team to look in, when you belong to more than one. |
On an existing project, init makes a new key pair for this machine; keys on other machines
keep working. It talks to MANTIS_API_URL, which defaults to https://api.shipmantis.com.
push
npx shipmantis push [--schema <file>] [--dry-run] [--branch <name>]Plans the schema against the branch, prints each step, then applies it. On main, a
change that can lose data or let more people in waits for a person's approval.
| Flag | What it does |
|---|---|
--schema <file> | The schema file. Default: mantis/schema.ts. |
--dry-run | Print the plan without applying it. |
--branch <name> | The branch. Default: MANTIS_BRANCH, else main. |
branch
npx shipmantis branch list
npx shipmantis branch create <name> [--from <parent>]
npx shipmantis branch promote <name>
npx shipmantis branch delete <name>See Branches. create copies main unless you pass --from. promote applies a
branch's schema to the branch it came from.
rewind
npx shipmantis rewind --to <time> [--table <name> [--id <uuid>]] [--apply] [--branch <name>]Shows what rewinding the branch, a table or a row to a time undoes; with --apply, does it. --to
is a time with an offset, or 30m, 2h, 1d ago. On main the rewind waits for a person. See
Rewind.
undo
npx shipmantis undo [--branch <name>]Undoes the latest migration, bringing dropped data back. On main, an undo that can lose data
waits for a person.
mcp
npx shipmantis mcpServes the MCP tools over stdio. Your agent starts it; you don't run it yourself.
Exit codes
| Code | Means |
|---|---|
0 | Done. |
1 | Refused or failed. The reason is printed. |
2 | Waiting for a person's approval. The change's id is printed. |
Code 2 lets a script or an agent tell a held change from a failure.