AMPLITUDE-WIZARD(1)

NAME
amplitude-wizard - instrument your app with Amplitude analytics

SYNOPSIS
amplitude-wizard [OPTIONS]
amplitude-wizard COMMAND [OPTIONS]

DESCRIPTION
amplitude-wizard is an interactive CLI that instruments applications with Amplitude analytics. It authenticates the user, detects the project framework, runs a Claude-powered agent to set up the SDK and track events, and guides the user through their first chart and dashboard.

Run without arguments to launch the interactive TUI wizard. The wizard auto-detects your framework (Next.js, React, Vue, Django, Flask, FastAPI, etc.) and writes the necessary SDK boilerplate.

COMMANDS

(default)
    Run the interactive Amplitude setup wizard. Launches a full-screen TUI.

login
    Log in to your Amplitude account via browser OAuth. Credentials are stored in ~/.ampli.json for subsequent runs.

logout
    Remove the locally stored Amplitude credentials.

whoami
    Print the currently logged-in user and org.

slack
    Set up the Amplitude Slack integration.

mcp add
    Install the Amplitude MCP server into supported AI clients (Claude, Cursor, etc.).

mcp remove
    Remove the Amplitude MCP server from supported AI clients.

completion
    Print a shell completion script for bash or zsh. Source it in your shell rc:
    eval "$(amplitude-wizard completion)"

OPTIONS

  Global options

--debug
    Enable verbose logging to the log file and console. Environment variable: AMPLITUDE_WIZARD_DEBUG

--verbose
    Print diagnostic info (working directory, detected framework, config) to the run log. Environment variable: AMPLITUDE_WIZARD_VERBOSE

--signup
    Create a new Amplitude account during setup instead of logging in. Environment variable: AMPLITUDE_WIZARD_SIGNUP

--ci
    Enable non-interactive CI mode. Requires --api-key and --install-dir. Environment variable: AMPLITUDE_WIZARD_CI

--api-key KEY
    Amplitude project API key. Skips the browser OAuth flow entirely. Environment variable: AMPLITUDE_WIZARD_API_KEY

--project-id ID
    Amplitude project ID. Optional; defaults to the project associated with the API key or the saved OAuth session. Environment variable: AMPLITUDE_WIZARD_PROJECT_ID

--local-mcp
    Route MCP calls to a local server at http://localhost:8787/mcp instead of the production endpoint. Environment variable: AMPLITUDE_WIZARD_LOCAL_MCP

-h, --help
    Show help and exit.

-v, --version
    Print the package version and exit.

  Wizard (default command) options

--integration FRAMEWORK
    Skip auto-detection and use the specified framework integration. Choices: nextjs, vue, react-router, django, flask, fastapi, javascript_web, javascript_node, python. Environment variable: AMPLITUDE_WIZARD_INTEGRATION

--install-dir DIR
    Directory to install Amplitude in. Defaults to the current working directory. Environment variable: AMPLITUDE_WIZARD_INSTALL_DIR

--force-install
    Force package installation even if peer dependency checks fail. Environment variable: AMPLITUDE_WIZARD_FORCE_INSTALL

--menu
    Show the framework selection menu instead of auto-detecting. Environment variable: AMPLITUDE_WIZARD_MENU

--benchmark
    Run in benchmark mode with per-phase token tracking. Environment variable: AMPLITUDE_WIZARD_BENCHMARK

  login options

--zone us|eu
    Amplitude data center zone. Default: us.

ENVIRONMENT
All flags can also be set as environment variables by prefixing with AMPLITUDE_WIZARD_ and uppercasing. For example:

export AMPLITUDE_WIZARD_API_KEY=my-key
export AMPLITUDE_WIZARD_CI=true
amplitude-wizard

FILES

~/.ampli.json
    Stores the OAuth access token, refresh token, and user metadata (name, email, org, zone). Written by login and cleared by logout.

./ampli.json
    Project-level config written by the wizard after setup. Contains the Amplitude Source ID, Workspace ID, SDK runtime, and branch information.

/tmp/amplitude-wizard.log
    Runtime log file. Captures verbose/debug output and agent traces.

EXAMPLES

Run the wizard in the current directory:
    amplitude-wizard

Run the wizard against a specific directory:
    amplitude-wizard --install-dir /path/to/project

Run in CI (non-interactive):
    amplitude-wizard --ci --api-key <key> --install-dir .

Force Next.js integration without auto-detection:
    amplitude-wizard --integration nextjs

Set up shell completions (bash/zsh):
    echo 'eval "$(amplitude-wizard completion)"' >> ~/.zshrc
    source ~/.zshrc

Log in to the EU data center:
    amplitude-wizard login --zone eu

SEE ALSO
Full documentation and source: https://github.com/amplitude/wizard