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 128 chars. 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
--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.
--query-ir <value>
optional
Typed query IR — the structured alternative to the query DSL string. Exactly one of query / query_ir is supplied per metric body.
Stable opaque metric id (met_…) or the metric's name.
Option
Description
--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.
--query-ir <value>
optional
Typed query IR — the structured alternative to the query DSL string. Exactly one of query / query_ir is supplied per metric body.
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.
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).
New lifecycle state. 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.
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.
shipeasy release experiments universes list [options]
Option
Description
--limit <value>
optional
Page size (1–500). Defaults to 100.
--cursor <value>
optional
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 universe key. Single segment or folder.name. Lowercase letters, digits, _ or -; max 128 chars. Immutable after create.
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
Human-readable blurb shown in the universe picker/hovercard.
--unit-type <value>
optional
Unit of randomisation. Typically user_id. Use account_id to keep whole accounts in the same group across an experiment.
--holdout-range <value>
optional
Inclusive [lo, hi] bucket range (0–9999) reserved as the holdout — callers hashed into this slice are excluded from every experiment in the universe. null disables the holdout. Pro plan or higher required.
--recommended-headroom <value>
optional
Basis points of reserved headroom seeded into each new experiment created in this universe (0 = none). Lets variants be appended into a running experiment without reshuffling.
--param-schema <value>
optional
The universe-owned config schema — an ordered { name, type, default }[]. Experiments may only override values per variant, never add fields. null starts an empty schema.
Stable opaque universe id (uni_…) or the universe's name.
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
Human-readable blurb shown in the universe picker/hovercard.
--holdout-range <value>
optional
Inclusive [lo, hi] bucket range (0–9999) reserved as the holdout — callers hashed into this slice are excluded from every experiment in the universe. null disables the holdout. Pro plan or higher required.
--recommended-headroom <value>
optional
Basis points of reserved headroom seeded into new experiments in this universe.
--param-schema <value>
optional
Replace the universe config schema. Additive changes + default edits are always allowed; removing a param a running experiment overrides is rejected (deprecate-only).
Opaque cursor returned in the previous page's next_cursor. Omit for the first page.
--status <value>
optional
Filter by lifecycle status. Pass archived to return the archive tab; any other value (or omitting it) returns the non-archived experiments.
--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 experiment key. Single segment or folder.name (a-z, 0-9, _/-; max 128 chars). Used by SDKs as Shipeasy.getExperiment(user, '<name>'). Immutable after create.
Option
Description
--description <value>
optional
Free-form description. Max 2000 chars, markdown rendered in the dashboard.
--hypothesis <value>
optional
Hypothesis statement shown in the editor. Display-only.
--tag <value>
optional
Short tag chip rendered next to the name. Display-only.
--owner-email <value>
optional
Owner email. Display-only.
--audience <value>
optional
Audience label shown in the editor. Display-only.
--bucket-by <value>
optional
—
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--universe <value>
optional
Name of an existing universe in the project. Returns 422 if the universe doesn't exist.
--targeting-gate <value>
optional
Optional gate name (a targeting-type flag). Only callers that pass the gate are enrolled in the experiment.
--holdout-gate <value>
optional
Optional per-experiment holdout gate — the name of a holdout-type flag (public % + whitelist). A caller the flag passes is held out (never assigned, sees the universe defaults). Distinct from the universe-level holdout.
--allocation-pct <value>
optional
Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). 0 = unallocated. Under pooled assignment this is the size of the universe-pool slice claimed. Use allocation_percent (0–100) below to think in percent. Immutable while the experiment is running.
--allocation-percent <value>
optional
Allocation as a percentage (0–100, fractional ok). Friendlier alias for allocation_pct; converted to basis points server-side (e.g. 50 = 5000 bp). If both are set, allocation_percent wins.
--reserved-headroom <value>
optional
Basis points of this experiment's split kept empty (0–10000) so a new variant can be appended into it while running without reshuffling. Group weights must sum to 10000 − reserved_headroom. Defaults to the universe's recommended_headroom when omitted.
--salt <value>
optional
Hash salt for bucketing. Auto-generated if omitted. Immutable while running.
--params <value>
optional
Deprecated — the universe now owns the config schema (param_schema). Retained for back-compat; new experiments should leave this empty and declare params on the universe. Map of param-name → scalar type.
--groups <value>
optional
Two or more variants. Weights must sum to 10000 − reserved_headroom. Existing weights are immutable while running, but a new variant may be appended into the reserved tail.
--significance-threshold <value>
optional
p-value cutoff used by the analysis pass. Defaults to 0.05. Values other than 0.05 require Pro plan or higher.
--min-runtime-days <value>
optional
Minimum days the experiment must run before results are considered conclusive.
--min-sample-size <value>
optional
Minimum exposures per group before results are considered conclusive.
--sequential-testing <value>
optional
Enable sequential testing (always-valid p-values). Requires Premium plan or higher.
--goal-metric <value>
optional
Inline metric — a DSL query, or an event (+ aggregation/value) the server compiles into one.
--guardrail-metrics <value>
optional
Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail.
Stable opaque experiment id (exp_…) or the experiment's name.
Option
Description
--name <value>
optional
Stable experiment key. Single segment or folder.name (a-z, 0-9, _/-; max 128 chars). Used by SDKs as Shipeasy.getExperiment(user, '<name>'). Immutable after create.
--description <value>
optional
—
--hypothesis <value>
optional
—
--tag <value>
optional
—
--owner-email <value>
optional
—
--audience <value>
optional
—
--bucket-by <value>
optional
—
--folder <value>
optional
Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).
--targeting-gate <value>
optional
—
--holdout-gate <value>
optional
Per-experiment holdout gate — the name of a holdout-type flag, or null to clear. A caller the flag passes is held out.
--allocation-pct <value>
optional
Basis-points allocation (0–10000). Use allocation_percent (0–100) for percent. Immutable while the experiment is running.
--reserved-headroom <value>
optional
Basis points of the split kept empty for appended variants. Group weights must sum to 10000 − reserved_headroom. May be shrunk (never grown into existing weights) while running when appending a variant.
--allocation-percent <value>
optional
Allocation as a percentage (0–100). Friendlier alias for allocation_pct; converted to basis points server-side. Wins over allocation_pct if both are supplied. Immutable while running.
--salt <value>
optional
Hash salt. Immutable while running.
--universe <value>
optional
New universe name. Immutable while running. Returns 422 if the universe doesn't exist.
--params <value>
optional
Deprecated — the universe owns the config schema (param_schema). Retained for back-compat. Map of param-name → scalar type.
--groups <value>
optional
Replacement groups. Weights must sum to 10000 − reserved_headroom. Existing weights/values are immutable while running; a new variant may be appended into the reserved tail.
--significance-threshold <value>
optional
—
--min-runtime-days <value>
optional
—
--min-sample-size <value>
optional
—
--sequential-testing <value>
optional
—
--goal-metric <value>
optional
Inline metric — a DSL query, or an event (+ aggregation/value) the server compiles into one.
--guardrail-metrics <value>
optional
Replaces the guardrail set wholesale (event auto-upserted per entry).
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. Only the skills you actually have are refreshed — discovery falls back to the full catalogue when it finds none.
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
--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
--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
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
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 injectshipeasy i18n install-loader --profile en:prod# Print the tag only, do not writeshipeasy i18n install-loader --print# Target a specific fileshipeasy i18n install-loader --path ./src/app/layout.tsx
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>, or re-push the file with --force to overwrite every colliding key at once.
shipeasy i18n push [options] <file>
Argument
Description
file
required
—
Option
Description
--profile <name>
required
Profile name (e.g. 'default')
--force
optional
Overwrite keys that already exist with the values in the file, instead of skipping them
--json
optional
Output as JSON
--project <id>
optional
Project ID override
Examples:
# Add new keys from a flat JSON mapshipeasy i18n push ./locales/en.json --profile en:prod# Re-push the file over existing keys (overwrites values)shipeasy i18n push ./locales/en.json --profile en:prod --force
Create an i18n profile (e.g. 'default', 'en:prod')
shipeasy i18n profiles create [options] <name>
Argument
Description
name
required
—
Option
Description
--locales <locales>
optional
Comma-separated locale list (defaults to 'en') (default: ["en"])
--default-locale <locale>
optional
Default locale (defaults to first --locales entry)
--json
optional
Output as JSON
--project <id>
optional
Project ID override
Examples:
# Create a profile with one localeshipeasy i18n profiles create en:prod# Multiple locales with a defaultshipeasy i18n profiles create fr:prod --locales fr,fr-CA --default-locale fr
Runs the whole extraction pipeline as one command: the AST codemod wraps translatable strings with i18n.t() and writes a flat keys file, then those keys are pushed (insert-only) and published. It first verifies this project's language/framework (from .shipeasy) has a codemod; for any other language it prints that language's i18n doc so you can wrap strings by hand, then push with shipeasy i18n push.
shipeasy i18n extract [options] [target]
Argument
Description
target
optional
—
Option
Description
--profile <name>
optional
Profile to push keys to (default: "en:prod")
--dry-run
optional
Preview the codemod without writing or pushing
--no-publish
optional
Push keys but don't publish to the CDN
--project <id>
optional
Project ID override
Examples:
# Extract under auto-detected dirs, push + publishshipeasy i18n extract# Target one dirshipeasy i18n extract ./src# Preview onlyshipeasy i18n extract --dry-run# Push but don't publishshipeasy i18n extract --no-publish