Set up Amplitude analytics in your app — from zero to first chart — with one command.

npx @amplitude/wizard

The wizard authenticates you, detects your framework, runs an AI agent to instrument the SDK and events, verifies data is flowing, and walks you through your first chart and dashboard. All from the terminal.

Requires Node.js >= 20.

Unrecognized frameworks fall back to a generic integration.

npx @amplitude/wizard

  ✓ Welcome  ✓ Auth  ● Setup  ○ Verify  ○ Done
  ─────────────────────────────────────────────

  Detecting framework... Found Next.js 15

  The agent is setting up Amplitude in your project.
  Current file: src/app/layout.tsx
  Tasks: 3/5 complete · 42s elapsed

  ❯ _

  [/] Commands  [Tab] Ask a question

1. Sign in — authenticates with your Amplitude account (or creates one)
2. Detect — identifies your framework and project structure
3. Instrument — proposes an event plan for your review, then writes the code
4. Verify — confirms events are flowing into Amplitude
5. Explore — walks you through your first chart, dashboard, and taxonomy

Every successful run drops an amplitude-setup-report.md at the project root summarizing what changed, what to verify, and how to extend the instrumentation. The previous run's report is archived alongside it as amplitude-setup-report.previous.md.

For browser-based SDK projects (Next.js, Vue, React Router, JavaScript web), the wizard auto-enables Autocapture, Session Replay, and Guides & Surveys when the project is using Amplitude's unified Browser SDK — no extra opt-in screens. Type any slash command (e.g. /whoami, /diagnostics) at any time; the prompt accepts them throughout the session.

Interactive (default) — rich terminal UI with progress, slash commands, and inline guidance:

npx @amplitude/wizard

CI — no prompts, no colors, for pipelines:

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

Agent — streams NDJSON for programmatic consumption:

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

AI coding agents can drive the wizard end-to-end. Point your agent at the CLI and it will detect the framework, check project state, and report back as JSON — no prompt parsing required.

The wizard ships a Claude Code skill at .claude/skills/amplitude-setup/ inside the published npm package. Once @amplitude/wizard is available (via npx or npm install), Claude Code will discover the skill when the user asks to set up Amplitude. The skill drives the right commands in the right order, surfaces every important moment to the user (which Amplitude app, which events, which files are about to be written), and never silently auto-approves.

What the skill enforces:

• Always runs apply in the foreground so NDJSON streams in real time.
• Always passes --confirm-app so the user gets to confirm which Amplitude app the wizard will write events into.
• Always surfaces the proposed event_plan to the user and re-invokes with --approve-events / --skip-events / --revise-events based on the user's answer.
• After setup_complete it pins the project context to amplitude.appId for follow-up Amplitude MCP queries — no more "wrong project" charts.

If your project doesn't pick up the skill automatically, copy it once:

mkdir -p .claude/skills
cp -R "$(npm root)/@amplitude/wizard/.claude/skills/amplitude-setup" .claude/skills/

Kick it off from your agent:

> Set up Amplitude on this project.

The agent will typically run:

npx @amplitude/wizard manifest            # introspect the CLI surface (JSON)
npx @amplitude/wizard detect --json       # detect framework
npx @amplitude/wizard status --json       # get full project state
npx @amplitude/wizard auth status --json  # check if the human is logged in
npx @amplitude/wizard plan --json         # build a setup plan (no writes) → planId
npx @amplitude/wizard apply --plan-id <id> --yes   # execute a previously generated plan
npx @amplitude/wizard verify --json       # confirm SDK + API key + framework are in place
npx @amplitude/wizard --agent             # run the full wizard in NDJSON mode

npx @amplitude/wizard works without installation. If the package is globally installed (npm install -g @amplitude/wizard), the shorter amplitude-wizard bin resolves to the same entry point.

Authentication in-the-loop. Pick the mode that matches how much human-in-the-loop you can tolerate. Only Option 2 requires a browser click; Options 1, 3, and 4 are fully scriptable:

# Option 1: inline project API key (preferred for CI / full automation
# against an existing Amplitude project)
npx @amplitude/wizard --agent --install-dir . --api-key <key>

# Option 2: prior interactive login on the same machine, then run
npx @amplitude/wizard login                 # one-time browser click
npx @amplitude/wizard --agent --install-dir .

# Option 3: read the stored OAuth token for other scripts
npx @amplitude/wizard auth token            # stdout: <access-token>

# Option 4: zero-touch — create a brand-new Amplitude account and app
# inline, no browser click, no prior login. Suitable for AI coding agents
# bootstrapping a project from scratch.
#
# ⚠️ --accept-tos programmatically accepts Amplitude's Terms of Service
#    on the user's behalf. AI agents MUST confirm consent with the human
#    before passing it — do not default it on.
# ⚠️ --region picks the data-center region (US or EU) for the new
#    account and has data-residency implications. AI agents MUST ask the
#    human which region they want — do not default to us or eu on their
#    behalf.
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

Option 4 notes:

• --auth-onboarding create-account switches OAuth from sign-in to a direct signup path; the wizard logs Direct signup succeeded; using newly created account. on success.
• --email, --full-name, --accept-tos, and --region are all required when combining create-account with --agent / --ci (the wizard has no TTY to prompt for them).
• --app-name triggers app creation under the new account in agent mode. Omit it only if you intend to bind to an existing app via --app-id.
• ⚠️ --accept-tos programmatically accepts Amplitude's Terms of Service on the user's behalf. AI coding agents and orchestrators must not pass this flag without explicit consent from the human whose account is being created — the ToS acceptance is legally binding on them, not on the agent. Treat it the same as a click-through "I agree" checkbox: ask first, pass the flag only after the user has confirmed they've read and accepted the terms. Omitting the flag in --agent / --ci mode is a hard error, which is the intended safeguard.
• ⚠️ --region (us or eu) selects the data center for the new account and has data-residency implications. AI coding agents and orchestrators must not default this flag on the human's behalf — ask the human which region applies to them (regulatory requirements, internal data-handling policies, or simply where their other Amplitude data already lives) and pass the chosen value verbatim.
• --agent already implies --auto-approve; -y is still needed to grant the inner agent write capability.
• Do not pipe --agent output through head, tail, or grep — SIGPIPE will kill the inner setup agent mid-run. Redirect to a file (> wizard.log 2>&1) and tail it separately. If a run is interrupted, resume with npx @amplitude/wizard --agent --resume -y.

Agent-friendly verbs:

All commands auto-emit JSON when stdout is piped. Use --human to override and force human-readable output. --json enables JSON output without the auto-approve side effects of --agent (so you can script but still get prompted for confirmation when needed).

Plan / apply / verify. For orchestrators that want a human in the loop on the diff, split the run into three phases: plan builds a WizardPlan (framework, SDK, intended file changes) and returns a planId; apply --plan-id <id> --yes executes it within 24 hours; verify confirms the result. plan and verify never write to disk. The plan JSON output includes a ready-to-run resumeFlags array — feed it straight back into apply.

Selecting an Amplitude project. Amplitude's hierarchy is Org → Project → Environment → App. When multiple match, pick one with a flag — --project-id is unambiguous; the others narrow when needed:

When running --agent without a selector and the user has multiple projects, the wizard emits a prompt event with promptType: "environment_selection" carrying a flat choices array plus pre-built resumeFlags so the orchestrator can show the human a picker and re-invoke with the chosen flags. Run amplitude-wizard manifest for the full glossary.

Environment variables:

NDJSON schema. Every event emitted in --agent mode carries a v:1 version tag and a typed envelope. The stream includes inner-agent lifecycle events plus file_change events for every write the agent makes — orchestrators can render a live diff without tailing the filesystem. See docs/dual-mode-architecture.md for the full schema and deprecation policy.

Auth-required signal. When an agent-mode run starts without valid credentials, the wizard emits a structured lifecycle event and exits with code 3 (AUTH_REQUIRED) instead of a plain error log. Orchestrators can surface the instruction to the human, trigger the login, then re-run:

{
  "v": 1,
  "type": "lifecycle",
  "level": "error",
  "message": "Not signed in to Amplitude. Ask the user to run `npx @amplitude/wizard login`...",
  "data": {
    "event": "auth_required",
    "reason": "no_stored_credentials",
    "loginCommand": ["npx", "@amplitude/wizard", "login"],
    "resumeCommand": ["npx", "@amplitude/wizard", "--agent"]
  }
}

Reason values: no_stored_credentials, token_expired, refresh_failed, env_selection_failed.

Tip for orchestrators: on no_stored_credentials, an alternative to surfacing the loginCommand to the human is to re-invoke with the Option 4 flags above (--auth-onboarding create-account + --email, --full-name, --accept-tos, --region, --app-name) to create a fresh account inline. Note this is not zero-prompt: --accept-tos and --region are user-facing decisions (ToS consent, data residency) — ask the human for both before passing them.

Nested-invocation signal. Running the wizard from inside another AI coding agent session is supported. The wizard spawns its own agent subprocess for the setup agent, and inherited env vars from the outer session (CLAUDECODE=1, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_AGENT_SDK_VERSION, etc.) would otherwise leak into the inner subprocess and cause the LLM gateway to reject requests with a 400. The wizard strips those vars before spawning, so nested runs succeed.

When nesting is detected the wizard emits a diagnostic so outer agent orchestrators can log the signal:

{
  "v": 1,
  "type": "lifecycle",
  "level": "info",
  "message": "Detected nested agent invocation via CLAUDECODE=1...",
  "data": {
    "event": "nested_agent",
    "signal": "claude_code_cli",
    "detectedEnvVar": "CLAUDECODE",
    "bypassEnv": "AMPLITUDE_WIZARD_ALLOW_NESTED"
  }
}

Detection looks for CLAUDECODE=1 or CLAUDE_CODE_ENTRYPOINT env vars. Set AMPLITUDE_WIZARD_ALLOW_NESTED=1 to skip the diagnostic entirely (sanitization still runs).

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

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

If you've installed globally (npm install -g @amplitude/wizard), you can use the bin directly:

{
  "mcpServers": {
    "amplitude-wizard": {
      "command": "amplitude-wizard",
      "args": ["mcp", "serve"]
    }
  }
}

Tools exposed:

Available at any point during the wizard:

Some commands (/login, /logout, /region, /create-project) are paused while a setup run is active — cancel with Ctrl+C or wait for it to finish.

The wizard remembers your login, org, project, and region across runs. Expired sessions refresh silently — you won't be asked to re-authenticate unless necessary. If the wizard is interrupted, the next launch in the same directory picks up where you left off.

Run /diagnostics at any time to print the exact paths for the current project — handy for filing bug reports.

pnpm install
pnpm build
pnpm try          # run the wizard from source (no build needed)

See CLAUDE.md for full architecture documentation.

Contributing: CONTRIBUTING.md — setup, tests, and PR workflow (including AI-assisted changes and when to attach a /reflect checklist).

pnpm test             # unit tests (vitest)
pnpm test:watch       # watch mode
pnpm test:bdd         # BDD / Cucumber tests
pnpm test:e2e         # end-to-end tests
pnpm test:proxy       # proxy health check
pnpm lint             # prettier + eslint
pnpm fix              # auto-fix lint issues

Hat tip to PostHog's CLI for early inspiration. Amplitude's Wizard is an independent project, licensed under MIT. We welcome contributions from anyone.