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 pickershipeasy login# Re-authenticate over a live sessionshipeasy login --force# Scope to one project explicitlyshipeasy login --project proj_abc123# CI: env credentials act as the session, so this is a no-opSHIPEASY_CLI_TOKEN=… SHIPEASY_PROJECT_ID=… shipeasy login
Print the project root — the nearest .shipeasy dir (walks up from cwd, like .git)
The project root is the folder that holds .shipeasy, found by walking up from the cwd (like git finds .git). The nearest file wins, so a subproject's own .shipeasy shadows any ancestor and the walk stops there — one .shipeasy per project. Use this instead of git rev-parse --show-toplevel when you need the Shipeasy project boundary: it respects a subproject root and never overshoots to the git root above it. Exits non-zero (with guidance) when nothing is bound.
shipeasy root [options]
Option
Description
--json
optional
Output the resolved root as JSON
Examples:
# print the nearest .shipeasy dirshipeasy root# root + project_id + sdk, machine-readableshipeasy root --json# cd to the project rootcd "$(shipeasy root)"
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Event name. Starts with a letter, digit, or _; letters, digits, _, -, .; max 50 characters. The cap is the Analytics Engine index budget — 96 bytes total, less a 36-byte project UUID and a separator — and the API has always enforced 50 while this spec advertised 128. The charset is ASCII, so characters and bytes are the same count. Immutable after create — this is the handle metric queries reference.
Option
Description
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--description <value>
optional
Optional human-readable description of the event.
--properties <value>
optional
Typed properties declared on the event. Defaults to an empty list.
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Stable metric key. Single segment or folder.name; lowercase letters, digits, _/-; max 128 chars.
Option
Description
--display-name <value>
optional
What a human calls the metric — "Checkout revenue" beside the checkout.revenue that identifies it. Unlike name it is free text, it is editable, and nothing addresses the metric by it: the dashboard leads with it and falls back to name when it is absent, so a metric nobody named simply reads as its key. Send null to clear it.
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--event-name <value>
optional
Source event the query reads from.
--query <value>
optional
Metric query DSL string, e.g. sum(purchase, amount). The alternative to query_ir. Every label the query references — in filters, the value position, by (…), or without (…) — must exist as a property on the tracked event's payload; a query over a label the event never carries validates fine but returns empty results.
--winsorize-pct <value>
optional
Winsorise percentile (1–99) to clamp outliers. Defaults to 99.
--default-min-effect-of-interest <value>
optional
Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with min_effect_of_interest when a specific decision has a different cost/risk bar. null to omit.
--direction <value>
optional
Desired direction of movement. higher_better (default), lower_better, or neutral (guardrail).
--unit <value>
optional
Display unit (e.g. ms, %, $), or null when unitless.
--display <value>
optional
How the metric's series is DRAWN, as opposed to what it measures. Both parts used to be DSL functions (expected(q, seasonal), forecast(q, …)), which meant turning a band on minted a different metric; they are properties now, so every chart of the metric picks them up and nothing that JUDGES the metric — an alert rule, the experiment analyzer — reads them at all.
--query-ir <value>
optional
A metric definition as a typed expression tree — the structured alternative to the query DSL string, and what the API stores. Exactly one of query / query_ir is supplied per metric body; query is the same definition written as text, and is the spelling to prefer.
Stable opaque metric id (met_…) or the metric's name.
Option
Description
--display-name <value>
optional
What a human calls the metric — "Checkout revenue" beside the checkout.revenue that identifies it. Unlike name it is free text, it is editable, and nothing addresses the metric by it: the dashboard leads with it and falls back to name when it is absent, so a metric nobody named simply reads as its key. Send null to clear it.
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--event-name <value>
optional
Source event the query reads from.
--query <value>
optional
Metric query DSL string, e.g. sum(purchase, amount). The alternative to query_ir. Every label the query references — in filters, the value position, by (…), or without (…) — must exist as a property on the tracked event's payload; a query over a label the event never carries validates fine but returns empty results.
--winsorize-pct <value>
optional
Winsorise percentile (1–99) to clamp outliers. Defaults to 99.
--default-min-effect-of-interest <value>
optional
Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with min_effect_of_interest when a specific decision has a different cost/risk bar. null to omit.
--direction <value>
optional
Desired direction of movement. higher_better (default), lower_better, or neutral (guardrail).
--unit <value>
optional
Display unit (e.g. ms, %, $), or null when unitless.
--display <value>
optional
How the metric's series is DRAWN, as opposed to what it measures. Both parts used to be DSL functions (expected(q, seasonal), forecast(q, …)), which meant turning a band on minted a different metric; they are properties now, so every chart of the metric picks them up and nothing that JUDGES the metric — an alert rule, the experiment analyzer — reads them at all.
--query-ir <value>
optional
A metric definition as a typed expression tree — the structured alternative to the query DSL string, and what the API stores. Exactly one of query / query_ir is supplied per metric body; query is the same definition written as text, and is the spelling to prefer.
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Human label for the rule, shown on the alert and the rules list.
--metric-id <value>
optional
Id of the metric to evaluate.
--kind <value>
optional
What the rule watches for. normal compares the metric's own value — against threshold via comparator, or against the [rangeMin, rangeMax] corridor it must stay inside. anomaly compares it against its own seasonal baseline in sigmas: the same fit a chart draws as the band, so a point outside the drawn band is exactly a breaching bucket, and one metric can back rules at several sigmas. outliers compares each by() group against its peers in the same bucket and is refused on a metric with no grouping.
--comparator <value>
optional
How the metric value is compared to the threshold. Read only by a normal rule with no range set.
--threshold <value>
optional
Threshold the metric value is compared against. Required for a normal rule unless a range is given; ignored by every other kind.
--range-min <value>
optional
Lower edge of the corridor the metric must stay inside. Setting either bound switches a normal rule off comparator/threshold and onto the range, which breaches on LEAVING it in either direction. One bound alone is a one-sided range.
--range-max <value>
optional
Upper edge of the corridor the metric must stay inside.
--sigma <value>
optional
How far from normal is too far, for anomaly and outliers, in sigma-equivalents. Omit (or null) for 3, which is also the half-width of the band a chart draws — so an unconfigured rule fires exactly where the picture says it would.
--direction <value>
optional
Which side of the baseline an anomaly or outliers rule watches. Omit (or null) for either, which is what "is this unusual" means; name a side for a metric that is only bad in one direction.
--sustained <value>
optional
Judge the window by ACCUMULATED departure instead of bucket by bucket. The ordinary check asks every bucket to be past sigma, which a slow regression never manages: a metric running 1.5σ worse than normal since Tuesday puts no single bucket past 3σ and pages nobody. A sustained rule adds up each bucket's excess over half a sigma and fires once the total passes twice sigma — four buckets at 2σ do it, a lone 3σ spike does not. anomaly and outliers only, and refused alongside requiredBuckets: the accumulated bar IS the evidence bar, and a second one counted in buckets would silently override it.
--window-hours <value>
optional
Lookback window (hours) the metric is aggregated over. 1–720.
--bucket-minutes <value>
optional
Width of the buckets the window is split into, in minutes. Omit (or null) to divide the window into 12 equal buckets. The rule is judged per bucket, so this is the resolution at which "sustained" is measured — a short bucket asks the condition to hold through finer detail.
--required-buckets <value>
optional
How many buckets must breach before the rule fires. Omit (or null) to require every bucket that had data. Buckets with nothing in them are excluded before this is counted, so on a sparse metric null can mean a single bucket — set this to 2 or more where one lone sample must never page.
--warn-threshold <value>
optional
The milder bound — a second level, in the same unit the kind judges in, that raises a quieter alert before the firing level is reached. Must be strictly milder than the level the rule fires at, or it could never fire on its own. Refused on a range rule and on a sustained one: neither condition is a single number, so there is nothing to substitute.
--recovery-threshold <value>
optional
What the metric must get back to before a live alert closes. Without it a metric sitting on its threshold pages and clears once per tick. Must be on the safe side of the firing level, or equal to it. Omit (or null) for no hysteresis.
--group-alerts <value>
optional
Fire one alert per by() group instead of one for the whole metric. The firing key becomes (rule, group), so each group raises, dedupes and recovers on its own. Refused on a metric with no by(), and on no_data — a group that went silent has no rows left to be missing from.
--max-groups <value>
optional
How many groups this rule may alert on at once. Omit (or null) for 10. Past the cap the worst groups fire and the count of the rest is stated on each ticket — a group set is customer data, and an uncapped rule on by(user_id) would file a ticket per user.
--no-data-minutes <value>
optional
For a no_data rule: how long the silence must last. Omit (or null) for 15 minutes. Five is the floor — below it, ordinary ingest lag empties the trailing bucket and reads as an outage.
--delay-minutes <value>
optional
Hold the evaluated window back this far behind live, on top of the reader's own settle grace. For a metric assembled from a source that lands in batches, whose trailing buckets are legitimately incomplete for longer than the grace covers.
--auto-resolve-minutes <value>
optional
Close a live instance that has gone this long without a fresh verdict. A rule that cannot reach a verdict deliberately leaves its alert alone, which is right for a tick and wrong for a week. Never closes an instance that is currently breaching. Omit (or null) to never auto-resolve.
--composite <value>
optional
What a composite rule is a boolean over. rules are sibling alert-rule ids in the same project and op is how their states combine. A child's state is what the current pass concluded about it, falling back to whether it has an open instance — so a composite still means something on a tick where a child could not be evaluated, which is exactly the tick a "two of these are broken at once" rule is for. One level deep: a child may not itself be composite.
--severity <value>
optional
Severity of the raised alert. A warnThreshold breach opens one step quieter than this.
--enabled <value>
optional
Whether the rule is evaluated by the cron.
--notify <value>
optional
Delivery target for a notification; null = use the project default.
Stable opaque alert-rule id (ar_…) or the rule's name.
Option
Description
--name <value>
optional
—
--kind <value>
optional
—
--comparator <value>
optional
—
--threshold <value>
optional
—
--range-min <value>
optional
Lower edge of the corridor; null drops it, returning the rule to comparator and threshold when both bounds are gone.
--range-max <value>
optional
Upper edge of the corridor; null drops it.
--sigma <value>
optional
Sigmas an anomaly or outliers rule fires at; null restores the default of 3.
--direction <value>
optional
Which side an anomaly or outliers rule watches; null restores either.
--sustained <value>
optional
Judge the window by accumulated departure rather than bucket by bucket. anomaly and outliers only; refused alongside requiredBuckets.
--warn-threshold <value>
optional
The milder bound; null drops the warning level, leaving the rule with one.
--recovery-threshold <value>
optional
What the metric must get back to before a live alert closes; null drops the hysteresis.
--group-alerts <value>
optional
Fire one alert per by() group. Refused on a metric with no grouping.
--max-groups <value>
optional
How many groups may alert at once; null restores the default of 10.
--no-data-minutes <value>
optional
How long a no_data rule's silence must last; null restores 15 minutes.
--delay-minutes <value>
optional
How far behind live the window is held; null drops the delay.
--auto-resolve-minutes <value>
optional
Close a stale live instance after this long; null never auto-resolves.
--composite <value>
optional
What a composite rule is a boolean over. rules are sibling alert-rule ids in the same project and op is how their states combine. A child's state is what the current pass concluded about it, falling back to whether it has an open instance — so a composite still means something on a tick where a child could not be evaluated, which is exactly the tick a "two of these are broken at once" rule is for. One level deep: a child may not itself be composite.
--window-hours <value>
optional
—
--bucket-minutes <value>
optional
Bucket width in minutes; null restores the default 12 buckets per window.
--required-buckets <value>
optional
Buckets that must breach to fire; null restores "every bucket that had data".
--severity <value>
optional
—
--enabled <value>
optional
—
--notify <value>
optional
Delivery target for a notification; null = use the project default.
Per-project item number (e.g. 7) or the full ops item id.
Option
Description
--body <value>
optional
The comment body as markdown. Mentions (@teammate, @shipeasy) are parsed from it.
--parent-id <value>
optional
Reply under this top-level comment. Omit / null for a top-level comment. Replying to a reply attaches to the same top-level parent (threading is one level deep).
Stable opaque instance id — the same id as the alert ops item this instance is.
Option
Description
--status <value>
optional
New lifecycle state, written through to the queue item (resolved / wont_fix / open). resolved / dismissed stamp their timestamp; active re-opens and clears both.
--assignee-id <value>
optional
PERSON owner — a users.id, or null to clear the assignment.
--agent <value>
optional
AGENT owner — a connected trigger connector's id (connectors.id), the built-in "jarvis" (Enterprise plan only — rejected with 403 otherwise), or null to clear. Stored in assigneeConnectorId or assigneeAgent depending on the value; the two are mutually exclusive.
Investigation records on a queue item — the structured, read-only write-ups an AI agent produces while working it (findings / a blocking question / QA notes), plus the working run rows an ack or an AI hand-off opens.
Recurring coding-agent triggers: the scheduled, unattended runs that burn down the ops queue in --pr mode (one PR per fixed item; nothing auto-merges).
Register a Claude Code scheduled routine as the trigger connector
shipeasy ops trigger create claude [options]
Option
Description
--name <value>
optional
Human-readable connector label.
--events <value>
optional
Events that auto-fire the routine. Defaults to empty so the trigger does not auto-fire paid runs until events are subscribed.
--config <value>
optional
Non-secret config for a Claude trigger.
--token <value>
optional
The routine's fire bearer token (secret). Optional — a tokenless trigger is recorded but not fireable until a token is added later. Encrypted into the credentials cipher; never persisted in config or returned.
Register a Cursor cloud-agent trigger (cold-fire; Shipeasy launches the run)
shipeasy ops trigger create cursor [options]
Option
Description
--name <value>
optional
Human-readable connector label.
--events <value>
optional
Events that auto-fire a cold cloud-agent run. Defaults to empty.
--config <value>
optional
Non-secret config for a Cursor trigger.
--api-key <value>
optional
Cursor API key that launches the run (secret). Encrypted into the credentials cipher; never returned.
--ops-key <value>
optional
Restricted Shipeasy ops key (secret). Sent as the Bearer for the Shipeasy MCP server handed to each run inline — never in the prompt text or the run env. Encrypted; never returned.
Events that auto-fire a Copilot agent task. Defaults to empty.
--config <value>
optional
Non-secret config for a Copilot trigger.
--token <value>
optional
Copilot-licensed user PAT (secret). The ops key lives in the repo's GitHub "Agents" secret store and is never sent through Shipeasy. Encrypted; never returned.
Mint the ops key + emit the RemoteTrigger create body for the agent to run
Does the Shipeasy-side prep for a recurring trigger and emits the exact RemoteTrigger create body. It mints a restricted ops key (embedded in the routine prompt — the only hands-off channel, since routine env vars are UI-only), resolves the repo (origin remote) and cron (--frequency), and writes the body to a 0600 temp file (the key is never printed). It does NOT create the routine — the agent does, via the in-process RemoteTrigger tool, because the routines API token is not exposed to a standalone CLI.
Filter by item type, or all (the default). Every type a returned item can carry is filterable, including the auto-filed ones.
--status <value>
optional
Filter by lifecycle status, or all (the default). The human-gated holding state (pending_approval) is excluded from all/default and returned only when requested as the exact status.
--limit <value>
optional
Max items to return (1–500). Defaults to 200.
--owner <value>
optional
Narrow to items owned by one person OR one agent. Matches a person by users.id, email, or display name, and an agent by connector id, display name, or kebab-case handle — e.g. owner=Claude or owner=alice@acme.dev. Case-insensitive exact match, applied over the returned page.
Per-project item number (e.g. 7) or the full ops item id.
Option
Description
--title <value>
optional
New bug title (no leading/trailing whitespace).
--steps-to-reproduce <value>
optional
Updated reproduction steps.
--actual-result <value>
optional
Updated actual result.
--expected-result <value>
optional
Updated expected result.
--status <value>
optional
Lifecycle status of a queue item. The working flow is open → in_progress → ready_for_qa → resolved (or wont_fix, terminal from any earlier stage). blocked marks an item that can't progress until an external dependency clears — a working state a human sets and clears. ready_for_qa is what a developer sets once a fix lands; resolved is the QA sign-off, normally flipped in the dashboard after verification — set it directly from code only when the fix has been verified end-to-end. investigating_by_ai is a system-owned display state — set when the AI agent (Jarvis) picks an item up to investigate, never chosen by a human — so it is shown but not offered as a manual choice. pending_approval is the one human-gated holding state: it parks an item OUT of the work queue until a human promotes it to open in the dashboard, so GET /api/admin/ops excludes it under status=all/default and returns it only when requested as an exact status. It covers untriaged inbound that must never be auto-implemented — connector requests filed from a customer's connectors panel, and questions funnelled in from the "Stuck in onboarding?" assistant — where approving means flipping the status to open. Two earlier values were removed in favour of this single gate: triage (the onboarding-help bucket, now pending_approval) and triaged (a redundant "looked at but not started" step, now plain open).
--priority <value>
optional
Triage priority, or null when not set (in an update, null clears it).
--github-pr-number <value>
optional
Link (or, when null, unlink) a GitHub pull request to this bug.
--notify <value>
optional
Where this item's completion notification lands, or null.
Per-project item number (e.g. 7) or the full ops item id.
Option
Description
--agent <value>
optional
The AI agent type acking on the item's behalf — pass your own type when you are a coding agent (Claude Code passes claude, Cursor cursor, Copilot copilot, Jules/Gemini jules). Omit entirely for a human ack by the authenticated caller.
--session-id <value>
optional
The agent-run session id (e.g. Claude's session_01…), so the dashboard can deep-link to the exact run page. Omit when the harness has no session id.
One sentence: why it can't be fixed in code. Renders markdown.
--steps <value>
optional
Ordered steps the human should take to unblock — self-contained (the human reads only this card, not the agent's transcript), 3–6 steps, each naming the exact file, command, env var, or dashboard page. Renders markdown.
--href <value>
optional
Dashboard-relative deep link to the related item. null is accepted and treated as "no link".
--dedupe-key <value>
optional
Stable per-escalation key (e.g. feedback:7) so re-runs dedupe to one row.
Lowercase bare hostname (e.g. acme.com, app.acme.com, *.acme.com), or * to allow any origin. Full URLs with https:// are not accepted. The project is keyed by (owner_email, domain), so a second call with the same domain returns the existing project.
--name <value>
optional
Human-readable project name. Defaults to the domain on first create.
Stable opaque project id. Must match the caller's own project.
Option
Description
--name <value>
optional
New project name.
--domain <value>
optional
Lowercase bare hostname (e.g. acme.com, app.acme.com, *.acme.com), or * to allow any origin. Full URLs with https:// are not accepted. The project is keyed by (owner_email, domain), so a second call with the same domain returns the existing project.
--slug <value>
optional
URL-safe identifier used in app URLs and SDK config. Lowercase letters, numbers, and hyphens; 2–48 chars; cannot start or end with a hyphen. The caller lowercases the raw slug before sending.
--default-env <value>
optional
Default environment new resources are scoped to.
--timezone <value>
optional
IANA timezone the project's daily analysis runs in.
--stat-method <value>
optional
Statistical method the experiment analyzer uses.
--sig-threshold <value>
optional
Significance threshold (alpha) for experiment analysis.
--auto-rollback <value>
optional
Whether a failing guardrail auto-rolls back the experiment.
--min-sample-days <value>
optional
Minimum number of days an experiment must run before it can be called.
--module-translations <value>
optional
Enable/disable the i18n/translations module.
--module-configs <value>
optional
Enable/disable the dynamic-configs module.
--module-gates <value>
optional
Enable/disable the feature-gates module.
--module-experiments <value>
optional
Enable/disable the experiments module.
--module-feedback <value>
optional
Enable/disable the feedback/ops module.
--module-user <value>
optional
Enable/disable the user-management module.
--module-events <value>
optional
Enable/disable the events module.
--min-sample-size <value>
optional
Verdict power guard — minimum users per arm before a ship/hold verdict.
--min-runtime-days <value>
optional
Minimum days an experiment must run before a verdict (peeking guard).
--default-power <value>
optional
Target statistical power (1−β) feeding the realized-MDE calculation.
--ci-confidence <value>
optional
Confidence level for the interval surfaced on results (any value in [0.5, 0.999], e.g. 0.90, 0.95, 0.975, 0.99).
--default-allocation-pct <value>
optional
Default traffic allocation (basis points, 1000 = 10%) new experiments start with; overridable per experiment.
--default-holdout <value>
optional
Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
--default-winsorize-pct <value>
optional
Default winsorization percentile new metrics start with; overridable per metric.
--default-mei <value>
optional
Default minimum effect of interest (relative, 0–1) new metrics start with; overridable per metric and per experiment. Null clears it.
--cuped-baseline-days <value>
optional
CUPED baseline window — days of pre-experiment history, frozen at start.
--cuped-min-overlap <value>
optional
CUPED selection-bias guard — min share of users with a baseline, else skip.
--cuped-min-baseline-users <value>
optional
CUPED — minimum users with a baseline before it runs at all.
--msprt-tau-mei-factor <value>
optional
mSPRT prior width — τ = minimum effect of interest × this factor.
--msprt-tau-sd-factor <value>
optional
mSPRT fallback prior width — τ = this × control SD when no MEI is set.
--srm-threshold <value>
optional
SRM chi-square p-value below which the run is called invalid.
--error-autoclose-days <value>
optional
Days an open tracked error may go unseen before the nightly sweep auto-resolves it. 0 disables auto-close for this project.
--error-ticket-min-occurrences <value>
optional
Occurrence count a tracked error must cross before an error ticket is auto-filed into the ops queue. Requires a paid plan — the request is rejected with 403 on a plan without the ops_auto_error_issues entitlement.
Opaque cursor returned in the previous page's next_cursor. Omit for the first page.
--q <value>
optional
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Stable config/killswitch key in folder.name form (two lowercase segments separated by a dot, e.g. pricing.tiers). Immutable after create.
Option
Description
--description <value>
optional
Optional free-form description shown in the dashboard. Max 512 chars.
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--schema <value>
optional
JSON Schema (draft 2020-12) describing the shape of the config value. Top-level type must be 'object'; every published value is validated against this schema.
--value <value>
optional
Initial config value. Either a single JSON object applied to every env, or a { env: value } map seeding per-env values. Must match schema. Defaults to {} on every env when omitted.
--dev <value>
optional
Seed the dev env's initial value (version 1), overriding value for dev. Published immediately. Must match schema.
--staging <value>
optional
Seed the staging env's initial value (version 1), overriding value for staging. Published immediately. Must match schema.
--prod <value>
optional
Seed the prod env's initial value (version 1), overriding value for prod. Published immediately. Must match schema.
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
--query <value>
optional
Deprecated alias for q, kept working for one release. Prefer q.
Opaque cursor returned in the previous page's next_cursor. Omit for the first page.
--q <value>
optional
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Stable gate key used by SDKs (Shipeasy.checkGate(user, '<name>')). Single segment or folder.name. Lowercase letters, digits, _ or -; max 128 chars. Immutable after create — rename = delete + recreate.
Option
Description
--type <value>
optional
Gate kind. targeting (default) is a normal flag with the full builder. holdout is a restricted flag — only a public rollout % and a whitelist are allowed; attribute rules and a gatekeeper stack are rejected. Used as an experiment's holdout_gate.
--enabled <value>
optional
Master switch. Defaults to true. Set false to create the gate disabled (evaluates to false regardless of rules/rollout); flip on via POST /{id}/enable or PATCH.
--rollout-pct <value>
optional
Initial rollout in basis points (0–10000 = 0%–100%) — 100 here means 1%, not 100%. Use rollout_percent (0–100) below if you'd rather think in percent. Use 0 to create the gate dark and ramp via PATCH after deploy validation.
--rollout-percent <value>
optional
Initial rollout as a percentage (0–100, fractional ok). Friendlier alias for rollout_pct; converted internally to basis points (e.g. 100 here = 10000 bp = 100%). If both rollout_pct and rollout_percent are set, rollout_percent wins.
--rules <value>
optional
Targeting predicates. AND-combined. If non-empty, the gate returns true only for callers that satisfy every rule and fall under rollout_pct.
--salt <value>
optional
Hash salt for percentage bucketing. Auto-generated if omitted. Provide explicitly to keep a gate's buckets stable across delete/recreate. Immutable after create — there is no PATCH for salt because changing it would re-bucket every caller.
--stack <value>
optional
Optional gatekeeper stack. When provided, takes precedence over rules + rollout_pct at evaluation time. Omit (or pass null) for a flat gate.
--title <value>
optional
Human-readable title shown in the dashboard. Free-form, no key format constraint.
--description <value>
optional
Long-form description / runbook. Markdown is rendered in the dashboard.
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--group <value>
optional
Group label for dashboard organisation (e.g. team or product area).
--owner-email <value>
optional
Owner contact. Displayed verbatim; not used for auth.
Gate kind. Switching to holdout requires the gate carry only a public rollout % + whitelist (attribute rules / stack are rejected).
--rollout-pct <value>
optional
New rollout in basis points (0–10000 = 0%–100%) — 100 here means 1%. Use rollout_percent (0–100) below for percent. Omit both to leave unchanged.
--rollout-percent <value>
optional
New rollout as a percentage (0–100). Friendlier alias for rollout_pct; converted internally. Wins over rollout_pct if both are supplied. Omit both to leave unchanged.
--rules <value>
optional
Replaces the rule list wholesale. To add a value to an in rule, send the full new rules array with the augmented value (e.g. previous ['US','CA'] → ['US','CA','GB']).
--enabled <value>
optional
Master switch. false makes the gate evaluate to false for every caller regardless of rollout_pct, rules, or stack — use as kill switch.
--stack <value>
optional
Replaces the gatekeeper stack wholesale. Send null to revert to flat rules + rollout_pct evaluation.
--title <value>
optional
Human-readable title shown in the dashboard. Free-form, no key format constraint.
--description <value>
optional
Long-form description / runbook. Markdown is rendered in the dashboard.
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--group <value>
optional
Group label for dashboard organisation (e.g. team or product area).
--owner-email <value>
optional
Owner contact. Displayed verbatim; not used for auth.
Stable opaque gate id (gate_…) or the gate's name.
Option
Description
--attr <value>
optional
Identity attribute to match on. Only honoured when the gate has no whitelist yet (this call creates it); passing an attribute that disagrees with an existing whitelist is a 409 rather than a silent re-key of the entries already there.
--entries <value>
optional
Identities to admit. Already-listed entries are skipped, so the call is idempotent.
Opaque cursor returned in the previous page's next_cursor. Omit for the first page.
--q <value>
optional
Case-insensitive substring filter across the resource's human-readable text columns (e.g. name, title, description). OR-matched across those columns; omit to return everything.
Stable opaque killswitch id (ksw_…) or the killswitch's name.
Option
Description
--switch-key <value>
optional
Which target to flip. Omit (or null) to flip the killswitch's own flat value; name a switch key to flip that nested sub-switch instead, creating the entry if it doesn't exist yet.
--value <value>
optional
The value to publish. Omit (or null) to flip whatever is stored now — read-modify-write in one call. Pass an explicit true/false to make the call idempotent, so a retry can't undo the first attempt.
--env <value>
optional
Environment to publish on. Defaults to prod — the environment an incident response means when it says "kill it".
One-command onboarding for this repo. Logs you in and binds a project, detects and wires your coding agents (Claude Code plugin, or MCP + instruction files for Cursor/Codex/Copilot/Antigravity/Gemini), mints SDK keys, installs @shipeasy/sdk, and offers the devtools overlay + feature modules — then writes self-contained SDK-wiring steps to shipeasy-wiring.md for your agent to finish. Monorepo-aware and idempotent (safe to re-run). Run shipeasy setup --help for every flag; shipeasy setup triggers sets up the scheduled queue-fixing automation on its own.
setup now runs the whole deterministic half of onboarding itself, without needing an AI to drive it:
detect-powered monorepo scan; every target gets its own .shipeasy.
Browser login, then binds the repo root AND each install target.
Wires your coding agents — each through its own mcp add --transport http command where one exists (Claude, Copilot, Codex), else a merged config file — plus instruction files + universal AGENTS.md, installed in-repo by default (confirms interactively; offers user-global). At project scope even Claude stays in-repo (.mcp.json + ./.claude/skills); user scope takes the native Claude plugin. Base workflow skills go to every non-plugin agent via npx skills add.
Mints env-locked server/client SDK keys.
Runs the SDK package install per target and persists the keys to each target's gitignored env file.
6-7. Offers devtools — the browser <script> overlay, or, for a React Native/Expo target, installs @shipeasy/react-native-devtools (+ its Expo peers) for the shake-to-open on-device panel; the surface comes from step 1's detection, not a question. Then the feature module enables (flags/i18n/ops).
Verification gate — session, keys, and every target's binding.
Trusts the folder in Claude when its .mcp.json server is still pending — opens one interactive session prefilled with /exit, so it closes itself the moment you accept the prompt.
Authorizes the hosted MCP connection: entries written to a config that is private to your machine carry an Authorization: Bearer header (your CLI session key) and need no sign-in at all — which is why Copilot's entries go to its CLI config and VS Code's user profile, not the repo. Committable ones (.mcp.json, .cursor/mcp.json) never hold a credential, so those take the OAuth browser flow via each agent's own mcp login.
Everything that needs codebase judgement (entry-point configure(...) wiring, idiomatic secret stores, overlay script injection) is written to shipeasy-wiring.md — complete, self-contained instructions any coding agent (Claude, Codex, Cursor, Copilot, or a human) can execute. Key values never appear in that file. Alongside it, the SDK doc pages for exactly what you enabled — installation always, plus the overlay, head-tag, flag, experiment, metrics, error and i18n pages you turned on — are pulled from each SDK's live docs into shipeasy-wiring-docs/ and linked from the step that needs them, so the wiring an agent writes tracks the SDK as it ships today rather than whatever this CLI version remembers. Both are temporary — once every gate passes the agent asks whether to delete them and commit the wiring, and does neither unless you say yes.
Offers to bootstrap the instrumentation a module enable can't produce on its own: with ops on, a session that finds this app's real failure paths and reports them through see(); with the release module on, one that names the product's critical moments and builds the event → metric → alert chain over them. Runs on your own harness with a written brief (skills, gates, and a stop-before-commit rule); --no-bootstrap skips it.
Offers the automation trigger (scheduled queue burn-down as PRs).
Opens the browser on the plan step — the two things setup will not decide for you: which plan you're on, and the Terms/Privacy agreements. Free needs no card; Pro/Business start a 14-day trial through Stripe. Completing that screen is what marks onboarding done for the account (an account that already finished it lands on Settings → Billing instead); --no-plan skips it.
Idempotent — safe to re-run. In CI (non-TTY) it runs non-interactively with SHIPEASY_CLI_TOKEN + SHIPEASY_PROJECT_ID.
shipeasy setup [options] [command]
Option
Description
--yes
optional
Non-interactive: accept defaults everywhere (bind, prod keys, run installs)
--agents <list>
optional
Comma list to wire (claude,cursor,codex,copilot,antigravity,gemini)
--domain <domain>
optional
Production domain (used when creating a new project at login)
--scope <scope>
optional
MCP + skills scope: project (in-repo, default) | user (global). Omit to be asked.
--env <env>
optional
Environment the minted SDK keys read: dev | staging | prod
--devtools
optional
Enable devtools without asking (browser <script> and/or the React Native overlay, per detection)
--no-devtools
optional
Skip devtools without asking
--features <list>
optional
Module groups to enable non-interactively (flags,i18n,ops)
--skip-install
optional
Don't run SDK package installs (they go into the wiring steps)
--no-agent-run
optional
Don't offer to launch a coding agent on the wiring steps
--no-bootstrap
optional
Skip the instrumentation session (see() error tracking + events/metrics/alerts)
--no-claude-run
optional
(deprecated) alias of --no-agent-run
--triggers
optional
Set up the automation trigger without asking (skips the yes/no gate)
--no-triggers
optional
Skip the automation trigger step
--trigger-platform <id>
optional
Preselect the trigger platform (claude|codex|cursor|copilot|gemini|jules)
--plan
optional
Open the plan step without asking (skips the yes/no gate)
--no-plan
optional
Skip the plan step (onboarding stays unfinished until it's done)
--dry-run
optional
Show what would change without writing files or calling the API
Examples:
# interactive: full onboarding, prompts as it goesshipeasy setup# non-interactiveshipeasy setup --yes --env prod --features flags# preview without writingshipeasy setup --dry-run --no-agent-run# subset, skip overlayshipeasy setup --agents claude,cursor --no-devtools
Set up an automation trigger — a scheduled agent that fixes queue items as PRs, unattended. Opens the hosted, guided setup for your platform.
A trigger is a scheduled agent run that burns down your feedback queue (bugs, feature requests, auto-filed error/alert tickets) and opens one pull request per fixed item — nothing merges without you. This command explains it, has you pick the platform you code with (Claude Code, Codex, Cursor, Copilot, or Gemini/Jules), then opens the hosted, guided setup wizard preselected to that platform, which walks you through the platform-specific fields and secrets. shipeasy setup offers this same step inline.
shipeasy setup triggers [options]
Option
Description
--platform <id>
optional
Preselect the platform (claude|codex|cursor|copilot|gemini|jules)
--dry-run
optional
Print the URL without opening a browser
Examples:
# interactive: pick a platform, open the wizardshipeasy setup triggers# preselect Claude Codeshipeasy setup triggers --platform claude# just print the URLshipeasy setup triggers --dry-run
File a setup/onboarding bug to Shipeasy (filed as pending-approval). Meant for the setup agent when a step fails: it collects OS/Node/CLI version, your project id, language and frameworks, plus the failing step + error. REQUIRES the user's consent — pass --consent (agent, after asking) or answer the interactive prompt. Prints the exact payload first.
shipeasy report-issue [options]
Option
Description
--title <title>
required
One-line summary, e.g. "Setup failed at Feature installs"
--step <step>
optional
Which setup step failed
--error <error>
optional
The error message / actual result
--description <text>
optional
Freeform description of the problem
--reporter-email <email>
optional
Optional contact email
--project <id>
optional
Shipeasy project id the issue relates to (defaults to the bound one)
--language <lang>
optional
Detected language (typescript, python, …)
--frameworks <list>
optional
Comma list of detected frameworks
--consent
optional
Confirm the USER agreed to send system/env info to Shipeasy. Required to send unattended.
--json
optional
Print the exact payload and exit WITHOUT sending (dry preview)
Examples:
# agent files a report after the user agreedshipeasy report-issue --consent --title "Setup failed at Feature installs" --step "Feature installs" --error "enableModuleGroup(ops) 500"# preview the exact payload without sendingshipeasy report-issue --title "Setup broke" --error "..." --json
Bring your Shipeasy install up to date: self-updates the CLI, refreshes the coding-agent wiring (Claude plugin / MCP registration) and the how-to skills from the marketplace, and offers to bump the @shipeasy/sdk dependency in each onboarded target. Idempotent and best-effort. Use shipeasy upgrade skills for the CLI + skills only.
upgrade refreshes everything a Shipeasy install accumulates, in order:
CLI — installs @shipeasy/cli@latest globally (npm by default; --pm for pnpm/yarn/bun). The new version applies to your NEXT command, not the running one.
Skills — re-fetches the marketplace how-to skills from the repo and reinstalls them into your wired agents. Claude at user scope refreshes the native plugin (MCP + skills + slash commands in one); every other agent (and Claude in-repo) reinstalls via skills add. The WHOLE catalogue is installed — skills added to the library since your last setup land here, not just newer bytes for what you already have (--only-installed keeps it to what's on disk).
MCP — re-asserts the hosted MCP registration (mcp.shipeasy.ai is a static remote, so there's nothing to bump — this just repairs a stale/local entry).
SDK — detects each onboarded target and OFFERS to bump @shipeasy/sdk to its latest release (prompted; --yes accepts, --skip-sdk skips).
Scope and agents auto-detect from the repo; override with --scope / --agents. shipeasy upgrade skills runs only steps 1–2.
shipeasy upgrade [options] [command]
Option
Description
--agents <list>
optional
Restrict to these agents (claude,cursor,codex,copilot,antigravity,gemini)
--scope <scope>
optional
Where skills/MCP live: project | user (default: auto-detected)
--pm <pm>
optional
Package manager for the global CLI update (npm|pnpm|yarn|bun)
--skip-cli
optional
Don't self-update the CLI
--skip-sdk
optional
Don't offer the SDK dependency update
--only-installed
optional
Refresh only the skills already on disk — don't add missing ones
--yes
optional
Non-interactive: accept the SDK update without prompting
--dry-run
optional
Show what would change without installing anything
Examples:
# CLI + agents + skills, then offer the SDK bumpshipeasy upgrade# non-interactive: also accept the SDK updateshipeasy upgrade --yes# global install, pnpm-managed CLIshipeasy upgrade --scope user --pm pnpm# preview without installingshipeasy upgrade --dry-run
Update the CLI itself and refresh your Shipeasy skills to the latest marketplace revision (re-fetched from the repo). Skips the MCP re-registration and the SDK bump that the full shipeasy upgrade also does.
shipeasy upgrade skills [options]
Option
Description
--agents <list>
optional
Restrict to these agents (claude,cursor,codex,copilot,antigravity,gemini)
--scope <scope>
optional
Where skills live: project | user (default: auto-detected)
--pm <pm>
optional
Package manager for the global CLI update (npm|pnpm|yarn|bun)
--skip-cli
optional
Refresh skills only — don't self-update the CLI
--only-installed
optional
Refresh only the skills already on disk — don't add missing ones
--dry-run
optional
Show what would change without installing anything
Examples:
# refresh the CLI + skills onlyshipeasy upgrade skills# skills only, leave the CLI as-isshipeasy upgrade skills --skip-cli# one agent, in-reposhipeasy upgrade skills --agents claude --scope project
Enable a platform module group (flags | i18n | ops) and verify it
Turns on a coherent group of project modules in one call, then verifies the admin read paths are reachable and prints next steps. Module groups:
• flags — gates + configs + events + experiments (kill switches ride the
same KV blob; no separate flag).
• i18n — translations; also ensures the primary profile (--profile,
default en:prod) exists, since the server does not auto-create one.
• ops — feedback + events (the queue + production-error tickets). The
code wiring (devtools overlay, see() reporting) is language-specific
and lives in the shipeasy-ops + shipeasy-see skills.
Requires an admin session (shipeasy login) and a bound project; an ops key cannot toggle modules.
shipeasy install [options] <module>
Argument
Description
module
required
—
Option
Description
--profile <name>
optional
i18n only: primary profile to ensure exists (default: "en:prod")
--json
optional
Output as JSON
--project <id>
optional
Project ID override
--no-skills
optional
Enable the module only — don't install its how-to skills
Examples:
# Enable the whole flags + experimentation platformshipeasy install flags# Enable translations + ensure en:prod existsshipeasy install i18n# Use a different primary profileshipeasy install i18n --profile en:staging# Enable the feedback / ops queueshipeasy install ops
Scan the repo for install targets and print a per-folder onboarding recommendation (language, install command, keys, secret store, docs handle, next skills).
detect is the engine behind the setup skill's 'detect subprojects' step. With no args it walks the tree under the cwd (depth 4, pruning node_modules/vendor/build/etc.) and finds every project manifest (package.json, pyproject.toml, Gemfile, go.mod, pom.xml, build.gradle[.kts], composer.json, Package.swift). Pass explicit paths to scan only those folders.
For each folder it reports the detected language + frameworks and a recommendation: the SDK install command, which keys to mint (server, plus client for browser frameworks), the idiomatic secret store, the shipeasy docs get line that pulls the version-correct install + configure() wiring for that language, and the feature-install skills to run next. Already-onboarded folders and JS workspace roots are flagged so they're skipped. Use --json to drive it programmatically.
It also writes what it detected — the language, sdk, and frameworks — into each real target's own .shipeasy (non-destructively; project_id is never touched), recording one file per project and seeding the sdk that shipeasy docs defaults to. --json echoes the written paths under recorded.
shipeasy detect [options] [paths...]
Argument
Description
paths...
optional
—
Option
Description
--json
optional
Output the structured recommendation set as JSON
Examples:
# recommendations for every target under the cwdshipeasy detect# machine-readable, for the setup skillshipeasy detect --json# scan only these foldersshipeasy detect apps/web apps/api