@amplitude/wizard 1.0.0-beta.0

package/dist/src/utils/shell-completions.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASH_COMPLETION_SCRIPT = exports.ZSH_COMPLETION_SCRIPT = void 0;
+exports.detectShell = detectShell;
+exports.installCompletions = installCompletions;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const EVAL_LINE = `eval "$(amplitude-wizard completion)"`;
+/** Substring used to detect whether the eval line is already present. */
+const MARKER = 'amplitude-wizard completion';
+function detectShell() {
+    const shell = process.env.SHELL ?? '';
+    if (shell.endsWith('zsh'))
+        return 'zsh';
+    if (shell.endsWith('bash'))
+        return 'bash';
+    return null;
+}
+function getRcFile(shell) {
+    const home = os.homedir();
+    if (shell === 'zsh')
+        return path.join(home, '.zshrc');
+    // On macOS bash sessions are login shells; prefer .bash_profile if present.
+    const bashProfile = path.join(home, '.bash_profile');
+    if (fs.existsSync(bashProfile))
+        return bashProfile;
+    return path.join(home, '.bashrc');
+}
+// Inject shell variable syntax (${) without triggering TS template interpolation.
+const DB = '${';
+exports.ZSH_COMPLETION_SCRIPT = `###-begin-amplitude-wizard-completions-###
+
+_amplitude_wizard() {
+  local state
+  local -a commands global_opts wizard_opts
+
+  commands=(
+    'login:Log in to your Amplitude account'
+    'logout:Log out of your Amplitude account'
+    'whoami:Show the currently logged-in Amplitude account'
+    'slack:Set up Amplitude Slack integration'
+    'mcp:MCP server management commands'
+    'completion:Print shell completion script'
+  )
+
+  global_opts=(
+    '--debug[Enable verbose logging]'
+    '--verbose[Print diagnostic info to the run log]'
+    '--signup[Create a new Amplitude account during setup]'
+    '--ci[Enable non-interactive CI mode]'
+    '--api-key[Amplitude project API key]:key:'
+    '--project-id[Amplitude project ID]:id:'
+    '--local-mcp[Use local MCP server at http://localhost:8787/mcp]'
+    {-h,--help}'[Show help]'
+    {-v,--version}'[Show version]'
+  )
+
+  wizard_opts=(
+    '--force-install[Force package install even if peer checks fail]'
+    '--install-dir[Directory to install Amplitude in]:dir:_files -/'
+    '--integration[Framework integration to set up]:integration:(nextjs vue react-router django flask fastapi javascript_web javascript_node python)'
+    '--menu[Show integration selection menu instead of auto-detecting]'
+    '--benchmark[Run in benchmark mode with per-phase token tracking]'
+  )
+
+  _arguments -C \\
+    '1: :->cmd' \\
+    '*:: :->args'
+
+  case $state in
+    cmd)
+      _describe 'command' commands
+      _arguments $global_opts $wizard_opts
+      ;;
+    args)
+      case ${DB}words[1]} in
+        mcp)
+          local -a mcp_cmds
+          mcp_cmds=('add:Install Amplitude MCP server' 'remove:Remove Amplitude MCP server')
+          _arguments -C '1: :->sub' '*:: :->subargs'
+          case $state in
+            sub) _describe 'mcp command' mcp_cmds ;;
+            subargs) _arguments '--local[Use local MCP server at http://localhost:8787]' ;;
+          esac
+          ;;
+        login)
+          _arguments '--zone[Amplitude data center zone]:zone:(us eu)'
+          ;;
+        *)
+          _arguments $global_opts $wizard_opts
+          ;;
+      esac
+      ;;
+  esac
+}
+
+(( $+functions[compdef] )) || { autoload -Uz compinit; compinit; }
+compdef _amplitude_wizard amplitude-wizard
+###-end-amplitude-wizard-completions-###`;
+exports.BASH_COMPLETION_SCRIPT = `###-begin-amplitude-wizard-completions-###
+_amplitude_wizard_completions() {
+  local cur prev
+  cur="${DB}COMP_WORDS[COMP_CWORD]}"
+  prev="${DB}COMP_WORDS[COMP_CWORD-1]}"
+
+  local commands="login logout whoami slack mcp completion"
+  local global_flags="--debug --verbose --signup --ci --api-key --project-id --local-mcp --help --version"
+  local wizard_flags="--force-install --install-dir --integration --menu --benchmark"
+  local integrations="nextjs vue react-router django flask fastapi javascript_web javascript_node python"
+
+  if [[ ${DB}COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "$commands $global_flags $wizard_flags" -- "$cur"))
+    return
+  fi
+
+  case "${DB}COMP_WORDS[1]}" in
+    mcp)
+      if [[ ${DB}COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=($(compgen -W "add remove" -- "$cur"))
+      else
+        COMPREPLY=($(compgen -W "--local" -- "$cur"))
+      fi
+      ;;
+    login)
+      if [[ "$prev" == "--zone" ]]; then
+        COMPREPLY=($(compgen -W "us eu" -- "$cur"))
+      else
+        COMPREPLY=($(compgen -W "--zone" -- "$cur"))
+      fi
+      ;;
+    *)
+      if [[ "$prev" == "--integration" ]]; then
+        COMPREPLY=($(compgen -W "$integrations" -- "$cur"))
+      elif [[ "$prev" == "--install-dir" ]]; then
+        COMPREPLY=($(compgen -d -- "$cur"))
+      else
+        COMPREPLY=($(compgen -W "$global_flags $wizard_flags" -- "$cur"))
+      fi
+      ;;
+  esac
+}
+complete -F _amplitude_wizard_completions amplitude-wizard
+###-end-amplitude-wizard-completions-###`;
+/**
+ * Silently appends `eval "$(amplitude-wizard completion)"` to the user's shell
+ * RC file if it isn't already there.  Call fire-and-forget at startup.
+ */
+function installCompletions() {
+    try {
+        const shell = detectShell();
+        if (!shell)
+            return;
+        const rcFile = getRcFile(shell);
+        if (fs.existsSync(rcFile)) {
+            const contents = fs.readFileSync(rcFile, 'utf-8');
+            if (contents.includes(MARKER))
+                return; // already installed
+        }
+        const line = `\n# Amplitude Wizard shell completions\n${EVAL_LINE}\n`;
+        fs.appendFileSync(rcFile, line, 'utf-8');
+    }
+    catch {
+        // Never surface completion-install errors to the user.
+    }
+}

package/dist/src/utils/string.d.ts

@@ -0,0 +1 @@
+export declare function stripAnsii(str: string): string;

package/dist/src/utils/string.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripAnsii = stripAnsii;
+function stripAnsii(str) {
+    return str.replace(
+    // eslint-disable-next-line no-control-regex
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
+}

package/dist/src/utils/types.d.ts

@@ -0,0 +1,72 @@
+export type AmplitudeProjectData = Record<string, unknown>;
+export type PreselectedProject = {
+    project: AmplitudeProjectData;
+    authToken: string;
+};
+export type WizardOptions = {
+    /**
+     * Whether to enable debug mode.
+     */
+    debug: boolean;
+    /**
+     * Whether to force install the SDK package to continue with the installation in case
+     * any package manager checks are failing (e.g. peer dependency versions).
+     *
+     * Use with caution and only if you know what you're doing.
+     *
+     * Does not apply to all wizard flows (currently NPM only)
+     */
+    forceInstall: boolean;
+    /**
+     * The directory to run the wizard in.
+     */
+    installDir: string;
+    /**
+     * Whether to select the default option for all questions automatically.
+     */
+    default: boolean;
+    /**
+     * Whether to create a new Amplitude account during setup.
+     */
+    signup: boolean;
+    /**
+     * Whether to use the local MCP server at http://localhost:8787/mcp
+     */
+    localMcp: boolean;
+    /**
+     * CI mode - non-interactive execution
+     */
+    ci: boolean;
+    /**
+     * Personal API key (phx_xxx) - used for LLM gateway auth, skips OAuth
+     */
+    apiKey?: string;
+    /**
+     * Amplitude project ID. When set (e.g. in CI with --project-id), the wizard uses this project
+     * instead of the default from the API key or OAuth.
+     */
+    projectId?: number;
+    /**
+     * Whether to show the menu for manual integration selection instead of auto-detecting.
+     */
+    menu: boolean;
+    /**
+     * Whether to run in benchmark mode with per-phase token tracking.
+     * When enabled, the wizard runs each workflow phase as a separate agent call
+     * and writes detailed usage data to /tmp/amplitude-wizard-benchmark.json.
+     */
+    benchmark: boolean;
+};
+export interface Feature {
+    id: string;
+    prompt: string;
+    enabledHint?: string;
+    disabledHint?: string;
+}
+export type FileChange = {
+    filePath: string;
+    oldContent?: string;
+    newContent: string;
+};
+export type CloudRegion = 'us' | 'eu';
+export type AIModel = 'gpt-5-mini' | 'o4-mini' | 'gemini-2.5-flash' | 'gemini-2.5-pro';

package/dist/src/utils/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utils/urls.d.ts

@@ -0,0 +1,14 @@
+import type { CloudRegion } from './types';
+export declare const getHostFromRegion: (region: CloudRegion) => "http://localhost:8010" | "https://api2.amplitude.com" | "https://api.eu.amplitude.com";
+export declare const getCloudUrlFromRegion: (region: CloudRegion) => "https://app.amplitude.com" | "https://eu.amplitude.com";
+export declare function detectRegionFromToken(accessToken: string): Promise<CloudRegion>;
+/**
+ * Get the LLM proxy URL for the Claude Agent SDK.
+ *
+ * Routes through the wizard-proxy-router in Thunder (javascript repo), which
+ * validates Amplitude OAuth tokens and proxies to GCP Vertex AI.
+ *
+ * Override with WIZARD_LLM_PROXY_URL env var for explicit URL override.
+ * The Claude Agent SDK uses this as ANTHROPIC_BASE_URL and appends /v1/messages.
+ */
+export declare const getLlmGatewayUrlFromHost: (host: string) => string;

package/dist/src/utils/urls.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLlmGatewayUrlFromHost = exports.getCloudUrlFromRegion = exports.getHostFromRegion = void 0;
+exports.detectRegionFromToken = detectRegionFromToken;
+const axios_1 = __importDefault(require("axios"));
+const constants_1 = require("../lib/constants");
+const getHostFromRegion = (region) => {
+    if (constants_1.IS_DEV) {
+        return 'http://localhost:8010';
+    }
+    if (region === 'eu') {
+        return 'https://api.eu.amplitude.com';
+    }
+    return 'https://api2.amplitude.com';
+};
+exports.getHostFromRegion = getHostFromRegion;
+const getCloudUrlFromRegion = (region) => {
+    if (region === 'eu') {
+        return 'https://eu.amplitude.com';
+    }
+    return 'https://app.amplitude.com';
+};
+exports.getCloudUrlFromRegion = getCloudUrlFromRegion;
+async function detectRegionFromToken(accessToken) {
+    if (constants_1.IS_DEV) {
+        return 'us';
+    }
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        'User-Agent': constants_1.WIZARD_USER_AGENT,
+    };
+    const [usResult, euResult] = await Promise.allSettled([
+        axios_1.default.get('https://us.amplitude.com/api/users/@me/', { headers }),
+        axios_1.default.get('https://eu.amplitude.com/api/users/@me/', { headers }),
+    ]);
+    if (usResult.status === 'fulfilled')
+        return 'us';
+    if (euResult.status === 'fulfilled')
+        return 'eu';
+    throw new Error('Could not determine cloud region from access token. Please check your Amplitude account.');
+}
+/**
+ * Get the LLM proxy URL for the Claude Agent SDK.
+ *
+ * Routes through the wizard-proxy-router in Thunder (javascript repo), which
+ * validates Amplitude OAuth tokens and proxies to GCP Vertex AI.
+ *
+ * Override with WIZARD_LLM_PROXY_URL env var for explicit URL override.
+ * The Claude Agent SDK uses this as ANTHROPIC_BASE_URL and appends /v1/messages.
+ */
+const getLlmGatewayUrlFromHost = (host) => {
+    // Allow explicit override for local proxy development
+    const proxyOverride = process.env.WIZARD_LLM_PROXY_URL;
+    if (proxyOverride) {
+        return proxyOverride;
+    }
+    if (host.includes('localhost')) {
+        // Local dev: point at the local proxy (start with `pnpm proxy` in the wizard repo)
+        return 'http://localhost:3030/wizard';
+    }
+    if (host.includes('eu.amplitude.com')) {
+        return 'https://core.eu.amplitude.com/wizard';
+    }
+    return 'https://core.amplitude.com/wizard';
+};
+exports.getLlmGatewayUrlFromHost = getLlmGatewayUrlFromHost;

package/dist/src/utils/vendor/is-unicorn-supported.d.ts

@@ -0,0 +1 @@
+export declare function isUnicodeSupported(): boolean;

package/dist/src/utils/vendor/is-unicorn-supported.js

@@ -0,0 +1,23 @@
+"use strict";
+// Vendored from: https://github.com/sindresorhus/is-unicode-supported/blob/c80c691dde9e2fcfe3996810858c6672c8f35ad9/index.js#L3
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUnicodeSupported = isUnicodeSupported;
+// MIT License
+// Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+function isUnicodeSupported() {
+    if (process.platform !== 'win32') {
+        return process.env.TERM !== 'linux'; // Linux console (kernel)
+    }
+    return (Boolean(process.env.CI) ||
+        Boolean(process.env.WT_SESSION) || // Windows Terminal
+        Boolean(process.env.TERMINUS_SUBLIME) || // Terminus (<0.2.27)
+        process.env.ConEmuTask === '{cmd::Cmder}' || // ConEmu and cmder
+        process.env.TERM_PROGRAM === 'Terminus-Sublime' ||
+        process.env.TERM_PROGRAM === 'vscode' ||
+        process.env.TERM === 'xterm-256color' ||
+        process.env.TERM === 'alacritty' ||
+        process.env.TERMINAL_EMULATOR === 'JetBrains-JediTerm');
+}

package/dist/src/utils/wizard-abort.d.ts

@@ -0,0 +1,13 @@
+export declare class WizardError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+interface WizardAbortOptions {
+    message?: string;
+    error?: Error | WizardError;
+    exitCode?: number;
+}
+export declare function registerCleanup(fn: () => void): void;
+export declare function clearCleanup(): void;
+export declare function wizardAbort(options?: WizardAbortOptions): Promise<never>;
+export {};

package/dist/src/utils/wizard-abort.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WizardError = void 0;
+exports.registerCleanup = registerCleanup;
+exports.clearCleanup = clearCleanup;
+exports.wizardAbort = wizardAbort;
+/**
+ * Single exit point for the wizard. Use instead of process.exit() directly.
+ *
+ * Sequence: cleanup -> error capture (optional) -> analytics shutdown -> outro -> process.exit
+ *
+ * WizardError is a data carrier passed to wizardAbort() for analytics context, never thrown.
+ * The legacy abort() in setup-utils.ts delegates here.
+ */
+const analytics_1 = require("./analytics");
+const ui_1 = require("../ui");
+class WizardError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'WizardError';
+    }
+}
+exports.WizardError = WizardError;
+const cleanupFns = [];
+function registerCleanup(fn) {
+    cleanupFns.push(fn);
+}
+function clearCleanup() {
+    cleanupFns.length = 0;
+}
+async function wizardAbort(options) {
+    const { message = 'Wizard setup cancelled.', error, exitCode = 1, } = options ?? {};
+    // 1. Run registered cleanup functions
+    for (const fn of cleanupFns) {
+        try {
+            fn();
+        }
+        catch {
+            /* cleanup should not prevent exit */
+        }
+    }
+    // 2. Capture error in analytics (if provided)
+    if (error) {
+        analytics_1.analytics.captureException(error, {
+            ...((error instanceof WizardError && error.context) || {}),
+        });
+    }
+    // 3. Shutdown analytics
+    await analytics_1.analytics.shutdown(error ? 'error' : 'cancelled');
+    // 4. Display message to user
+    (0, ui_1.getUI)().cancel(message);
+    // 5. Exit (fires 'exit' event so TUI cleanup runs)
+    return process.exit(exitCode);
+}

package/man/amplitude-wizard.1

@@ -0,0 +1,170 @@
+.TH AMPLITUDE\-WIZARD 1 "2026" "@amplitude/wizard" "Amplitude Wizard"
+.SH NAME
+amplitude\-wizard \- instrument your app with Amplitude analytics
+.SH SYNOPSIS
+.B amplitude\-wizard
+[\fIOPTIONS\fR]
+.br
+.B amplitude\-wizard
+\fICOMMAND\fR [\fIOPTIONS\fR]
+.SH DESCRIPTION
+\fBamplitude\-wizard\fR 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.
+.PP
+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.
+.SH COMMANDS
+.TP
+\fB(default)\fR
+Run the interactive Amplitude setup wizard. Launches a full\-screen TUI.
+.TP
+\fBlogin\fR
+Log in to your Amplitude account via browser OAuth. Credentials are stored in
+\fI~/.ampli.json\fR for subsequent runs.
+.TP
+\fBlogout\fR
+Remove the locally stored Amplitude credentials.
+.TP
+\fBwhoami\fR
+Print the currently logged\-in user and org.
+.TP
+\fBslack\fR
+Set up the Amplitude Slack integration.
+.TP
+\fBmcp add\fR
+Install the Amplitude MCP server into supported AI clients (Claude, Cursor, etc.).
+.TP
+\fBmcp remove\fR
+Remove the Amplitude MCP server from supported AI clients.
+.TP
+\fBcompletion\fR
+Print a shell completion script for bash or zsh. Source it in your shell rc:
+.RS
+.nf
+eval "$(amplitude\-wizard completion)"
+.fi
+.RE
+.SH OPTIONS
+.SS Global options
+.TP
+\fB\-\-debug\fR
+Enable verbose logging to the log file and console.
+Environment variable: \fBAMPLITUDE_WIZARD_DEBUG\fR
+.TP
+\fB\-\-verbose\fR
+Print diagnostic info (working directory, detected framework, config) to the
+run log.
+Environment variable: \fBAMPLITUDE_WIZARD_VERBOSE\fR
+.TP
+\fB\-\-signup\fR
+Create a new Amplitude account during setup instead of logging in.
+Environment variable: \fBAMPLITUDE_WIZARD_SIGNUP\fR
+.TP
+\fB\-\-ci\fR
+Enable non\-interactive CI mode. Requires \fB\-\-api\-key\fR and \fB\-\-install\-dir\fR.
+Environment variable: \fBAMPLITUDE_WIZARD_CI\fR
+.TP
+\fB\-\-api\-key\fR \fIKEY\fR
+Amplitude project API key. Skips the browser OAuth flow entirely.
+Environment variable: \fBAMPLITUDE_WIZARD_API_KEY\fR
+.TP
+\fB\-\-project\-id\fR \fIID\fR
+Amplitude project ID. Optional; defaults to the project associated with the
+API key or the saved OAuth session.
+Environment variable: \fBAMPLITUDE_WIZARD_PROJECT_ID\fR
+.TP
+\fB\-\-local\-mcp\fR
+Route MCP calls to a local server at \fIhttp://localhost:8787/mcp\fR instead of
+the production endpoint.
+Environment variable: \fBAMPLITUDE_WIZARD_LOCAL_MCP\fR
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help and exit.
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Print the package version and exit.
+.SS Wizard (default command) options
+.TP
+\fB\-\-integration\fR \fIFRAMEWORK\fR
+Skip auto\-detection and use the specified framework integration. Choices:
+\fBnextjs\fR, \fBvue\fR, \fBreact\-router\fR, \fBdjango\fR, \fBflask\fR, \fBfastapi\fR,
+\fBjavascript_web\fR, \fBjavascript_node\fR, \fBpython\fR.
+Environment variable: \fBAMPLITUDE_WIZARD_INTEGRATION\fR
+.TP
+\fB\-\-install\-dir\fR \fIDIR\fR
+Directory to install Amplitude in. Defaults to the current working directory.
+Environment variable: \fBAMPLITUDE_WIZARD_INSTALL_DIR\fR
+.TP
+\fB\-\-force\-install\fR
+Force package installation even if peer dependency checks fail.
+Environment variable: \fBAMPLITUDE_WIZARD_FORCE_INSTALL\fR
+.TP
+\fB\-\-menu\fR
+Show the framework selection menu instead of auto\-detecting.
+Environment variable: \fBAMPLITUDE_WIZARD_MENU\fR
+.TP
+\fB\-\-benchmark\fR
+Run in benchmark mode with per\-phase token tracking.
+Environment variable: \fBAMPLITUDE_WIZARD_BENCHMARK\fR
+.SS login options
+.TP
+\fB\-\-zone\fR \fIus\fR|\fIeu\fR
+Amplitude data center zone. Default: \fBus\fR.
+.SH ENVIRONMENT
+All flags can also be set as environment variables by prefixing with
+\fBAMPLITUDE_WIZARD_\fR and uppercasing. For example:
+.PP
+.nf
+export AMPLITUDE_WIZARD_API_KEY=my\-key
+export AMPLITUDE_WIZARD_CI=true
+amplitude\-wizard
+.fi
+.SH FILES
+.TP
+\fI~/.ampli.json\fR
+Stores the OAuth access token, refresh token, and user metadata (name, email,
+org, zone). Written by \fBlogin\fR and cleared by \fBlogout\fR.
+.TP
+\fI./ampli.json\fR
+Project\-level config written by the wizard after setup. Contains the Amplitude
+Source ID, Workspace ID, SDK runtime, and branch information.
+.TP
+\fI/tmp/amplitude\-wizard.log\fR
+Runtime log file. Captures verbose/debug output and agent traces.
+.SH EXAMPLES
+.TP
+Run the wizard in the current directory:
+.nf
+amplitude\-wizard
+.fi
+.TP
+Run the wizard against a specific directory:
+.nf
+amplitude\-wizard \-\-install\-dir /path/to/project
+.fi
+.TP
+Run in CI (non\-interactive):
+.nf
+amplitude\-wizard \-\-ci \-\-api\-key <key> \-\-install\-dir .
+.fi
+.TP
+Force Next.js integration without auto\-detection:
+.nf
+amplitude\-wizard \-\-integration nextjs
+.fi
+.TP
+Set up shell completions (bash/zsh):
+.nf
+echo 'eval "$(amplitude\-wizard completion)"' >> ~/.zshrc
+source ~/.zshrc
+.fi
+.TP
+Log in to the EU data center:
+.nf
+amplitude\-wizard login \-\-zone eu
+.fi
+.SH SEE ALSO
+Full documentation and source: \fIhttps://github.com/amplitude/wizard\fR