CLI

The shipmore CLI is the canonical operator surface. It’s a tsup-built binary served from your deployed box at /cli/install.sh; humans and agents drive the same commands.

Install


curl -fsSL https://<your-shipmore-box>/cli/install.sh | bash
shipmore --version

Authenticate

The CLI authenticates with a Payload API key. There is no interactive login flow.

Log into the Payload admin on your deployed box (/admin).
Users → your operator user → enable API Key → Generate → copy.
Export:


export SHIPMORE_API_KEY=<key>
export SHIPMORE_API_URL=https://<your-shipmore-box>

SHIPMORE_API_URL falls back to ~/.shipmore/config (baked by the installer). SHIPMORE_API_KEY is read from the env var only — never written to disk.

Agent protocol

The CLI auto-detects non-TTY environments and outputs JSON. Rules for agents:

Supply ALL required flags. The CLI never prompts; missing flags return validation_error.
Use -q to suppress progress; implies JSON.
Exit 0 = success; >0 = error.
Success JSON → stdout. Error JSON → stderr in the shape {"error":{"message":"…","code":"…"}}.
Introspection: shipmore commands dumps the full command tree + flags + codes as JSON.

Global flags

Flag	Effect
`--json`	Force JSON output (auto on non-TTY)
`-q, --quiet`	Suppress progress; implies `--json`
`--help`	Command help
`--version`	CLI version

Command overview

Command	Purpose
`shipmore tenant ...`	Create, look up, and relocate tenants
`shipmore page ...`	Build pages from block specs; discover block schemas
`shipmore product ...`	Create monetization products; pricing finished in Stripe
`shipmore import`	Import records from a CSV/JSON file or URL
`shipmore schema infer`	Propose a schema from sample rows
`shipmore schema apply`	Persist a schema (and import mapping)
`shipmore schema get`	Read the deployed schema for a tenant
`shipmore schema diff`	Compare a local fields file against the deployed schema (exit 0 = match, 1 = drift)
`shipmore schema field set/drop/list`	Edit fields in a local schema file
`shipmore imports list`	List recent import batches
`shipmore import status <id>`	Inspect a single import batch
`shipmore staging status / clear`	Inspect or release the per-tenant staging session
`shipmore monitor brief --tenant <domain>`	Read the latest observations brief
`shipmore commands`	Dump the full command tree as JSON (agent discovery)

Full flag tables ship with the CLI under references/commands.md.

Error envelope

Every error response:


{ "error": { "message": "…", "code": "…" } }

Exit codes:

0 — success
1 — generic (validation_error, parse_error, network_error, schema_missing, timeout, unknown)
2 — auth_error
3 — file_too_large
4 — tenant_not_found

Common mistakes

#	Mistake	Fix
1	Running `import` before `schema apply`	Run `schema infer` → `schema apply` first. Code: `schema_missing`.
2	Forgetting `--tenant`	Every command requires `--tenant <domain>`. Code: `validation_error`.
3	Running `schema apply` / `page build` before `tenant create`	Schema + pages bind to an existing tenant. Code: `tenant_not_found`.
4	Reconstructing the page URL from the request host	`page build` returns the correct tenant-scoped URL in `response.url` — use it verbatim.

End-to-end quickstart


# 1. Auth
export SHIPMORE_API_KEY=<key>
export SHIPMORE_API_URL=https://your-box
 
# 2. Tenant + schema + import
shipmore tenant create --name "Acme Ramen" --domain ramen.example.com
shipmore schema infer  --tenant ramen.example.com --data-file sample.csv > /tmp/schema.json
shipmore schema apply  --tenant ramen.example.com --fields-file /tmp/schema.json
shipmore import        --tenant ramen.example.com
 
# 3. Page
shipmore page block-schema --name explore-section-block
shipmore page build --tenant ramen.example.com --slug home --title "Browse Ramen Shops" \
  --blocks '[{"type":"explore-section-block","content":{"title":"Browse","pageSize":20}}]'

See Data → Import for the full ingest flow and the agent’s 4-phase workflow.