Developer

CLI commands, JSON, and exit codes

Every registered Apex CLI command, the stable JSON envelope, exit-code meanings, and headless agent usage rules.

Use this page as the command map before scripting the CLI. The source of truth is the live apex schema --json command.

Global behavior

apex is the canonical binary. drip is a compatibility alias.
--json is available globally and on every registered command.
Piped stdout automatically uses JSON mode even when --json is omitted.
Human progress, prompts, diagnostics, and update notices go to stderr.
Do not parse human tables. Use apex schema --json to discover commands and flags.

JSON output uses this stable top-level envelope:

json

{
  "ok": true,
  "version": "0.1.1",
  "command": "apex experiments list",
  "data": {}
}

Errors use the same envelope shape with ok: false and an error object:

json

{
  "ok": false,
  "version": "0.1.1",
  "command": "apex experiments apply",
  "error": {
    "message": "Applying these changes invalidates QA approval and requires confirmation.",
    "code": 4,
    "details": {
      "retry": "apex experiments apply ./my-test --force"
    }
  }
}

Headless and agent usage

bash

DRIP_API_KEY=apx_your_key_here apex schema --json
apex experiments plan ./my-test --json
apex experiments apply ./my-test --json

In headless mode:

Do not wait for prompts.
Prefer explicit --json.
If a command returns exit code 4, inspect error.details.retry and rerun with the exact flag only after checking the planned destructive or QA-invalidating action.
Never commit ~/.drip/credentials.json, API keys, or preview tokens.

Exit codes

Code	Meaning	Typical recovery
`0`	Success.	Continue.
`1`	General failure.	Read `error.message` and command-specific details.
`2`	Auth or permission failure.	Run `apex login`, set `DRIP_API_KEY`, or check API-key permissions.
`3`	Validation failure.	Fix arguments, JSON, config, or unsupported file content.
`4`	Confirmation required.	Inspect `error.details.retry`; rerun with the named flag only when intended.
`5`	Conflict, including stale filesystem state where detected.	Pull fresh state, reapply edits, and plan again.

apex login authenticates your account once: the browser flow mints an expiring, account-scoped user key that covers every organization and shop your account can access, then lets you pick an org/shop context. Inspect the credential and everything it can reach with apex whoami; switch the stored context with apex use <org>[/<shop>]; override per invocation with --org/--shop or the DRIP_ORG/DRIP_SHOP environment variables. Every JSON envelope echoes the effective context (org, shop, credential kind). Automation keeps injecting a narrow shop key per process with DRIP_API_KEY; shop and user credentials can coexist. apex login --user is a deprecated alias. Use apex logout --user to remove only the user credential; plain apex logout removes both.

Command index

The command names in this index are checked against apex schema --json by the CLI CI lane.

Command	Purpose
`apex login`	Authenticate your account and pick an org/shop context.
`apex logout`	Remove stored credentials.
`apex whoami`	Show your identity, credential, and available org/shop context.
`apex use`	Set the current Apex organization and shop context.
`apex account`	Manage your Apex account.
`apex account profile`	Show the current account profile.
`apex account profile set`	Update the current account profile.
`apex keys`	Manage shop API keys with a user credential.
`apex keys list`	List API-key metadata for a shop.
`apex keys create`	Create a shop API key and print its secret once.
`apex keys revoke`	Revoke a shop API key.
`apex webhooks`	Manage shop webhooks.
`apex webhooks list`	List webhooks.
`apex webhooks create`	Create a webhook.
`apex webhooks update`	Update a webhook URL, events, or active state.
`apex webhooks delete`	Delete a webhook.
`apex webhooks deliveries`	List webhook deliveries including failure and disabled state.
`apex webhooks test`	Send a signed test event to a webhook.
`apex simulate`	Simulate data-layer triggers without emitting events.
`apex experiments`	Manage experiments.
`apex experiments list`	List experiments.
`apex experiments get`	Get experiment details by ID or slug.
`apex experiments results`	Read experiment results and timeseries by ID or slug.
`apex experiments create`	Create a new experiment.
`apex experiments pause`	Pause a running experiment.
`apex experiments complete`	Complete or stop an experiment.
`apex experiments delete`	Delete an experiment.
`apex experiments pull`	Pull an experiment as an editable filesystem.
`apex experiments plan`	Plan experiment filesystem changes.
`apex experiments apply`	Apply experiment filesystem changes to Apex.
`apex experiments screenshots`	Force-assign every capture, including control, to its variation server-side for deterministic screenshots.
`apex experiments qa`	Manage experiment QA runs from the CLI.
`apex experiments qa status`	Show or create the latest experiment QA run.
`apex experiments qa check`	Update one QA checklist item with status, notes, and evidence.
`apex experiments qa notes`	Update QA run notes or acceptance criteria summary.
`apex experiments qa approve`	Mark QA done after checklist gates are ready.
`apex experiments qa reopen`	Reopen QA and clear scheduled launch state.
`apex experiments qa evidence`	Attach screenshot jobs or upload typed QA evidence.
`apex push`	Push experiment definitions from config to the API.
`apex preview`	Open a QA preview URL for an experiment variation.
`apex roadmap`	Work with approved roadmap ideas and build handoffs.
`apex roadmap approved`	List approved roadmap ideas ready to build in Apex.
`apex roadmap handoff`	Get the full build brief for an approved roadmap item.
`apex harness`	Develop AB Test Harness projects through Apex live QA sessions.
`apex harness init`	Create `apex.harness.json` for a harness folder.
`apex harness dev`	Build, upload, preview, and watch a harness folder.
`apex harness publish`	Verify, build, upload, and publish a harness artifact.
`apex workspace`	Check out, preview, and publish Apex draft workspace files.
`apex workspace checkout`	Check out an Operator workspace for one variation.
`apex workspace status`	Show changed local workspace files.
`apex workspace dev`	Upload one preview version or watch workspace files.
`apex workspace publish`	Build and publish changed workspace files back to Apex.
`apex tracking`	Create tracking ingestion manifests and QA handoffs.
`apex tracking inspect`	Create a local tracking manifest from funnel URLs.
`apex tracking plan`	Print the implementation plan from a tracking manifest.
`apex tracking qa`	Print the QA checklist for a tracking manifest.
`apex tracking verify`	Verify live tracking events, filter by `--event-type`, and preview event properties.
`apex goals`	Manage conversion and revenue goals.
`apex goals list`	List goals.
`apex goals create`	Create a goal.
`apex goals update`	Update a goal.
`apex goals test`	Dry run a goal URL pattern against traffic.
`apex goals suggest`	Suggest goals and funnels from analytics.
`apex funnels`	Manage analytics funnels.
`apex funnels list`	List funnels.
`apex funnels create`	Create a funnel.
`apex funnels update`	Replace a funnel's steps.
`apex funnels delete`	Delete a funnel.
`apex funnels run`	Run funnel analysis.
`apex funnels validate`	Validate funnel steps without writing.
`apex environments`	Manage runtime environments and domain mappings.
`apex environments list`	List runtime environments and mapped domains.
`apex environments set-domain`	Map a domain to a runtime environment.
`apex environments remove-domain`	Remove a domain mapping.
`apex consent`	Manage consent gating.
`apex consent get`	Show consent settings.
`apex consent set`	Enable and configure consent gating.
`apex consent off`	Disable consent gating.
`apex triggers`	Manage data-layer triggers and temporary setup capture.
`apex triggers get`	Read the shop's runtime triggers.
`apex triggers set`	Replace the shop's runtime triggers from a JSON file.
`apex triggers propose`	Propose candidate triggers from a discovery report.
`apex triggers apply-recipe`	Apply a server-owned trigger recipe.
`apex triggers enable-capture`	Enable temporary setup capture.
`apex triggers disable-capture`	Disable setup capture and clear its expiry.
`apex domains`	Manage install domains.
`apex domains list`	List install domains.
`apex domains add`	Add install domains.
`apex domains remove`	Remove install domains.
`apex domains set`	Replace install domains.
`apex handover`	Manage cross-domain identity handover.
`apex handover get`	Show cross-domain handover settings.
`apex handover set`	Enable cross-domain identity handover.
`apex handover off`	Disable cross-domain handover.
`apex handover qa`	Check static link/form handover parameter carriage.
`apex analytics`	Read shop analytics with a secret API key.
`apex analytics stats`	Show dashboard analytics stats.
`apex analytics timeseries`	Show analytics timeseries.
`apex analytics traffic`	Show traffic sources.
`apex analytics pages`	Show page analytics.
`apex analytics geo`	Show geography and device analytics.
`apex analytics sessions`	Show session analytics.
`apex analytics realtime`	Show realtime analytics.
`apex analytics entry-exit`	Show entry and exit page analytics.
`apex analytics consent-rate`	Estimate analytics consent acceptance from visitor series.
`apex analytics urls`	Show storefront URL inventory from pageview analytics.
`apex install`	Check Apex storefront installation.
`apex install check`	Verify snippet, served config (including purchase triggers), and recent tracking.
`apex flags`	Manage flags.
`apex flags list`	List flags.
`apex flags get`	Get a flag.
`apex flags status`	Check whether a flag publication is live at the edge.
`apex flags create`	Create a flag.
`apex flags update`	Update a flag.
`apex flags activate`	Activate a flag.
`apex flags pause`	Pause a flag.
`apex flags archive`	Archive a flag.
`apex backlog`	Manage backlog.
`apex backlog list`	List backlog.
`apex backlog get`	Get a backlog item.
`apex backlog create`	Create a backlog item.
`apex backlog update`	Update a backlog item.
`apex backlog archive`	Archive a backlog item with a decline reason.
`apex backlog restore`	Restore an archived backlog item.
`apex backlog delete`	Permanently delete a backlog item after confirmation.
`apex signals`	Manage signals.
`apex signals list`	List signals; pass `--include-archived` to include archived signals.
`apex signals get`	Get a signal.
`apex signals create`	Create a signal.
`apex signals update`	Update a signal.
`apex signals delete`	Delete or archive a signal.
`apex personalizations`	Manage personalizations.
`apex personalizations list`	List personalizations.
`apex personalizations get`	Get a personalization.
`apex personalizations create`	Create a personalization.
`apex personalizations update`	Update a personalization.
`apex personalizations activate`	Activate a personalization.
`apex personalizations pause`	Pause a personalization.
`apex personalizations archive`	Archive a personalization.
`apex external-pixels`	Manage external pixel integrations.
`apex external-pixels snippet`	Generate an external purchase pixel snippet.
`apex assets`	Manage assets.
`apex assets list`	List assets.
`apex assets get`	Get an asset.
`apex assets upload`	Upload an asset file.
`apex assets delete`	Delete an asset.
`apex landing-pages`	Read landing pages.
`apex landing-pages list`	List landing pages.
`apex landing-pages get`	Get a landing page.
`apex pages`	Manage pages.
`apex pages list`	List pages.
`apex pages create`	Create a page.
`apex pages update`	Update a page.
`apex pages delete`	Delete a page.
`apex segments`	Manage segments.
`apex segments list`	List segments.
`apex segments create`	Create a segment.
`apex segments update`	Update a segment.
`apex segments delete`	Delete a segment.
`apex exclusion-groups`	Manage exclusion groups.
`apex exclusion-groups list`	List exclusion groups.
`apex exclusion-groups get`	Get an exclusion group.
`apex exclusion-groups create`	Create an exclusion group.
`apex exclusion-groups update`	Update an exclusion group.
`apex exclusion-groups delete`	Delete an exclusion group after confirmation; use `--force` in non-interactive environments.
`apex exclusion-groups replace-members`	Replace exclusion group members.
`apex brand`	Print shop brand context for external agents.
`apex targeting`	Test experiment targeting.
`apex targeting test`	Evaluate experiment URL targeting for a page.
`apex audit-log`	Inspect sensitive audit logs.
`apex audit-log list`	List audit logs with entity filters and offset pagination.
`apex inbox`	Read and send inbox messages.
`apex inbox list`	List account or experiment inbox messages.
`apex inbox send`	Send an account or experiment inbox message.
`apex inbox mark-read`	Mark one inbox channel, or all channels, read.
`apex shops`	Manage organization shops.
`apex shops list`	List organization shops.
`apex shops get`	Get a shop.
`apex shops create`	Create a shop.
`apex shops update`	Update a shop.
`apex shops doctor`	Check shop configuration and the three-state purchase-capture battery against observed analytics.
`apex shops auto-stop`	Read or update auto-stop defaults.
`apex shops testing-defaults`	Read or update testing defaults.
`apex shops guardian`	Read or update guardian defaults.
`apex shops store-profile`	Read and review a store profile.
`apex shops store-profile get`	Read the store profile.
`apex shops store-profile review-fact`	Review a store-profile fact.
`apex shops store-profile review-finding`	Review a semantic finding.
`apex shops store-profile start-learning-run`	Start a store-profile learning run.
`apex shops shopware`	Manage Shopware bindings.
`apex shops shopware prebind`	Bind a Shopware store URL before installation.
`apex discover`	Read observed tracking shapes and optionally mine a public GTM container.
`apex schema`	Print the current Apex CLI command and flag schema.
`apex skills`	Print or install Apex CLI agent skill files.
`apex org`	Manage the organization bound to the user credential.
`apex org get`	Get organization details.
`apex org update`	Update organization settings.
`apex org members`	List organization members.
`apex org invite`	Invite an organization member with organization and default shop roles.
`apex org revoke-invite`	Revoke an organization invitation.
`apex org set-role`	Change an organization member role.
`apex org remove-member`	Remove an organization member after confirmation.
`apex team`	Manage shop-scoped team membership.
`apex team members`	List members for an explicit shop.
`apex team invite`	Invite a member to an explicit shop.
`apex team revoke-invite`	Revoke a shop invitation.
`apex team set-role`	Change a shop member role.
`apex team remove`	Remove a shop member after confirmation.

Analytics reads

apex analytics requires a secret API key with analytics:read (or analytics:*). Publishable keys cannot access shop analytics. Windowed commands accept --days; pages also accepts --limit. All commands support the standard --json envelope.

Global behavior

Headless and agent usage

Exit codes

Login and context

Command index

Analytics reads

Related pages