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.

Use apex login --user to approve an expiring, organization-bound user key in the browser. Shop and user credentials can coexist. apex whoami verifies and shows both credentials, including the user key's organization and live role. 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 with Apex.
`apex logout`	Remove stored credentials.
`apex whoami`	Show current authentication status.
`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 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 start`	Start an 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 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 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 for the current shop.
`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 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 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 web-vitals`	Show web vitals analytics.
`apex analytics realtime`	Show realtime analytics.
`apex analytics entry-exit`	Show entry and exit page analytics.
`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 sos`	Create and inspect Apex SOS tickets.
`apex sos create`	Create an Apex SOS ticket.
`apex sos mine`	List SOS tickets created by this API key.
`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 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 schema`	Print the current Apex CLI command and flag schema.
`apex skills`	Print or install Apex CLI agent skill files.
`apex admin`	Operate allowlisted platform controls.
`apex admin settings`	Show platform operator settings.
`apex admin settings set`	Set platform kill switches; requires the explicit `--confirm` flag.
`apex admin quarantine`	List tracking quarantine events.
`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

User-scoped login

Command index

Analytics reads

Related pages