CLI

Overview

pnpm add -g @shipdit/cli
shipd --help

Binary: shipd. Package: @shipdit/cli. Every command works non-interactively and supports --json.

Global flags

Flag	Purpose
`--json`	Machine-readable stdout (errors on stderr as JSON)
`--yes` / `--ci`	Skip confirmation (`CI=1` / `SHIPD_CI=1` also)
`--api-url <url>`	API origin (`SHIPD_API_URL`; login defaults to `https://api.useshipd.com`)
`--org <slug>`	Organization (`SHIPD_ORG`)
`--project <slug>`	Project (`SHIPD_PROJECT`)
`--env <slug>`	Environment (`SHIPD_ENV`)
`--config <path>`	Project settings JSON (`.shipd/config.json` shape)
`--flags-config <path>`	Path to `shipd.config.ts`

Precedence (highest wins): CLI flags → env (SHIPD_*) → .shipd/config.json → ~/.config/shipd/. Credentials: ~/.config/shipd/credentials.json (mode 0600). XDG: $XDG_CONFIG_HOME/shipd.

Auth

Command	Description
`shipd login`	Device authorization at `/auth/device/code`. Stores a scoped management API key.
`shipd logout`	Clear stored credentials
`shipd whoami`	Current user or API-key context

Config as code

Command	Description
`shipd pull`	Rewrite `shipd.config.ts` from the server + typegen
`shipd push`	Plan and apply
`shipd diff`	Show plan (`--json`)
`shipd types gen`	Typegen from local config (`-o, --out`)

Push flags

Flag	Meaning
`--prune`	Archive remote flags missing locally
`--force`	Override stale-version CAS (audited)
`--adopt`	Deprecated no-op
`--yes` / `--ci`	Skip confirmation

Removes are archives. Definition changes need flag.production.toggle. Default-only non-prod needs flag.state.update.

Plan:
  + create flag "new-checkout"
  ~ update flag "search-variant"
      description: "Old" -> "New"
      tags: ["search"] -> ["search", "experiment"]
  - archive flag "legacy-homepage"

{
  "creates": [],
  "updates": [],
  "archives": [],
  "unlinked": [],
  "conflicts": []
}

Snapshots

shipd snapshots publish --project web-app --env production

Materialize from Postgres and publish to KV. Use after a failed publish.

Lower-level

Command	Description
`shipd flags list`	List flags
`shipd flags create`	`--key` required; `--type boolean\|variant\|number\|json`; `--variants` required for variant
`shipd flags archive`	Archive by `--key`
`shipd projects list`	List projects
`shipd environments list`	List environments

CI

SHIPD_API_KEY=shipd_mgmt_… shipd push --yes
shipd push --ci --project web-app --org fieldkit --env production

The key’s environment must match --env. --org cannot switch organizations.

Exit codes

Code	Meaning
0	Success / no drift
1	General error
2	Drift (`diff --exit-code`)
3	Conflict (stale version / CAS)
4	Unlinked (`diff --exit-code`)

Guides: Define flags · CI.

Getting started

Guides

How-to

Concepts

Reference

Overview

Global flags

Auth

Config as code

Push flags

Snapshots

Lower-level

CI

Exit codes

​Overview

​Global flags

​Auth

​Config as code

​Push flags

​Snapshots

​Lower-level

​CI

​Exit codes

Overview

Global flags

Auth

Config as code

Push flags

Snapshots

Lower-level

CI

Exit codes