DOCSEARCHbyAlgolia
Submit Docs

Amplitude Wizard Agent Reference

website·Indexed 19 days ago

https://amplitude.com/

Full reference for AI coding agents interacting with the @amplitude/wizard CLI. Includes invocation methods via npx or global installation, agent-friendly verbs, capability flags, the NDJSON contract for event envelopes, and a technical glossary.

Tokens
2.6K
Snippets
13
Records
15
Agent score
49%

What's inside @amplitude/wizard

  1. Discover Amplitude Wizard capabilities via the manifest

    Agents should always start by reading the manifest to obtain the current stable contract. The manifest is a typed JSON document (schemaVersion: 1) containing:

    • invocations: Valid argv prefixes.
    • concepts.hierarchy: The organizational structure (["org", "project", "app", "environment"]).
    • concepts.glossary: Definitions of Amplitude terms.
    • globalFlags and env: All available flags and environment variables with defaults.
    • exitCodes: Documented exit codes.
    • commands: Available subcommands and their specific flags.
    npx @amplitude/wizard manifest

  2. Provide input to Amplitude Wizard via stdin

    When the wizard emits a needs_input event (paired with exit code 12 if --auto-approve is not set), it pauses for user input. There are three ways to resolve this, in order of priority:

    1. Resume Flags: Re-invoke the wizard using one of the resumeFlags provided in the event data.
    2. Stdin Pipe: Pipe a single JSON line matching the responseSchema to stdin.
    3. Auto-approve: Pass the --auto-approve flag, and the wizard will select the recommended value.
    # Example: Providing an appId via stdin
echo '{"appId":"769610"}' | npx @amplitude/wizard --agent --install-dir .

  4. Verify Amplitude Wizard installation and setup

    Use the following commands and files to verify the state of the SDK installation and event flow.
    # Verify if SDK init was written
npx @amplitude/wizard verify --json

# Check approved event plan
cat .amplitude/events.json

# Check created dashboard URL
cat .amplitude/dashboard.json

# View human-readable setup report
cat amplitude-setup-report.md

# Check if events are flowing
npx @amplitude/wizard status --json | jq '.eventIngestion'

  5. Resolve authentication requirements in Amplitude Wizard

    When the wizard emits an auth_required event (paired with exit code 3), the agent must prompt the user to authenticate. The event payload provides the exact commands needed to log in and resume the operation.
    {
  "v": 1,
  "type": "lifecycle",
  "level": "error",
  "message": "Not signed in to Amplitude...",
  "data": {
    "event": "auth_required",
    "reason": "no_stored_credentials",
    "loginCommand": ["npx", "@amplitude/wizard", "login"],
    "resumeCommand": ["npx", "@amplitude/wizard", "--agent"]
  }
}

  6. Configure Amplitude Wizard via environment variables

    The wizard reads several environment variables to control behavior, authentication, and logging.
    # Project ingestion key (same as --api-key) - embedded in client code
export AMPLITUDE_WIZARD_API_KEY=your_key

# OAuth access-token override - NOT embedded in client code
export AMPLITUDE_TOKEN=your_token

# Force agent mode (NDJSON, auto-approve)
export AMPLITUDE_WIZARD_AGENT=1

# Inner-agent turn cap (Default 200, Max 10000)
export AMPLITUDE_WIZARD_MAX_TURNS=500

# Verbose logging to project log file
export AMPLITUDE_WIZARD_DEBUG=1

# Override log file path
export AMPLITUDE_WIZARD_LOG=/path/to/log

# Skip nested_agent diagnostic when running inside another agent
export AMPLITUDE_WIZARD_ALLOW_NESTED=1

# Override cache root (~/.amplitude/wizard/)
export AMPLITUDE_WIZARD_CACHE_DIR=/custom/cache

  7. Configure Amplitude Wizard MCP server

    The Amplitude Wizard provides an MCP (Model Context Protocol) stdio server that exposes read-only operations as typed tools for AI agents (e.g., Claude Code, Cursor, Windsurf). To execute a plan generated by the MCP server, use the apply CLI subcommand.
    {
  "mcpServers": {
    "amplitude-wizard": {
      "command": "npx",
      "args": ["-y", "@amplitude/wizard", "mcp", "serve"]
    }
  }
}

    To execute a plan returned by the MCP server:

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

  8. Handle Amplitude Wizard exit codes

    Orchestrators should use these exit codes to determine the next action when the wizard terminates.
    0: SUCCESS -> Continue
1: GENERAL_ERROR -> Log and abort
2: INVALID_ARGS -> Fix flags and re-invoke
3: AUTH_REQUIRED -> Surface instruction to user, run login, re-invoke
4: NETWORK_ERROR -> Retry with backoff
10: AGENT_FAILED -> Transient error, retry once
11: PROJECT_NAME_TAKEN -> Pick new name and re-invoke
12: INPUT_REQUIRED -> Surface 'needs_input' event to user, re-invoke with resumeFlags
13: WRITE_REFUSED -> Re-invoke with --yes or --force
20: INTERNAL_ERROR -> File bug at github.com/amplitude/wizard/issues
130: USER_CANCELLED -> Abort

  9. Handle Amplitude Wizard NDJSON event envelopes

    When running the Amplitude Wizard in agent mode, it emits events as NDJSON. Agents should branch on data.event for structured payloads rather than parsing the human-readable message string. The envelope version v only increments on breaking changes to the envelope itself; individual event shapes are versioned via data_version.
    interface AgentEventEnvelope<TData = unknown> {
  v: 1;                                 // wire version
  '@timestamp': string;                 // ISO 8601
  type:
    | 'lifecycle'                       // run start/end, auth_required, etc.
    | 'log'                             // info / warn / error / success / step
    | 'status'                          // notes, push status, heartbeats, spinners
    | 'progress'                        // tool_call, file_change_planned, etc.
    | 'result'                          // file_change_applied, etc.
    | 'error'                           // setRunError, project_create_error
    | 'prompt'                          // legacy
    | 'needs_input'                     // canonical structured prompt
    | 'diagnostic'                      // service status, retry state
    | 'session_state';                  // region, framework, credentials_set, etc.
  message: string;                      // human-readable
  session_id?: string;
  run_id?: string;
  data_version?: number;                // per-event-type shape version
  data?: TData;                         // event-specific payload
  level?: 'info' | 'warn' | 'error' | 'success' | 'step';
}

  10. Amplitude Wizard constraints and best practices

    Avoid the following common pitfalls when interacting with the @amplitude/wizard CLI:

    • Node Version: Requires Node ≥ 20. Node 18 is not supported.
    • Configuration: Use --app-id instead of --org and --project-id for unambiguous targeting.
    • Secrets: API keys and tokens are redacted from stdout. Read them from ~/.ampli.json or the OS keychain.
    • Retries:
      • Do not retry on exit 11 (PROJECT_NAME_TAKEN) without changing the project name.
      • Do not retry on exit 12 (INPUT_REQUIRED) or 13 (WRITE_REFUSED) without providing a different flag or resolving the needs_input event.
    • TUI: The interactive TUI only renders on a TTY. Use --agent to force NDJSON output.
    • Tokens: Use the project API key (--api-key or AMPLITUDE_WIZARD_API_KEY) in client code; AMPLITUDE_TOKEN (OAuth) is for server-side use only.

  11. Manage agent capabilities and write permissions

    The wizard uses capability flags to control whether the inner agent can approve changes or write to the filesystem. If a write is attempted without the required capability, the wizard exits with code 13 (WRITE_REFUSED).
    # Only auto-approve prompts, no writes
--auto-approve

# Auto-approve and allow writes (CI friendly)
--yes # or -y or --ci

# Auto-approve, allow writes, and allow destructive changes
--force

# Full agent mode (auto-approve + allow writes)
--agent

  12. Use Amplitude Wizard agent-friendly commands

    The CLI provides several commands designed for programmatic use. All commands auto-emit JSON when stdout is piped; use --json to force JSON without agent side-effects, or --human to force human-readable output.
    # Discover CLI capabilities
npx @amplitude/wizard manifest

# Identify the app framework
npx @amplitude/wizard detect --json

# Check full project state
npx @amplitude/wizard status --json

# Build a setup plan (returns planId with 24h TTL)
npx @amplitude/wizard plan --json

# Execute a previously generated plan
npx @amplitude/wizard apply --plan-id <id> --yes

# Post-run sanity check
npx @amplitude/wizard verify --json

# Check login state and token expiry
npx @amplitude/wizard auth status --json

# Get OAuth token for scripts
npx @amplitude/wizard auth token

# List user projects/environments
npx @amplitude/wizard projects list --json --query <q>

# Expose wizard as MCP tools
npx @amplitude/wizard mcp serve

# Full end-to-end setup (streams NDJSON)
npx @amplitude/wizard --agent