Amplitude Setup Wizard CLI

One command, one terminal session. The wizard reads your actual codebase to propose events tailored to your app. You review and approve every change before the wizard writes anything.

npx @amplitude/wizard

The wizard runs in your terminal. Amplitude is testing Claude Code in Terminal, with Claude Code Desktop, Cursor Desktop, and more in development. Run npx @amplitude/wizard --help for information about subcommands and options.

What happens when you run it

1. Authenticate: The wizard signs you in (or picks up an existing session) and lets you choose your org, project, and data region.
2. Detect your framework: The wizard scans your project to identify your stack. It supports 18+ frameworks including Next.js, React, Vue, Django, Flask, Swift, Android, Flutter, Go, and more. Web projects use Browser SDK 2 or Browser Unified SDK.
3. Propose and instrument events: An Amplitude AI agent reads your codebase, proposes tracking events based on what your app does, and waits for your approval before writing any code. You don't need your own agent license.
4. Set up MCP integration: The wizard offers to install the Amplitude MCP server in your editor so you can query your analytics data in plain English.
5. Verify: The wizard polls the Amplitude API until it detects events arriving. Run your app, trigger some actions, and the wizard shows you the events as they flow in.
6. Create charts and a dashboard: The agent builds your first dashboard in Amplitude so you have something useful the moment data starts flowing.

If you stop the wizard with Ctrl+C, it crashes, or you close the terminal, the wizard saves a checkpoint. Run it again in the same directory to resume.

Access your data from wherever you work

• Terminal or IDE: Use the Amplitude MCP server to ask questions about your data in plain English from Claude, Cursor, or any MCP-compatible AI tool. Agents can run the CLI using --agent or --ci mode.

• Claude Code plugin: Install the Amplitude plugin for Claude Code, which provides the same MCP tools along with built-in slash commands for quick access.

  Inside a Claude Code session:

  bash

  Copy

  /plugin install amplitude
  

  Or from your terminal:

  bash

  Copy

  claude plugin install amplitude
  

  After installing, run /mcp in Claude Code and follow the browser prompts to log in to Amplitude. The plugin includes slash commands like /amplitude:create-chart, /amplitude:create-dashboard, /amplitude:instrument-events, /amplitude:replay-ux-audit, /amplitude:weekly-brief, and more.

• Slack or Teams app: Connect Amplitude to your team's messaging tool to get insights, create charts, and more where you work.

Run it from an AI agent

AI coding agents can drive the wizard end-to-end. Two non-interactive modes cover most automation:

• --agent streams NDJSON lifecycle events on stdout (one JSON object per line, each with a v:1 envelope) so an orchestrator can render progress, file diffs, and prompts in real time.
• --ci runs without prompts or color output, suitable for pipelines.

Both modes auto-approve the wizard's prompts. The right way to skip the human depends on whether the user already has an Amplitude account.

Net-new Amplitude account. Pass --auth-onboarding create-account plus the user's details so the wizard provisions the org, project, and app for them. Skip --api-key entirely. The wizard mints one as part of account creation. --email, --full-name, --accept-tos, and --region are all required when combining create-account with --agent or --ci, because the wizard has no TTY to prompt for them.

npx @amplitude/wizard --agent \
  --auth-onboarding create-account \
  --email <new-account-email> \
  --full-name "<Full Name>" \
  --accept-tos \
  --region <us|eu> \
  --app-name "<app name>" \
  -y

--agent already implies --auto-approve. -y is still needed to grant the inner agent write capability.

Existing Amplitude account, fully unattended. Pass an Amplitude project API key inline so the wizard can skip OAuth. Add --app-id <id> to bind the run to a specific Amplitude app. It's the only scope flag agents need, because the wizard derives org, project, and environment automatically:

npx @amplitude/wizard --agent --install-dir . --api-key <key> --app-id <id>

npx @amplitude/wizard --ci --install-dir . --api-key <key> --app-id <id>

Existing Amplitude account, prior login on the same machine. After a one-time npx @amplitude/wizard login, you can omit --api-key and the wizard reuses the stored OAuth token.

Key flags

Run npx @amplitude/wizard manifest to print the full machine-readable CLI surface (flags, environment variables, exit codes, and a glossary) as JSON.

Plan, apply, and verify

For agents that want a human in the loop on the diff, split a run into three phases. plan and verify never touch disk:

npx @amplitude/wizard plan --json
npx @amplitude/wizard apply --plan-id <id> --yes
npx @amplitude/wizard verify --json

1. plan --json builds a WizardPlan containing the detected framework, SDK choice, and intended file changes, then returns a planId that's valid for 24 hours. The output also includes a ready-to-run resumeFlags array. Feed it straight into apply.
2. apply --plan-id <id> --yes executes the plan and streams NDJSON file_change events for every write. Add --force to allow destructive overwrites.
3. verify --json runs a cheap, no-network check that the SDK, API key, and framework integration are all in place. It exits non-zero on failure.

Other agent-friendly subcommands include detect --json, status --json, auth status --json, and auth token for reading the stored OAuth token from other scripts.

MCP server mode

npx @amplitude/wizard mcp serve exposes the wizard's read-only operations as Model Context Protocol tools over stdio. AI agents call them as typed tools instead of spawning the CLI and parsing output. Add this snippet to your MCP client's config:

{
  "mcpServers": {
    "amplitude-wizard": {
      "command": "npx",
      "args": ["-y", "@amplitude/wizard", "mcp", "serve"]
    }
  }
}

The server exposes detect_framework, get_project_status, plan_setup, verify_setup, get_auth_status, and get_auth_token. Pair plan_setup with the apply CLI subcommand to execute the resulting plan.

Environment variables

The wizard reads these variables in --agent and --ci runs:

Exit codes

Orchestrators can branch on the wizard's exit code:

Exit code 3 (AUTH_REQUIRED) is the critical signal for orchestrators. The wizard emits it when an --agent run starts without valid credentials, alongside a structured lifecycle NDJSON event whose data.loginCommand and data.resumeCommand arrays tell the orchestrator exactly how to prompt the human to sign in and re-run. Reason values include no_stored_credentials, token_expired, refresh_failed, and env_selection_failed.

{
  "v": 1,
  "type": "lifecycle",
  "level": "error",
  "data": {
    "event": "auth_required",
    "reason": "no_stored_credentials",
    "loginCommand": ["npx", "@amplitude/wizard", "login"],
    "resumeCommand": ["npx", "@amplitude/wizard", "--agent"]
  }
}

On no_stored_credentials, an alternative to surfacing loginCommand is to re-invoke with the net-new account flags (--auth-onboarding create-account plus --email, --full-name, --accept-tos, --region, --app-name) and create a fresh account inline. This path isn't zero-prompt, because --accept-tos and --region still need explicit human input, but it skips the browser-based OAuth handshake.

Things to try after your data is flowing

• Watch your first session replay: Review exactly what users experience in your app.
• Launch a web experiment: A/B test features with no extra code using the Visual Editor.
• Create a guide or survey: Collect in-product feedback or surface messages to specific user segments.

Feedback

The wizard is open source. View the source, report issues, and contribute on GitHub.

Share what's working and what you'd like next: wizard@amplitude.com.