CLI commands, JSON, and exit codes

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.

CLI version floor

Every v1 API response includes X-Apex-Cli-Minimum and, when known at build time, X-Apex-Cli-Latest. The minimum is advisory until server-side enforcement is enabled. When enforcement is enabled, a write from an older Apex CLI returns HTTP 426 with code cli_upgrade_required and the exact upgrade command. Read commands continue to work so agents can inspect state and recover safely.

• 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.
• apex --version --json returns the standard envelope with the package name and version in data; apex --version remains a bare version string for compatibility, including in pipes.

JSON output uses this stable top-level envelope:

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

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

{
  "ok": false,
  "version": "0.1.1",
  "command": "apex experiments apply",
  "error": {
    "message": "Applying these changes revokes the QA approval from 2026-10-01T12:00:00.000Z; pass --accept-qa-invalidation to confirm.",
    "code": 4,
    "details": {
      "reason": "qa_approval_present",
      "qa_approved_at": "2026-10-01T12:00:00.000Z",
      "required_acknowledgment": "accept-qa-invalidation",
      "retry": "apex experiments apply ./my-test --accept-qa-invalidation"
    }
  }
}

When filesystem apply would replace authored URL rules with a Page attachment, it returns exit 4; review the change and retry with --confirm-targeting-replace.

With --json, stdout carries exactly one JSON document and nothing else.

For commands backed by one API request, data is the API response body exactly as the API returned it: lists keep { "data": [...], "pagination": {...} }, so rows are at .data.data[], and single resources are at .data. apex experiments get adds only dashboard_url. Commands that combine several requests or local files, such as experiments create, pull, plan and apply, print a documented CLI-composed object. When an API response caused a failure, error.api carries { "status", "body" } with the API error body verbatim; error.code stays the CLI exit code. CLI 0.13.0 introduced this mirroring; earlier releases nested bodies under keys such as .data.experiment.

Headless and agent usage

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.

• Note: CLI experiment readback for the v1 experiment format now guarantees the presence of lifecycle timestamp fields (started_at, scheduled_start_at, and qa_approved_at) in apex experiments get / apex experiments list --full --json outputs when those fields are applicable. Integrations should read those fields from the JSON envelope to determine scheduling and QA state.

Exit codes

Login and context

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>] or apex use --org <org> --shop <shop>; override per invocation with --org/--shop or the DRIP_ORG/DRIP_SHOP environment variables. An environment-key run cannot persist apex use; it returns context_not_persistable with the exact DRIP_ORG/DRIP_SHOP values to export. 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.

Survey body example

Save this body as survey.json, then use apex surveys create --file survey.json or apex surveys update <id> --file survey.json. Both commands also accept the body as inline JSON, @survey.json, or a positional file path. Providing a positional body together with --file is an error.

{
  "name": "Product feedback",
  "questions": [{
    "type": "single_choice",
    "prompt": "What would help you decide?",
    "options": [{"label": "More details"}, {"label": "Reviews"}, {"label": "Delivery info"}]
  }],
  "targeting": {"url": [{"type": "simple", "pattern": "/products/", "matchType": "contains"}]},
  "sampling_rate": 0.5,
  "frequency_cap": "once_per_visitor",
  "card_style": "quiet",
  "answer_goal": 100
}

On create, name is required. Server defaults: questions: [] (each question's required: true), targeting: null (all pages/visitors), sampling_rate: 1, frequency_cap: "once_per_visitor", card_style: "quiet", answer_goal: null, environment_key: "production", placement: "sdk_page", active_from: null, and active_to: null. Update accepts a partial body and keeps omitted fields unchanged. Run apex surveys create --help or apex surveys update --help for field limits and supported values.

Platform administrator commands

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

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.

Related pages

• Install and authenticate the Apex CLI
• Experiment lifecycle commands
• Agent tools: SOS, brand, schema, and skills

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.

Order journey diagnostics

apex analytics order-journey --platform shopware --order-id <id> --environment production --from <iso> --to <iso> requires a secret or authorized user key with analytics:read. Use --order-number instead of --order-id, never both. The interval is at most 31 days. --include-qa includes QA in eligibility; bots remain excluded.

--json retains the sanitized report, every represented assignment, source availability, coverage and the integration verdict. Exit 0 means the diagnostic was fetched, even when its verdict is fail or inconclusive. Eligibility means only eligible_for_attributed_goal_read, with basis attributed_goal_counts. Final statistical contribution is not_evaluated. Unknown consent, freshness, missing evidence and failed reads never mean zero or healthy. No proof file is saved.

Order journey diagnostics report current, stale, or unknown freshness for each retained receipt and assignment. Present attributed-goal reads identify their evaluated snapshot; they do not establish historical contribution or repair missing producer evidence.

Error recovery and update notices

JSON errors keep the numeric error.code exit code and add error.reason, error.next_steps (an array of { command, why }), and optional error.request_id. The request ID comes from x-request-id, falling back to x-vercel-id (the Apex app) and then cf-ray; include it when reporting an API failure. API-provided reason codes are preserved verbatim. Otherwise reasons are auth_required, auth_forbidden, shop_context_required, shop_context_mismatch, install_check_failed, validation_failed, feature_disabled, confirmation_required, conflict, not_found, rate_limited, network_timeout, network_connect_timeout, network_dns, network_refused, network_reset, network_tls, network_unknown, local_file_error, or internal_error.

Inspect next_steps for login, key permissions, shop selection, network settings, folder validation, disabled-feature contacts, request-field issues, or rate-limit recovery. Body validation failures carry per-field issues in error.details.issues; disabled features name their shop setting. Steps are suggestions, never automatic approval to retry a write. Confirmation errors retain error.details.retry. Human output prints recovery steps as Next: lines on stderr and request IDs on the error line. Trigger commands now follow the same exit codes as every other command: authentication failures exit 2 (previously 4), invalid local input exits 3 (previously 2), and other API failures follow their HTTP status (validation 3, conflict 5, anything else 1). The TRIGGERS_AUTH, TRIGGERS_CONFIG_ABSENT and TRIGGERS_NO_DATA verdict prefixes are unchanged, so scripts can key on them instead of exit codes.

Every JSON envelope may carry update and warnings. The update object includes current, latest, optional minimum, required, breaking, command, and notes_url; warnings use { code, message }. The exact install command is npm install -g @drip-apex/apex-cli@latest, and apex upgrade runs it (--dry-run only prints it). Set APEX_NPM_BIN to choose the npm binary.

The npm latest version is cached for 24 hours (failed lookups for one hour). Server latest/minimum policy is cached for seven days, so offline commands still enforce a known floor. APEX_NO_UPDATE_CHECK=1 disables the npm lookup and optional update notice, but never hides a required server-floor upgrade.

Tracking verification limits

apex tracking verify reads at most 200 of the newest events from a window of at most 7 days. When the limit is reached, truncated is true and totals describe that sample only. The response includes the exact from, to, minutes, and limit window.

Commerce catalog

• apex commerce catalog search [query] [--cursor <cursor>] [--limit <1-10>]
• apex commerce catalog get <handle> [--cursor <cursor>]
• apex commerce catalog get --product-id <id> [--cursor <cursor>]

Use --json for the complete API envelope. Human output lists variant GID, title, SKU, price, cost (unknown when absent), and price-test exclusion.

Commerce results output

Human-readable experiment results show a Profit per visitor (CM1) section for commerce tests and checkout-owned tests with attributed orders. Null money prints as -; degraded reads print their reason and never imply measured zeroes. JSON output preserves the API's commerce_results field unchanged, including pending_days, plane, decision_grade, and confidence_visible.

Checkout-owned tests measure orders from visitors who saw the checkout message and receive the supplementary CM1 section when they have attributed orders. Other non-commerce tests return commerce_results: null. An unavailable supplementary section on a checkout-owned test does not mark the analytics as degraded.

Import past test results

apex results import --file <path> uploads one or more CSV or JSON files, inspects their columns, and prints a deterministic preview before confirmation. Use --dry-run to stop after preview and --yes for non-interactive confirmation. --json preserves full learning text and returns the preview envelope for dry runs or merged { imported, skipped, test_results } totals after import.

Read past test results

apex results list [--source import|native|all] [--limit <n>] [--all] [--json] lists past results for the selected shop (default source all, page size 50, maximum 200). Use --all to follow every page. The table shows legacy ID (or UUID), title, outcome, metric, lift, sample size, dates, and source. Empty lists print No test results.

apex results get <legacy-id-or-id> [--json] opens a result by legacy ID, test key, or UUID, including its full learning, confidence, dates, page, and device. Missing results exit with code 1 through the existing API failure path. Both commands use shop or user keys with experiments:read and verify each row belongs to the selected shop. Imports show their source name and original date range, falling back to import time; native results show source apex and creation time.

apex results delete <legacy-id-or-id> [--yes] [--json] permanently removes one imported result with experiments:write. It first reads and previews the title, outcome, dates, source, and legacy ID. Native results are refused locally (exit 3). Confirm the prompt or pass --yes; non-TTY callers without --yes receive exit 4 with the exact rerun hint. Removed results cannot be restored in Apex; the full record remains in the audit log. JSON output wraps the API { data } response and verifies the echoed shop.

JSON uses the standard CLI envelope: its data contains { data, pagination } for lists (merged rows and final pagination with --all) or { data: result } for a single result. Invalid --source or --limit exits 3 before an HTTP request.

Asset delivery URLs

apex assets upload <file> returns delivery_url; embed that permanent URL in variation code. The public_url is a signed read URL for the API caller and expires after 300 seconds. Never embed it. Delivery is anonymous once the referencing experiment or snippet is published, and resolves through the owning shop's dashboard session or a QA preview before that. Only the absolute https form is recognized as an owned reference; protocol-relative or http forms are not granted at publication.

See Commerce prices for CSV export, import, and revision semantics.