Experiment lifecycle commands
Create, list, inspect, read results, start, pause, complete, and delete Apex experiments from the CLI.
The experiments group covers experiment CRUD and lifecycle actions. Use IDs or slugs for reads and lifecycle commands. The alias apex exp is available for the group, and apex experiments list also has the ls alias.
List and inspect
apex experiments list --status draft --limit 20
apex experiments get homepage-hero-test
apex experiments results homepage-hero-test --currency EUR| Command | Arguments | Flags | Notes |
|---|---|---|---|
apex experiments list | None | --status <status>, --limit <n> | Status filter accepts draft, running, paused, or completed values. |
apex experiments get | <id-or-slug> | None beyond global flags | A plain slug and slug:<slug> both resolve by slug. |
apex experiments results | <id-or-slug> | --currency <code> | Returns experiment totals, arms, decision, metrics, series, and warnings when the API provides them. |
Use JSON mode for scripts:
apex experiments results homepage-hero-test --currency EUR --jsonCreate a draft
apex experiments create \
--name "Homepage hero trust copy" \
--slug homepage-hero-trust-copy \
--description "Tests clearer proof copy in the homepage hero." \
--traffic 25| Flag | Required | Behavior |
|---|---|---|
--name <name> | Yes | Experiment display name. |
--slug <slug> | No | URL-safe slug for GitOps and slug-based lookup. |
--description <desc> | No | Draft description. |
--traffic <pct> | No | Percentage input converted to API traffic allocation. Defaults to 100. |
The command creates the experiment through the API. Configure variations, metrics, targeting, and QA before starting traffic.
Lifecycle verbs
apex experiments start homepage-hero-trust-copy
apex experiments pause homepage-hero-trust-copy
apex experiments complete homepage-hero-trust-copy| Command | Arguments | Behavior |
|---|---|---|
apex experiments start | <id-or-slug> | Requests the API to move the experiment to running. |
apex experiments pause | <id-or-slug> | Requests the API to pause a running experiment. |
apex experiments complete | <id-or-slug> | Requests the API to complete or stop the experiment. |
Lifecycle validation is owned by Apex. If the API rejects a state transition, the CLI reports the API error and exits non-zero.
Delete
apex experiments delete homepage-hero-trust-copy
apex experiments delete homepage-hero-trust-copy --force --jsonapex experiments delete prompts before deleting in an interactive terminal. In non-TTY mode, deletion returns confirmation-required exit code 4 unless you pass --force.
What the CLI does not launch
The CLI can request lifecycle transitions exposed by the API, but the Apex launch workflow still relies on dashboard-owned approval and readiness gates. Do not use CLI lifecycle commands to bypass QA or business approval.
Troubleshooting
- Experiment not found: check whether you passed an ID, slug, or
slug:<slug>. - Lifecycle action rejected: inspect the API error in JSON mode for readiness, status, or permission details.
- Delete fails in automation: rerun with
--forceonly after confirming the target experiment.