ApexDocsOpen Apex
Developer

Experiment lifecycle commands

Create, list, inspect, read results, 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

bash
apex experiments list --status draft --limit 20
apex experiments get homepage-hero-test
apex experiments results homepage-hero-test --currency EUR
CommandArgumentsFlagsNotes
apex experiments listNone--status <status>, --limit <n>Status filter accepts draft, running, paused, or completed values.
apex experiments get<id-or-slug>None beyond global flagsA 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:

bash
apex experiments results homepage-hero-test --currency EUR --json

Create a draft

bash
apex experiments create \
  --name "Homepage hero trust copy" \
  --slug homepage-hero-trust-copy \
  --description "Tests clearer proof copy in the homepage hero." \
  --traffic 25
FlagRequiredBehavior
--name <name>YesExperiment display name.
--slug <slug>NoURL-safe slug for GitOps and slug-based lookup.
--description <desc>NoDraft description.
--type <type>Nomutation (default) or flag-gated redirect.
--source-url <pattern>Redirect: yesPositive source URL targeting rule. Repeat for multiple exact URLs, paths, or wildcard patterns. The first absolute HTTP(S) value also becomes the preview/store URL.
--destination <url>Redirect: yesHTTP(S) destination for one treatment variation. Repeat to create multiple equally weighted treatments. Invalid or missing redirect destinations fail validation.
--traffic <pct>NoPercentage input converted to API traffic allocation. Defaults to 100.

The command creates the experiment through the API. Configure variations, metrics, targeting, and QA before launching traffic in the dashboard.

Create a redirect experiment with a control on the source page and one treatment on the destination:

bash
apex experiments create \
  --name "Product page split URL" \
  --type redirect \
  --source-url "https://shop.example/products/source" \
  --destination "https://landing.example/products/treatment"

Redirect creation preserves the public v1 gates: the shop must have redirect tests enabled, at least one positive source rule and treatment destination are required, and destinations must be HTTP(S). A destination must not match the source targeting unless it is the same page with added or changed query parameters, such as ?view=alternate. API gate failures use the standard JSON error envelope and exit codes.

The filesystem and public v1 contracts permit a redirect treatment to retain mutations, CSS, or JavaScript. Those artifacts are source-page-only; Apex keeps the assignment active on the destination for attribution but does not apply the source-authored artifacts there. Filesystem plans warn when a treatment mixes these artifacts with a destination.

Lifecycle verbs

bash
apex experiments pause homepage-hero-trust-copy
apex experiments complete homepage-hero-trust-copy
CommandArgumentsBehavior
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.

Starting traffic is dashboard-only so the approval gates remain visible. Lifecycle validation for pause and complete is owned by Apex; if the API rejects a state transition, the CLI reports the API error and exits non-zero.

Delete

bash
apex experiments delete homepage-hero-trust-copy
apex experiments delete homepage-hero-trust-copy --force --json

apex experiments delete prompts before deleting in an interactive terminal. In non-TTY mode, deletion returns confirmation-required exit code 4 unless you pass --force.

Launch in the dashboard

The CLI has no experiments start command. Launch is dashboard-only so Apex can keep approval and readiness gates visible; CLI lifecycle commands cannot 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 --force only after confirming the target experiment.