CLI reference

Auto-generated reference for the `shipeasy` CLI — every command, argument, and flag, straight from the command definitions.

Every command below is generated from the CLI's own command tree, so it always matches the installed binary. Run any command with --help for the same information in your terminal.

New to the CLI? Start with the CLI guide for installation, auth, and worked examples — this page is the exhaustive flag-by-flag reference.

Authenticate via PKCE device flow (no-op if already logged in)

With no flags, login auto-detects the project: an explicit --project wins, otherwise the project bound via the nearest .shipeasy file (searched up from the cwd, like .git) — the browser flow then offers only that project. With neither, it opens the picker and writes .shipeasy on success.

In CI, set SHIPEASY_CLI_TOKEN + SHIPEASY_PROJECT_ID instead — they act as the session, so login short-circuits as already-authenticated (no browser).

shipeasy login [options]

Option		Description
`--force`	optional	Re-authenticate even if a valid session already exists
`--project <id>`	optional	Scope login to one project (defaults to the .shipeasy-bound project)

Examples:

# Use the .shipeasy-bound project, else open the picker
shipeasy login

# Re-authenticate over a live session
shipeasy login --force

# Scope to one project explicitly
shipeasy login --project proj_abc123

# CI: env credentials act as the session, so this is a no-op
SHIPEASY_CLI_TOKEN=… SHIPEASY_PROJECT_ID=… shipeasy login

logout

Clear stored credentials

`shipeasy logout`

Clear stored credentials

shipeasy logout [options]

Examples:

shipeasy logout

whoami

Show current authentication state and active project metadata

`shipeasy whoami`

Show current authentication state and active project metadata

shipeasy whoami [options]

Option		Description
`--json`	optional	Output as JSON

Examples:

shipeasy whoami

# machine-readable session + project
shipeasy whoami --json

Returns (with --json):

{
  "logged_in": true,
  "session": {
    "project_id": "proj_abc123",
    "user_email": "you@example.com",
    "worker_url": "https://api.shipeasy.ai",
    "app_url": "https://shipeasy.ai",
    "saved_at": "2026-06-14T17:00:00.000Z"
  },
  "bound_dir": {
    "project_id": "proj_abc123",
    "project_name": "acme"
  },
  "active_project_id": "proj_abc123",
  "project": {
    "id": "proj_abc123",
    "name": "acme",
    "domain": "acme.com",
    "ownerEmail": "you@example.com",
    "plan": "paid",
    "status": "active"
  },
  "project_error": null
}

bind

Bind the current directory to a Shipeasy project (writes .shipeasy)

`shipeasy bind`

Bind the current directory to a Shipeasy project (writes .shipeasy)

shipeasy bind [options] [project_id]

Argument		Description
`project_id`	optional	—

Option		Description
`--name <name>`	optional	Optional human-readable project name to record

Examples:

# bind to the active session's project
shipeasy bind

shipeasy bind proj_abc123

shipeasy bind proj_abc123 --name 'Acme Web'

setup

One-command onboarding: log in + bind a project, detect your coding agents, register the Shipeasy MCP server + skills, and hand SDK wiring to the agent.

`shipeasy setup`

One-command onboarding: log in + bind a project, detect your coding agents, register the Shipeasy MCP server + skills, and hand SDK wiring to the agent.

setup is the one place that wires Shipeasy into your coding agents — there is no separate skills/plugin install step. It detects every agent in your environment (Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Google Jules) and wires each one the way that agent expects:

Claude Code — installs the marketplace plugin (slash commands + skills + MCP), or drops .mcp.json when the claude binary isn't on PATH.
Cursor / Codex / Copilot / Jules — registers the @shipeasy/mcp server in that agent's config and writes its instructions file (.cursor/rules/shipeasy.mdc, AGENTS.md, .github/copilot-instructions.md).

Pick a subset with --agents, or let it auto-detect. It's idempotent — safe to re-run as you add agents. In CI (non-TTY) it runs non-interactively with SHIPEASY_CLI_TOKEN + SHIPEASY_PROJECT_ID.

shipeasy setup [options]

Option		Description
`--yes`	optional	Non-interactive: bind current project + wire all detected agents
`--agents <list>`	optional	Comma list to wire (claude,cursor,codex,copilot,jules)
`--domain <domain>`	optional	Production domain, passed to the Claude /shipeasy:setup step
`--scope <scope>`	optional	user \| project (MCP config scope) (default: `"project"`)
`--no-claude-run`	optional	Don't launch Claude Code for the in-repo wiring step
`--dry-run`	optional	Show what would change without writing files or launching anything

Examples:

# interactive: detect + wire every agent found
shipeasy setup

# non-interactive subset
shipeasy setup --yes --agents claude,cursor

# preview without writing
shipeasy setup --dry-run --no-claude-run

projects

Manage Shipeasy projects scoped to your account

`shipeasy projects upsert`

Find-or-create a project by domain (idempotent). Without --no-bind, writes the result to .shipeasy in the current directory.

shipeasy projects upsert [options]

Option		Description
`--domain <domain>`	required	Hostname-like identifier for the project (e.g. shouks.app, acme.com)
`--name <name>`	optional	Human-readable project name (defaults to the domain on first create)
`--no-bind`	optional	Don't write .shipeasy after upsert
`--json`	optional	Output as JSON

Examples:

# Find-or-create and bind to .shipeasy
shipeasy projects upsert --domain acme.com

# Name it explicitly, don't write .shipeasy
shipeasy projects upsert --domain shouks.app --name "Shouks" --no-bind

modules

Enable, disable, or inspect per-project feature modules

`shipeasy modules list`

Show which modules are enabled on the bound project

shipeasy modules list [options]

Option		Description
`--json`	optional	Output as JSON

Examples:

shipeasy modules list

`shipeasy modules enable`

Enable a module (translations | configs | gates | experiments | feedback)

shipeasy modules enable [options] <name>

Argument		Description
`name`	required	—

Examples:

# Turn on the feedback module
shipeasy modules enable feedback

`shipeasy modules disable`

Disable a module (translations | configs | gates | experiments | feedback)

shipeasy modules disable [options] <name>

Argument		Description
`name`	required	—

Examples:

# Turn off experiments
shipeasy modules disable experiments

flags

Manage feature flags (gates)

`shipeasy flags list`

List all feature flags

shipeasy flags list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy flags list

Returns (with --json):

[
  {
    "id": "gate_7Hq2",
    "name": "checkout-v2",
    "enabled": true,
    "rolloutPct": 2500,
    "rules": [
      {
        "attr": "plan",
        "op": "eq",
        "value": "pro"
      }
    ],
    "updatedAt": "2026-06-14T17:00:00.000Z"
  }
]

`shipeasy flags create`

Create a new feature flag

shipeasy flags create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--rollout <pct>`	optional	Rollout percentage (0-100) (default: `"0"`)
`--rules <json>`	optional	Targeting rules as JSON array
`--salt <s>`	optional	Override hash salt
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Off by default; flip it on later
shipeasy flags create checkout-v2

# Roll out to 25% of pro-plan users
shipeasy flags create new-ui --rollout 25 --rules '[{"attr":"plan","op":"eq","value":"pro"}]'

`shipeasy flags enable`

Enable a feature flag

shipeasy flags enable [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy flags enable checkout-v2

`shipeasy flags disable`

Disable a feature flag

shipeasy flags disable [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy flags disable checkout-v2

`shipeasy flags rollout`

Set rollout percentage (0-100) for a feature flag

shipeasy flags rollout [options] <name> <pct>

Argument		Description
`name`	required	—
`pct`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Ramp to 50%
shipeasy flags rollout checkout-v2 50

# Instant kill — set to 0
shipeasy flags rollout checkout-v2 0

`shipeasy flags delete`

Delete a feature flag

shipeasy flags delete [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy flags delete checkout-v2

killswitch

Manage killswitches

`shipeasy killswitch list`

List all killswitches

shipeasy killswitch list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy killswitch list

`shipeasy killswitch create`

Create a killswitch (name must be folder.name)

shipeasy killswitch create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--description <desc>`	optional	Description
`--value <bool>`	optional	Default value (true\|false) (default: `"false"`)
`--switches <json>`	optional	JSON object of { switch_key: bool }; takes precedence over value
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Default OFF
shipeasy killswitch create payments.stripe-gateway

# Pre-seed per-key switches
shipeasy killswitch create payments.stripe-gateway --switches '{"refunds":true,"payouts":false}'

`shipeasy killswitch update`

Update a killswitch's default value, switches map, or description

shipeasy killswitch update [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--value <bool>`	optional	Default value (true\|false)
`--switches <json>`	optional	JSON object of { switch_key: bool } — replaces wholesale
`--description <desc>`	optional	Description (pass empty to clear)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Flip the default ON
shipeasy killswitch update payments.stripe-gateway --value true

# Replace the whole switches map
shipeasy killswitch update payments.stripe-gateway --switches '{"refunds":false}'

`shipeasy killswitch delete`

Delete a killswitch

shipeasy killswitch delete [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy killswitch delete payments.stripe-gateway

`shipeasy killswitch set`

Set or update one switch entry on one env (default env=prod)

A kill switch is a named set of boolean switches that ship in the flags KV blob alongside gates and configs, so the SDK reads them with no extra round-trip. Each switch is keyed by switch_key and scoped per environment (dev / staging / prod) — so you can flip one dependency off in prod while leaving staging running. set creates or updates a single switch entry; the value is coerced (true/1/on → true, false/0/off → false).

See Kill switches for the full model — when to reach for a kill switch vs. a gate at 0%, and how switches evaluate at the edge.

shipeasy killswitch set [options] <name> <switch_key> <value>

Argument		Description
`name`	required	—
`switch_key`	required	—
`value`	required	—

Option		Description
`--env <env>`	optional	Env: dev \| staging \| prod (default: `"prod"`)
`--project <id>`	optional	Project ID override

Examples:

# Kill refunds in prod
shipeasy killswitch set payments.stripe-gateway refunds true

# Target staging instead
shipeasy killswitch set payments.stripe-gateway refunds true --env staging

`shipeasy killswitch unset`

Remove one switch entry from one env (default env=prod)

Removes one switch entry from one environment, reverting that key to its default (absent = not overridden). The inverse of set. See Kill switches.

shipeasy killswitch unset [options] <name> <switch_key>

Argument		Description
`name`	required	—
`switch_key`	required	—

Option		Description
`--env <env>`	optional	Env: dev \| staging \| prod (default: `"prod"`)
`--project <id>`	optional	Project ID override

Examples:

shipeasy killswitch unset payments.stripe-gateway refunds

# From staging
shipeasy killswitch unset payments.stripe-gateway refunds --env staging

experiments

Manage experiments

`shipeasy experiments list`

List experiments

shipeasy experiments list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments list

`shipeasy experiments create`

Create a new experiment

shipeasy experiments create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--universe <name>`	optional	Universe name (default: `"default"`)
`--allocation <pct>`	optional	Allocation percentage (0-100) (default: `"100"`)
`--groups <json>`	optional	Groups as JSON [{name,weight,params}]
`--params <json>`	optional	Parameter schema {name: type}
`--targeting-gate <name>`	optional	Targeting gate name
`--salt <s>`	optional	Override hash salt
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Default 50/50 control vs test, full traffic
shipeasy experiments create pricing-page

# Custom groups + weights in a named universe
shipeasy experiments create checkout-cta --universe web --allocation 100 \
  --groups '[{"name":"control","weight":5000,"params":{"label":"Pay"}},{"name":"v1","weight":5000,"params":{"label":"Buy now"}}]'

`shipeasy experiments update`

Update an experiment by name

shipeasy experiments update [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--allocation <pct>`	optional	Allocation percentage (0-100)
`--groups <json>`	optional	Groups as JSON [{name,weight,params}]
`--params <json>`	optional	Parameter schema {name: type}
`--targeting-gate <name>`	optional	Targeting gate name (use 'null' to clear)
`--significance <p>`	optional	Significance threshold (0.0001-0.5)
`--min-runtime-days <n>`	optional	Minimum runtime in days
`--min-sample-size <n>`	optional	Minimum sample size
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Dial allocation up to 50%
shipeasy experiments update pricing-page --allocation 50

# Clear targeting + tighten significance
shipeasy experiments update checkout-cta --targeting-gate null --significance 0.01

`shipeasy experiments delete`

Delete an experiment by name

shipeasy experiments delete [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments delete pricing-page

`shipeasy experiments start`

Start an experiment

shipeasy experiments start [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments start pricing-page

`shipeasy experiments stop`

Stop a running experiment

shipeasy experiments stop [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments stop pricing-page

`shipeasy experiments archive`

Archive a stopped experiment

shipeasy experiments archive [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments archive pricing-page

`shipeasy experiments reanalyze`

Re-run analysis pass for an experiment

shipeasy experiments reanalyze [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments reanalyze pricing-page

`shipeasy experiments status`

Show experiment status and latest results

shipeasy experiments status [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy experiments status pricing-page

metrics

Manage event metrics

`shipeasy metrics grammar`

Print the metric query DSL grammar

Prints the full metric query DSL grammar — aggregation functions, event selectors, label filters, and group-by. The same reference is published at Query DSL grammar.

shipeasy metrics grammar [options]

Examples:

shipeasy metrics grammar

`shipeasy metrics list`

List metrics in the bound project

shipeasy metrics list [options]

Option		Description
`--json`	optional	Output JSON

Examples:

shipeasy metrics list

`shipeasy metrics show`

Show one metric

shipeasy metrics show [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output JSON

Examples:

shipeasy metrics show 3f9a2c1b

`shipeasy metrics create`

Create a metric. Pass the DSL via --query, or pass --query-ir for the typed form.

shipeasy metrics create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--event <name>`	required	Source event name
`--query <dsl>`	optional	Query DSL string, e.g. 'sum(purchase, amount)'
`--query-ir <json>`	optional	Typed IR JSON (alternative to --query)
`--folder <folder>`	optional	Folder
`--winsorize <pct>`	optional	Winsorize percentile (1-99) (default: `"99"`)
`--mde <value>`	optional	Min detectable effect (0-1)

Examples:

# Unique users who completed checkout
shipeasy metrics create checkouts --event checkout_completed \
  --query 'count_users(checkout_completed)'

# p99 latency by route, grouped
shipeasy metrics create api-latency --event req_dur \
  --query 'p99(req_dur{route=~"/api/.*"}, ms) by (route)'

`shipeasy metrics delete`

Delete a metric (soft delete)

shipeasy metrics delete [options] <id>

Argument		Description
`id`	required	—

Examples:

shipeasy metrics delete 3f9a2c1b

configs

Manage remote-config values

`shipeasy configs list`

List all configs

shipeasy configs list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy configs list

`shipeasy configs get`

Show a config by name

shipeasy configs get [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy configs get pricing

`shipeasy configs create`

Create a new config. Configs are JSON objects validated against a JSON Schema.

shipeasy configs create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--schema <json>`	optional	JSON Schema (object only). Defaults to a permissive object schema.
`--value <json>`	optional	Initial value as JSON object. Defaults to {}.
`--description <text>`	optional	Human-readable description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Permissive schema, empty value
shipeasy configs create pricing

# Seed an initial value
shipeasy configs create pricing --value '{"free_trial_days":14}'

`shipeasy configs update`

Update a config's value (legacy flat update; use draft/publish for envs)

shipeasy configs update [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--value <json>`	required	New value (JSON-encoded)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Overwrite the value (all envs)
shipeasy configs update pricing --value '{"free_trial_days":30}'

`shipeasy configs draft`

Save a draft value for the given env

shipeasy configs draft [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--env <env>`	required	Target env (e.g. prod, staging, dev)
`--value <json>`	required	Draft value (JSON-encoded)
`--project <id>`	optional	Project ID override

Examples:

# Stage a prod value to publish later
shipeasy configs draft pricing --env prod --value '{"free_trial_days":30}'

`shipeasy configs publish`

Publish the saved draft for the given env

shipeasy configs publish [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--env <env>`	required	Target env to publish
`--project <id>`	optional	Project ID override

Examples:

# Promote the staged draft to prod
shipeasy configs publish pricing --env prod

`shipeasy configs delete`

Delete a config by name

shipeasy configs delete [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy configs delete pricing

universes

Manage experiment universes (containers + holdouts)

`shipeasy universes list`

List universes

shipeasy universes list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy universes list

`shipeasy universes create`

Create a universe

shipeasy universes create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--unit-type <t>`	optional	Unit type (e.g. user_id, account_id) (default: `"user_id"`)
`--holdout <range>`	optional	Holdout range as 'lo,hi' (0-9999); omit for no holdout
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Default user_id unit, no holdout
shipeasy universes create web

# 10% holdout, keyed on account_id
shipeasy universes create web --unit-type account_id --holdout 0,999

`shipeasy universes update`

Update a universe's holdout range

shipeasy universes update [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--holdout <range>`	optional	Holdout range as 'lo,hi' (0-9999), or 'null' to clear
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Set a 5% holdout
shipeasy universes update web --holdout 0,499

# Clear the holdout
shipeasy universes update web --holdout null

`shipeasy universes delete`

Delete a universe by name

shipeasy universes delete [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy universes delete web

feedback

Manage bug reports and feature requests

`shipeasy feedback bugs`

Bug reports

shipeasy feedback bugs [options] [command]

`shipeasy feedback features`

Feature requests

shipeasy feedback features [options] [command]

connectors

Manage feedback connectors (Google Sheets, GitHub, Claude triggers)

`shipeasy connectors create-trigger`

Register a Claude trigger connector for a Claude Code routine. The routine bearer token is encrypted at rest server-side and never logged.

shipeasy connectors create-trigger [options]

Option		Description
`--routine-id <id>`	required	Claude Code routine id to fire
`--token <token>`	required	Routine bearer token (used to fire the routine)
`--text <prompt>`	optional	Default prompt sent when the routine is fired without one
`--name <name>`	optional	Connector display name (default: `"Claude trigger"`)
`--events <list>`	optional	Comma-separated auto-fire events (bug.created, feature_request.created); default none
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Register a routine, auto-fire on new bugs
shipeasy connectors create-trigger --routine-id rt_abc123 --token se_rt_xxx \
  --events bug.created,feature_request.created

# On-demand only, with a default prompt
shipeasy connectors create-trigger --routine-id rt_abc123 --token se_rt_xxx \
  --name "Nightly fixer" --text "Fix the top open bug"

`shipeasy connectors fire`

Fire a Claude trigger connector's routine now

shipeasy connectors fire [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--text <prompt>`	optional	Prompt to send for this run (overrides the connector default)
`--project <id>`	optional	Project ID override

Examples:

# Fire a connector by id prefix
shipeasy connectors fire a1b2c3d4

# Fire with a one-off prompt
shipeasy connectors fire a1b2c3d4 --text "Fix bug #42"

`shipeasy connectors list`

List feedback connectors

shipeasy connectors list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy connectors list

ops

Operational CLIs — reference a sub-CLI explicitly (see shipeasy ops)

`shipeasy ops`

Operational CLIs — reference a sub-CLI explicitly (see shipeasy ops)

shipeasy ops [options]

ops.list

List the unified operational queue (bugs + features + error/alert tickets)

`shipeasy ops.list`

List the unified operational queue (bugs + features + error/alert tickets)

shipeasy ops.list [options]

Option		Description
`--type <type>`	optional	Filter by type: bug\|feature_request\|error\|alert\|all (default: `"all"`)
`--status <status>`	optional	Filter by status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix\|all (default: `"open"`)
`--priority <priority>`	optional	Filter by priority: nice_to_have\|medium\|high\|critical
`--limit <n>`	optional	Max rows (default: `"200"`)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Open critical items only
shipeasy ops.list --priority critical

# Just error tickets
shipeasy ops.list --type error

ops.get

Show one queue item by number (#7 → 7) or id — any type

`shipeasy ops.get`

Show one queue item by number (#7 → 7) or id — any type

shipeasy ops.get [options] <handle>

Argument		Description
`handle`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# By queue number
shipeasy ops.get 7

ops.update

Flip a queue item's status (any type) — and optionally its priority

`shipeasy ops.update`

Flip a queue item's status (any type) — and optionally its priority

shipeasy ops.update [options] <handle>

Argument		Description
`handle`	required	—

Option		Description
`--status <status>`	optional	New status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix
`--priority <priority>`	optional	New priority: nice_to_have\|medium\|high\|critical
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Resolve item #7
shipeasy ops.update 7 --status resolved

# Bump priority
shipeasy ops.update 7 --priority high

ops.link-pr

Link the PR that fixed a queue item (any type). Records connector_data.github.pr; ops-key safe.

`shipeasy ops.link-pr`

Link the PR that fixed a queue item (any type). Records connector_data.github.pr; ops-key safe.

shipeasy ops.link-pr [options] <handle> <pr-number>

Argument		Description
`handle`	required	—
`pr-number`	required	—

Option		Description
`--url <url>`	optional	Explicit PR URL (recommended — required for error/alert tickets)
`--remove`	optional	Unlink the PR instead of setting one
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Link the fixing PR (with URL)
shipeasy ops.link-pr 7 42 --url https://github.com/acme/app/pull/42

ops.notify

Raise a 'needs your attention' bell notification (agent escalation, create-only)

`shipeasy ops.notify`

Raise a 'needs your attention' bell notification (agent escalation, create-only)

shipeasy ops.notify [options]

Option		Description
`--title <text>`	required	One-line headline of what's blocked
`--summary <text>`	required	One sentence: why it can't be fixed in code
`--step <text>`	optional	A step the human should take (repeatable, ordered) (default: `[]`)
`--href <path>`	optional	Dashboard-relative deep link to the related item
`--item <number>`	optional	Queue item this is about — sets a stable dedupe key (feedback:<n>)
`--key <dedupe>`	optional	Explicit dedupe key (overrides --item); re-runs collapse to one row
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Escalate a blocked item to the bell
shipeasy ops.notify --item 7 \
  --title "Needs a DB migration" \
  --summary "Fix requires a schema change I can't apply in code" \
  --step "Add the column via wrangler d1 migrations" \
  --step "Re-run the fixer"

ops.bugs

Bug reports

`shipeasy ops.bugs list`

List bugs

shipeasy ops.bugs list [options]

Option		Description
`--status <status>`	optional	Filter by status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix
`--priority <priority>`	optional	Filter by priority: nice_to_have\|medium\|high\|critical
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Only open bugs
shipeasy ops.bugs list --status open

`shipeasy ops.bugs get`

Show one bug by id (or id prefix)

shipeasy ops.bugs get [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Look up by id prefix
shipeasy ops.bugs get a1b2c3d4

`shipeasy ops.bugs update`

Update a bug — supports --status and --priority <priority>

shipeasy ops.bugs update [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--status <status>`	optional	New status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix
`--priority <priority>`	optional	New priority: nice_to_have\|medium\|high\|critical
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Mark in progress
shipeasy ops.bugs update a1b2c3d4 --status in_progress

# Bump priority
shipeasy ops.bugs update a1b2c3d4 --priority high

`shipeasy ops.bugs create`

File a bug

shipeasy ops.bugs create [options] <title>

Argument		Description
`title`	required	—

Option		Description
`--page-url <url>`	optional	Page URL where it was observed
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override
`--steps <text>`	required	Steps to reproduce
`--actual <text>`	required	Actual result
`--expected <text>`	required	Expected result

Examples:

# File a bug
shipeasy ops.bugs create "Short bug title" --steps "…" --actual "…" --expected "…"

`shipeasy ops.bugs delete`

Delete a bug by id (or id prefix)

shipeasy ops.bugs delete [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

# Delete by id prefix
shipeasy ops.bugs delete a1b2c3d4

`shipeasy ops.bugs attachments`

Download all attachments for a bug to a local directory. Prints one absolute path per line on stdout (suitable for piping into other tools).

shipeasy ops.bugs attachments [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--out <dir>`	optional	Output directory. Defaults to a tmpdir under $TMPDIR/shipeasy-bugs/<id>/
`--json`	optional	Output JSON metadata instead of plain paths
`--project <id>`	optional	Project ID override

Examples:

# Download attachments to a directory
shipeasy ops.bugs attachments a1b2c3d4 --out ./shots

`shipeasy ops.bugs link-pr`

Link a GitHub pull request to a bug. When a GitHub connector is configured, prints the PR URL.

shipeasy ops.bugs link-pr [options] <id> <pr-number>

Argument		Description
`id`	required	—
`pr-number`	required	—

Option		Description
`--remove`	optional	Unlink the PR instead of setting one
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Link the PR that fixed it
shipeasy ops.bugs link-pr a1b2c3d4 42

# Unlink the PR
shipeasy ops.bugs link-pr a1b2c3d4 0 --remove

ops.features

Feature requests

`shipeasy ops.features list`

List features

shipeasy ops.features list [options]

Option		Description
`--status <status>`	optional	Filter by status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix
`--priority <priority>`	optional	Filter by priority: nice_to_have\|medium\|high\|critical
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Only open features
shipeasy ops.features list --status open

`shipeasy ops.features get`

Show one feature request by id (or id prefix)

shipeasy ops.features get [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Look up by id prefix
shipeasy ops.features get a1b2c3d4

`shipeasy ops.features update`

Update a feature request — supports --status and --priority <priority>

shipeasy ops.features update [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--status <status>`	optional	New status: open\|triaged\|in_progress\|ready_for_qa\|resolved\|wont_fix
`--priority <priority>`	optional	New priority: nice_to_have\|medium\|high\|critical
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Mark in progress
shipeasy ops.features update a1b2c3d4 --status in_progress

# Bump priority
shipeasy ops.features update a1b2c3d4 --priority high

`shipeasy ops.features create`

File a feature request

shipeasy ops.features create [options] <title>

Argument		Description
`title`	required	—

Option		Description
`--page-url <url>`	optional	Page URL where it was observed
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override
`--description <text>`	required	Description
`--use-case <text>`	required	Use case

Examples:

# File a feature request
shipeasy ops.features create "Short feature request title" --description "…" --use-case "…"

`shipeasy ops.features delete`

Delete a feature request by id (or id prefix)

shipeasy ops.features delete [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

# Delete by id prefix
shipeasy ops.features delete a1b2c3d4

`shipeasy ops.features attachments`

Download all attachments for a feature request to a local directory. Prints one absolute path per line on stdout (suitable for piping into other tools).

shipeasy ops.features attachments [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--out <dir>`	optional	Output directory. Defaults to a tmpdir under $TMPDIR/shipeasy-features/<id>/
`--json`	optional	Output JSON metadata instead of plain paths
`--project <id>`	optional	Project ID override

Examples:

# Download attachments to a directory
shipeasy ops.features attachments a1b2c3d4 --out ./shots

`shipeasy ops.features link-pr`

Link a GitHub pull request to a feature request. When a GitHub connector is configured, prints the PR URL.

shipeasy ops.features link-pr [options] <id> <pr-number>

Argument		Description
`id`	required	—
`pr-number`	required	—

Option		Description
`--remove`	optional	Unlink the PR instead of setting one
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Link the PR that fixed it
shipeasy ops.features link-pr a1b2c3d4 42

# Unlink the PR
shipeasy ops.features link-pr a1b2c3d4 0 --remove

ops.errors

Tracked production errors (read-only)

`shipeasy ops.errors list`

List tracked errors (most-recently-seen first)

shipeasy ops.errors list [options]

Option		Description
`--status <status>`	optional	Filter by status: open\|resolved\|ignored
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Only unresolved errors
shipeasy ops.errors list --status open

`shipeasy ops.errors get`

Show one tracked error by id (or id prefix)

shipeasy ops.errors get [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Inspect by id prefix
shipeasy ops.errors get a1b2c3d4

`shipeasy ops.errors update`

Set a tracked error's status: open|resolved|ignored

shipeasy ops.errors update [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--status <status>`	required	New status: open\|resolved\|ignored
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Mark resolved after a fix lands
shipeasy ops.errors update a1b2c3d4 --status resolved

alerts

Active alerts (read-only)

`shipeasy alerts list`

List alerts (danger first, then most-recent). Defaults to active.

shipeasy alerts list [options]

Option		Description
`--status <status>`	optional	Filter by status: active\|resolved\|dismissed\|all (default: `"active"`)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy alerts list

# Include resolved + dismissed
shipeasy alerts list --status all

`shipeasy alerts get`

Show one alert by id (or id prefix)

shipeasy alerts get [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# id or unique id-prefix
shipeasy alerts get a1b2c3d4

alert-rules

Manage metric-threshold alert rules (writable; shipeasy alerts is read-only)

`shipeasy alert-rules list`

List alert rules

shipeasy alert-rules list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy alert-rules list

`shipeasy alert-rules create`

Create an alert rule. The metric (and its aggregation) is fixed for the rule's life.

shipeasy alert-rules create [options] <name>

Argument		Description
`name`	required	—

Option		Description
`--metric <id\|name>`	required	Metric to evaluate (id or name)
`--comparator <op>`	required	Comparison: gt \| gte \| lt \| lte
`--threshold <number>`	required	Threshold the metric value is compared against
`--window <hours>`	optional	Lookback window in whole hours (1–720) (default: `"24"`)
`--severity <level>`	optional	Severity: danger \| warn \| info (default: `"warn"`)
`--disabled`	optional	Create the rule disabled (default: enabled)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Alert when error rate exceeds 50 / 24h
shipeasy alert-rules create high-error-rate --metric api-errors \
  --comparator gt --threshold 50

# Danger if checkouts drop below 100 in 6h
shipeasy alert-rules create low-checkouts --metric checkouts \
  --comparator lt --threshold 100 --window 6 --severity danger

`shipeasy alert-rules update`

Update an alert rule's tunable knobs (id or id-prefix or unique name). Metric is immutable.

shipeasy alert-rules update [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--name <name>`	optional	Human label for the rule
`--comparator <op>`	optional	Comparison: gt \| gte \| lt \| lte
`--threshold <number>`	optional	Threshold the metric value is compared against
`--window <hours>`	optional	Lookback window in whole hours (1–720)
`--severity <level>`	optional	Severity: danger \| warn \| info
`--enabled <bool>`	optional	Enable/disable the rule (true\|false)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Raise the threshold
shipeasy alert-rules update high-error-rate --threshold 100

# Disable a rule
shipeasy alert-rules update high-error-rate --enabled false

`shipeasy alert-rules delete`

Delete an alert rule (id or id-prefix or unique name)

shipeasy alert-rules delete [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--project <id>`	optional	Project ID override

Examples:

shipeasy alert-rules delete high-error-rate

keys

Manage SDK keys (server, client, admin, ops)

`shipeasy keys list`

List SDK keys for the current project

shipeasy keys list [options]

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

shipeasy keys list

# Machine-readable output
shipeasy keys list --json

`shipeasy keys create`

Create a new SDK key. The raw token is shown ONCE — store it now.

shipeasy keys create [options]

Option		Description
`--type <type>`	required	Key type: server \| client \| admin \| ops
`--env <env>`	server/client	Environment the key is bound to: dev \| staging \| prod. Required for server and client keys; ignored for admin/ops.
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Each server/client key is bound to one environment at mint time. The worker derives the read environment from the key — a client key can only ever read its own env (it ships in the browser, so it cannot be trusted to pick), while a server key may additionally pass ?env= per request as an explicit override. Mint one key per environment.

Examples:

# Server key for production (private, server-only)
shipeasy keys create --type server --env prod

# Public client key for staging
shipeasy keys create --type client --env staging

# Restricted ops key for the trigger (env-agnostic)
shipeasy keys create --type ops

`shipeasy keys revoke`

Revoke a key by id (or id prefix; first match wins)

shipeasy keys revoke [options] <id>

Argument		Description
`id`	required	—

Option		Description
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Revoke by full id
shipeasy keys revoke 7f3a9c10-2b4d-4e6f-8a1b-0c2d3e4f5a6b

# Revoke by id prefix (first match)
shipeasy keys revoke 7f3a9c10

scan

Detect project language, framework, and ShipEasy SDK state

`shipeasy scan`

Detect project language, framework, and ShipEasy SDK state

shipeasy scan [options] [paths...]

Argument		Description
`paths...`	optional	—

Option		Description
`--json`	optional	Output raw JSON

Examples:

# Scan the current directory
shipeasy scan

# Scan a specific app in a monorepo
shipeasy scan ./apps/web

# Raw JSON for tooling
shipeasy scan ./src --json

i18n

String Manager (i18n) tools

`shipeasy i18n install-loader`

Inject the ShipEasy i18n loader script into your project

shipeasy i18n install-loader [options]

Option		Description
`--data-key <key>`	optional	Client SDK key (created automatically if omitted)
`--profile <profile>`	optional	Locale profile name (default: `"default"`)
`--path <file>`	optional	Override target file path (auto-detected by default)
`--project <id>`	optional	Project ID override
`--print`	optional	Print the script tag only, do not write files

Examples:

# Auto-detect the layout and inject
shipeasy i18n install-loader --profile en:prod

# Print the tag only, do not write
shipeasy i18n install-loader --print

# Target a specific file
shipeasy i18n install-loader --path ./src/app/layout.tsx

`shipeasy i18n scan`

Find translatable strings in source files. Reports both already-wrapped t('key') calls and unwrapped JSX text / string props that look translatable.

shipeasy i18n scan [options] [paths...]

Argument		Description
`paths...`	optional	—

Option		Description
`--keys-only`	optional	Only report existing t('key') call sites — skip discovery
`--json`	optional	Output as JSON

Examples:

# Discover translatable strings under src/
shipeasy i18n scan ./src

# Only report existing t('key') calls
shipeasy i18n scan ./src --keys-only

`shipeasy i18n push`

Add NEW keys from a JSON file to the i18n profile. The file is a flat { "<key>": "<value>" } map. This only ADDS keys that do not already exist — existing keys are never overwritten. To change a value, update one key at a time with shipeasy i18n update <key> <value>.

shipeasy i18n push [options] <file>

Argument		Description
`file`	required	—

Option		Description
`--profile <name>`	required	Profile name (e.g. 'default')
`--chunk <name>`	optional	Logical grouping for the keys (default: `"default"`)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Add new keys from a flat JSON map
shipeasy i18n push ./locales/en.json --profile en:prod

# Group the keys under a chunk
shipeasy i18n push ./locales/en.json --profile en:prod --chunk marketing

`shipeasy i18n update`

Update the value of a single existing key. push only adds new keys; use this to change a value (one key per call).

shipeasy i18n update [options] <key> <value>

Argument		Description
`key`	required	—
`value`	required	—

Option		Description
`--profile <name>`	required	Profile name (e.g. 'en:prod')
`--description <text>`	optional	Optional description to store with the key
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Change one key's value
shipeasy i18n update home.cta 'Get started' --profile en:prod

# Value containing double quotes
shipeasy i18n update home.title 'Welcome to "ShipEasy"' --profile en:prod

`shipeasy i18n publish`

Publish a profile chunk to the CDN (rebuilds KV manifest, purges cache)

shipeasy i18n publish [options]

Option		Description
`--profile <name>`	required	Profile name (e.g. 'default')
`--chunk <name>`	optional	Chunk to publish (default: `"default"`)
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Publish the default chunk
shipeasy i18n publish --profile en:prod

# Publish a specific chunk
shipeasy i18n publish --profile fr:prod --chunk marketing

`shipeasy i18n validate`

Check that all t('key', …) references in code exist on the server

shipeasy i18n validate [options] [paths...]

Argument		Description
`paths...`	optional	—

Option		Description
`--profile <name>`	optional	Restrict the check to a single profile
`--json`	optional	Output as JSON
`--project <id>`	optional	Project ID override

Examples:

# Check all t('key') refs exist server-side
shipeasy i18n validate ./src

# Restrict the check to one profile
shipeasy i18n validate ./src --profile en:prod

`shipeasy i18n profiles`

Manage i18n locale profiles

shipeasy i18n profiles [options] [command]

codemod

Source-code codemods (i18n extraction, framework migrations)

`shipeasy codemod i18n`

Extract translatable strings and wrap them with i18n.t() from @shipeasy/sdk/client. Reads .i18n-codemod.json from the current directory if present.

shipeasy codemod i18n [options] [target]

Argument		Description
`target`	optional	—

Option		Description
`--config <path>`	optional	Path to a JSON config file
`--dry-run`	optional	Preview without writing files
`--verbose, -v`	optional	Detailed per-file output
`--type <name>`	optional	Run only one extraction type (jsx-text, jsx-attr, template-literal, ...)
`--migrate <name>`	optional	Run a migration plugin (react-i18next, react-intl, lingui, next-intl, raw-i18next)

Examples:

# Preview extraction over app/
shipeasy codemod i18n app --dry-run

# Run only JSX text extraction
shipeasy codemod i18n ./src --type jsx-text

# Migrate from react-i18next
shipeasy codemod i18n --migrate react-i18next

mcp

Manage the Shipeasy MCP server in AI-assistant configs

`shipeasy mcp install`

shipeasy mcp install [options]

Option		Description
`--client <name>`	optional	Restrict to one client (claude \| cursor \| windsurf \| all) (default: `"all"`)
`--scope <scope>`	optional	user \| project (default: `"user"`)
`--force`	optional	Replace an existing 'shipeasy' MCP entry without prompting
`--dry-run`	optional	Print what would change without writing files

Examples:

shipeasy mcp install

# only Claude, project config
shipeasy mcp install --client claude --scope project

# preview a forced replace
shipeasy mcp install --force --dry-run

`shipeasy mcp status`

Show which AI-assistant configs have a Shipeasy MCP entry

shipeasy mcp status [options]

Examples:

shipeasy mcp status

`shipeasy mcp start`

Run the Shipeasy MCP stdio server (forwards to @shipeasy/mcp)

shipeasy mcp start [options]

Examples:

# stdio server an assistant launches
shipeasy mcp start

`shipeasy mcp uninstall`

Remove the 'shipeasy' MCP entry from AI-assistant configs

shipeasy mcp uninstall [options]

Option		Description
`--client <name>`	optional	Restrict to one client (default: `"all"`)
`--scope <scope>`	optional	user \| project \| both (default: `"both"`)

Examples:

shipeasy mcp uninstall

shipeasy mcp uninstall --client cursor --scope user

CLI reference

On this page