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

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.

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.
  • Validation is rate-limited: retry later and check the server-side rate-limit configuration if this happens on first login.