ApexDocsOpen Apex
Developer

Install and authenticate the Apex CLI

Install apex, sign in with the default browser OAuth flow, and use API-key fallbacks for headless environments.

The Apex CLI is the command-line interface for experiment operations, draft workspace edits, GitOps pushes, QA evidence, tracking checks, and agent handoffs. Use apex as the canonical binary. drip is kept as a compatibility alias.

Prerequisites

  • Node.js 18 or newer.
  • An Apex account with access to the shop or workspace you want to manage.
  • For API-key fallback login, an Apex API key that starts with apx_.

Install

bash
npm install -g @drip-apex/apex-cli
apex --help

Agents and sandboxes

Install the CLI once, then call apex directly. apex --help and apex schema --json answer without network access. Do not run npx @drip-apex/apex-cli@latest for every command: npx asks the npm registry for the package before the CLI starts, so it prints nothing and hangs when the registry is slow or blocked, which is common in agent sandboxes. Update with npm install -g @drip-apex/apex-cli@latest.

For local package development, build and link from the monorepo:

bash
npm --prefix packages/cli install
npm --prefix packages/cli run build
cd packages/cli
npm link

Default browser login

Run login in an interactive terminal:

bash
apex login

By default, the CLI starts a short-lived callback server on 127.0.0.1, opens Apex at /cli/login, and includes a one-time state, local callback URL, and machine name. Approve the CLI login in your browser. Apex posts the generated API key back to the local callback, the CLI validates it by reading one experiment, and then stores credentials at ~/.drip/credentials.json with file mode 0600.

If the browser does not open automatically, the CLI prints the login URL. Open that URL manually in the same browser session where you are signed in to Apex.

Manual and API-key login

Use --manual when you want the CLI to prompt for a key instead of starting browser login:

bash
apex login --manual

Use --api-key for non-interactive shells:

bash
apex login --api-key apx_your_key_here

Use --base-url only when you are targeting a non-production Apex environment:

bash
apex login --base-url https://app.example.test

In CI or agent runners, prefer environment variables over prompts:

bash
DRIP_API_KEY=apx_your_key_here apex whoami --json

DRIP_API_KEY takes priority over stored credentials. DRIP_BASE_URL can override the API base URL for the process; otherwise the CLI uses https://app.drip-apex.com.

Verify or clear auth

bash
apex whoami
apex experiments list --limit 5
apex logout

apex whoami validates the current key against the API and prints only a redacted key preview. apex logout removes the stored credential file, but it does not revoke the API key in Apex.

To verify a storefront installation, run apex install check. The command resolves its shop from an explicit --shop-id first, then the invocation's selected shop (--shop <id> or apex use), and finally DRIP_SHOP_ID. --shop-id selects that shop for every request; a contradictory explicit --shop is refused with exit 3 and shop_context_mismatch. A definite failed verdict exits 6 and lists failed_checks in the JSON error details.

bash
apex --shop shop_123 install check --json

Troubleshooting

  • Browser login fails in CI: use apex login --api-key <key> or set DRIP_API_KEY.
  • Login returns exit code 4: inspect the JSON error.details.retry command and rerun only after confirming you meant to use API-key login.
  • Validation fails with 401: check that the key is valid and starts with apx_.
  • Validation fails with 403: the key exists, but it lacks permission to read experiments.
  • member_suspended (exit code 2): ask an organization owner or admin to reinstate your membership; logging in again will not restore access.
  • Validation is rate-limited: retry later and check the server-side rate-limit configuration if this happens on first login.
  • When the CLI cannot connect to the API, the error message now reports the underlying cause (for example: DNS lookup failure, TCP connection refused, TLS certificate validation failure, or a socket timeout) and includes a machine-readable reason field in JSON output where applicable. Verify network, DNS, and proxy settings when you see one of these causes.