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.
apex push and apex experiments apply write one hosted asset upload line to stderr for each inline image above 4,096 characters and each referenced local image file. Pass --no-asset-upload to keep inline and local image references unchanged.
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 attach-idea`	Attach an experiment to an idea.
`apex experiments detach-idea`	Detach an experiment from its idea.
`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 project-code`	Inspect and safely change shop project code.
`apex project-code get`	Read complete code and its opaque version.
`apex project-code diff`	Preview a partial JSON change without writing.
`apex project-code set`	Create a backup before a version-checked write.
`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 backlog fields`	Manage the shop's own idea fields.
`apex backlog fields list`	List the shop's idea fields.
`apex backlog fields create`	Add an idea field.
`apex backlog fields update`	Update an idea field.
`apex backlog fields archive`	Archive an idea field; values already on ideas are kept.
`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; the default shop role is `editor` (workspace defaults are internal 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 as `editor` or `client_viewer` (Viewer).
`apex team revoke-invite`	Revoke a shop invitation.
`apex team set-role`	Change a shop member role to `editor` or `client_viewer` (Viewer).
`apex team remove`	Remove a shop member after confirmation.

Platform administrator commands

These commands require a platform user API key and are intentionally excluded from the public command index.

Command	Purpose
`apex admin shops archive <shopId>`	Archive a shop and disable Apex delivery; use `--force` in non-interactive environments.
`apex admin shops restore <shopId>`	Restore an archived shop while leaving its runtime kill switch unchanged.

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.

Project code

apex project-code get --shop example.com --json
apex project-code diff --file project-code.json --shop example.com --json
apex project-code set --file project-code.json --shop example.com --backup previous-code.json --json

The input is a partial projectCode object, for example { "css": "body { color: red; }" }. Supported fields are enabled (boolean) and css, helperJs, and js (strings or null). Each code field permits at most 20,000 characters. Omitted fields remain unchanged. Null or blank code clears that field. Unknown fields and empty objects are rejected.

GET returns complete code, shop identity, and an opaque version. DIFF returns effective before/after values and changed fields without writing. SET creates a new backup file with complete previous code, identity, capture time, and the exact version before PATCH. It never replaces an existing backup. Backup failures prevent the write. An effective no-op returns unchanged, without a PATCH or backup file.

The backed-up version becomes expectedVersion unchanged. A conflict returns exit 5, keeps the backup, and does not retry. Read the latest state and preview it before a new attempt with a new backup path. Authentication uses exit 2; invalid input uses exit 3. A successful write returns saved, its diff, backup path, current version, writtenVersion, and precompile result. A failed precompile is a saved-write warning. All warnings remain in JSON and are also written to stderr. User keys resolve domains or pin UUID context; shop keys must match the requested identity before any backup or write.