The Amplitude Wizard CLI is a command-line tool that instruments your codebase and sets up Amplitude analytics in 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. ```shell 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. {% callout type="note" %} The Amplitude Wizard CLI requires Node.js 20+. {% /callout %} {% callout type="tip" %} Prefer a manual setup? Follow the [Amplitude Quickstart](/docs/get-started/amplitude-quickstart) to instrument your site directly. {% /callout %} ## What the Amplitude Wizard CLI does 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 inspects your project and picks the right integration path. Auto-detection covers Next.js, Vue, React Router, Django, Flask, FastAPI, Swift, React Native, Android, Flutter, Go, Java, Unreal, and Unity, with language-level fallbacks for JavaScript (web), Python, and JavaScript (Node). If nothing matches, you can select manually or use the generic fallback. Web projects use [Browser SDK 2](/docs/sdks/analytics/browser/browser-sdk-2) or [Browser Unified SDK](/docs/sdks/analytics/browser/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 Amplitude data from the tools you already use - **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` mode. - **Claude Code plugin**: Install the [Amplitude plugin for Claude Code](https://github.com/amplitude/mcp-marketplace/tree/main/plugins/amplitude), which provides the same MCP tools along with built-in slash commands for quick access. Inside a Claude Code session: ```bash /plugin install amplitude ``` Or from your terminal: ```bash 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 the Amplitude Wizard CLI from an AI agent AI coding agents can drive the wizard end-to-end. `--agent` mode streams [NDJSON](https://github.com/ndjson/ndjson-spec) 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. It auto-approves 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`, because the wizard has no TTY to prompt for them. ```shell npx @amplitude/wizard --agent \ --auth-onboarding create-account \ --email \ --full-name "" \ --accept-tos \ --region \ --app-name "" \ -y ``` `--agent` already implies `--auto-approve`. `-y` is still needed to grant the inner agent write capability. {% callout type="warning" %} **`--accept-tos` and `--region` need explicit human consent.** AI coding agents and orchestrators must not pass these flags on the user's behalf without confirmation: - `--accept-tos` programmatically accepts Amplitude's [Terms of Service](https://amplitude.com/terms). The acceptance is legally binding on the human whose account the wizard creates, not on the agent. Treat it like a click-through "I agree" checkbox: ask first, pass the flag only after the user confirms. - `--region` (`us` or `eu`) selects the data center for the new account and has data-residency implications. Ask the user which region applies to them, based on regulatory requirements, internal data-handling policy, or where their other Amplitude data already lives. Then pass the chosen value verbatim. Omitting either flag in `--agent` mode is a hard error, which is the intended safeguard. {% /callout %} **Existing Amplitude account, fully unattended.** Pass an Amplitude project API key inline so the wizard can skip OAuth. Add `--app-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: ```shell npx @amplitude/wizard --agent --install-dir . --api-key --app-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. {% callout type="warning" %} Don't pipe `--agent` output through `head`, `tail`, or `grep`. SIGPIPE ends the inner setup agent mid-run. Redirect to a file with `> wizard.log 2>&1` and tail it separately. If a run is interrupted, resume with `npx @amplitude/wizard --agent --resume -y`. {% /callout %} ### Key flags | Flag | Purpose | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | Amplitude project API key for an existing account. Skips OAuth so the wizard can run unattended. Or set `AMPLITUDE_WIZARD_API_KEY`. | | `--install-dir ` | Directory to install in. Required for `--agent`. | | `--yes` / `-y` | Skip all confirmation prompts and let the inner agent write files. Required for the `apply` subcommand and for `create-account` runs. | | `--auto-approve` | Silently pick the recommended choice on `needs_input` prompts. Doesn't grant write capability on its own; pair with `--yes` for that. `--agent` already implies `--auto-approve`. | | `--auth-onboarding ` | OAuth path: `sign-in` (default) for an existing account, or `create-account` to provision a brand-new Amplitude account from the CLI. | | `--email ` | Email for new-account creation. Required with `--auth-onboarding create-account` in `--agent`. | | `--full-name ""` | Full name for new-account creation. Quote the value when it contains spaces. Required with `--auth-onboarding create-account` in `--agent`. | | `--accept-tos` | Programmatically accepts Amplitude's [Terms of Service](https://amplitude.com/terms) on the user's behalf. Required with `create-account` in `--agent`. Don't pass without explicit user consent. The acceptance is legally binding on the human, not on the agent. | | `--region ` | Data-center region (`us` or `eu`) for the new account. Has data-residency implications. Required with `create-account` in `--agent`. Don't default on the user's behalf; ask which region applies. Also accepted as `--zone`. | | `--app-name ""` | Name for a new Amplitude app. Creates one when no apps exist, or whenever passed in `--agent`. | | `--app-id ` | Numeric Amplitude app ID for an existing app. The only scope flag agents need; the wizard derives org, project, and environment automatically. | | `--project-id ` | Numeric Amplitude project ID. Use when scoping to a project rather than a specific app. | | `--resume` | Load the saved checkpoint and skip already-completed steps. Useful after a SIGPIPE or interrupted run. | | `--json` | Machine-readable JSON output without the auto-approve side effects of `--agent`. | 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: ```shell npx @amplitude/wizard plan --json npx @amplitude/wizard apply --plan-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 --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](https://modelcontextprotocol.io) 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: ```json { "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` runs: | Variable | Effect | | ------------------------------ | ---------------------------------------------------------------------------------------------- | | `AMPLITUDE_WIZARD_AGENT=1` | Force agent mode (NDJSON output, auto-approve prompts). | | `AMPLITUDE_WIZARD_API_KEY` | Amplitude project API key. Equivalent to `--api-key`. | | `AMPLITUDE_WIZARD_INSTALL_DIR` | Directory to install in. Equivalent to `--install-dir`. | | `AMPLITUDE_WIZARD_PROJECT_ID` | Amplitude project ID. Equivalent to `--project-id`. | | `AMPLITUDE_WIZARD_YES` | Skip all confirmation prompts. Equivalent to `--yes`. | | `AMPLITUDE_TOKEN` | OAuth access-token override. Requires a prior `npx @amplitude/wizard login` to mint the token. | | `AMPLITUDE_WIZARD_TOKEN` | Alias for `AMPLITUDE_TOKEN`. | | `AMPLITUDE_WIZARD_MAX_TURNS` | Override the inner agent's per-run turn cap (default 200, max 10000). | ### Exit codes Orchestrators can branch on the wizard's exit code: | Code | Meaning | | ----- | ------------------------ | | `0` | Success. | | `1` | General error. | | `2` | Invalid arguments. | | `3` | Authentication required. | | `4` | Network error. | | `10` | Inner agent failed. | | `130` | User cancelled (Ctrl+C). | 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`. ```json { "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](https://github.com/amplitude/wizard). Share what's working and what you'd like next: wizard@amplitude.com.