@amplitude/wizard 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/src/ui/tui/store.js

@@ -13,7 +13,8 @@ import { atom, map } from 'nanostores';
 import { TaskStatus } from '../wizard-ui.js';
 import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase, buildSession, } from '../../lib/wizard-session.js';
 import { WizardRouter, Screen, Overlay, Flow, } from './router.js';
-import { analytics, sessionProperties } from '../../utils/analytics.js';
+import { analytics, sessionPropertiesCompact } from '../../utils/analytics.js';
+import { FLAG_LLM_ANALYTICS } from '../../lib/feature-flags.js';
 export { TaskStatus, Screen, Overlay, Flow, RunPhase, McpOutcome, SlackOutcome, };
 export class WizardStore {
     // ── Internal nanostore atoms ─────────────────────────────────────
@@ -51,6 +52,8 @@ export class WizardStore {
     _backupAndFixSettings = null;
     /** Pending confirmation or choice prompt from the agent. */
     $pendingPrompt = atom(null);
+    /** Resolves when the user picks continue vs run wizard after Amplitude pre-detection. */
+    _preDetectedChoiceResolver = null;
     constructor(flow = Flow.Wizard) {
         this.router = new WizardRouter(flow);
     }
@@ -103,7 +106,7 @@ export class WizardStore {
      */
     completeSetup() {
         this.$session.setKey('setupConfirmed', true);
-        analytics.wizardCapture('setup confirmed', sessionProperties(this.session));
+        analytics.wizardCapture('Setup Confirmed', sessionPropertiesCompact(this.session));
         this._resolveSetup();
         this.emitChange();
     }
@@ -116,15 +119,20 @@ export class WizardStore {
         if (credentials?.projectId) {
             analytics.setDistinctId(String(credentials.projectId));
         }
-        analytics.wizardCapture('auth complete', {
-            project_id: credentials?.projectId,
-        });
-        analytics.wizardCapture('credentials updated', {
+        analytics.wizardCapture('Auth Complete', {
             project_id: credentials?.projectId,
             region: this.session.region,
         });
         this.emitChange();
     }
+    setApiKeyNotice(notice) {
+        this.$session.setKey('apiKeyNotice', notice);
+        this.emitChange();
+    }
+    setSelectedProjectName(name) {
+        this.$session.setKey('selectedProjectName', name);
+        this.emitChange();
+    }
     setFrameworkConfig(integration, config) {
         this.$session.setKey('integration', integration);
         this.$session.setKey('frameworkConfig', config);
@@ -194,7 +202,7 @@ export class WizardStore {
         const prompt = this.$pendingPrompt.get();
         if (!prompt || prompt.kind === 'event-plan')
             return;
-        analytics.wizardCapture('prompt response', {
+        analytics.wizardCapture('Prompt Response', {
             prompt_kind: prompt.kind,
             response: String(answer),
         });
@@ -219,7 +227,7 @@ export class WizardStore {
         const prompt = this.$pendingPrompt.get();
         if (!prompt || prompt.kind !== 'event-plan')
             return;
-        analytics.wizardCapture('prompt response', {
+        analytics.wizardCapture('Prompt Response', {
             prompt_kind: 'event-plan',
             response: typeof decision === 'object' ? 'feedback' : String(decision),
         });
@@ -303,7 +311,7 @@ export class WizardStore {
     }
     setDataIngestionConfirmed() {
         this.$session.setKey('dataIngestionConfirmed', true);
-        analytics.wizardCapture('data ingestion confirmed', sessionProperties(this.session));
+        analytics.wizardCapture('Data Ingestion Confirmed', sessionPropertiesCompact(this.session));
         this.emitChange();
     }
     setChecklistChartComplete() {
@@ -316,10 +324,10 @@ export class WizardStore {
     }
     setChecklistComplete() {
         this.$session.setKey('checklistComplete', true);
-        analytics.wizardCapture('checklist completed', {
+        analytics.wizardCapture('Checklist Completed', {
             chart_complete: this.session.checklistChartComplete,
             dashboard_complete: this.session.checklistDashboardComplete,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
@@ -402,8 +410,16 @@ export class WizardStore {
     /**
      * Enable an additional feature: enqueue it for the stop hook
      * and set any feature-specific session flags.
+     * Respects Amplitude Experiment feature flags — if the corresponding
+     * flag is off the feature is silently skipped.
      */
     enableFeature(feature) {
+        // Gate LLM analytics behind the wizard-llm-analytics feature flag
+        if (feature === AdditionalFeature.LLM) {
+            if (!analytics.isFeatureFlagEnabled(FLAG_LLM_ANALYTICS)) {
+                return;
+            }
+        }
         if (!this.session.additionalFeatureQueue.includes(feature)) {
             this.session.additionalFeatureQueue.push(feature);
         }
@@ -411,30 +427,62 @@ export class WizardStore {
         if (feature === AdditionalFeature.LLM) {
             this.session.llmOptIn = true;
         }
-        analytics.wizardCapture('feature enabled', { feature });
+        analytics.wizardCapture('Feature Enabled', { feature });
         this.emitChange();
     }
     setAmplitudePreDetected() {
         this.$session.setKey('amplitudePreDetected', true);
+        this.$session.setKey('amplitudePreDetectedChoicePending', true);
+        this.emitChange();
+    }
+    /**
+     * Blocks bin.ts until McpScreen resolves via resolvePreDetectedChoice().
+     */
+    waitForPreDetectedChoice() {
+        return new Promise((resolve) => {
+            this._preDetectedChoiceResolver = resolve;
+        });
+    }
+    /**
+     * Called from McpScreen when the user chooses to skip the agent (continue to
+     * MCP) or run the full setup wizard anyway.
+     */
+    resolvePreDetectedChoice(runWizardAnyway) {
+        const resolveFn = this._preDetectedChoiceResolver;
+        this._preDetectedChoiceResolver = null;
+        if (!runWizardAnyway) {
+            this.$session.setKey('amplitudePreDetectedChoicePending', false);
+        }
+        this.emitChange();
+        resolveFn?.(runWizardAnyway);
+    }
+    /**
+     * Undo the pre-detection fast-path so runWizard can run; used when the user
+     * opts into the setup agent after Amplitude was already found in the project.
+     */
+    resetForAgentAfterPreDetected() {
+        this.$session.setKey('amplitudePreDetected', false);
+        this.$session.setKey('amplitudePreDetectedChoicePending', false);
+        this.$session.setKey('runPhase', RunPhase.Idle);
         this.emitChange();
     }
     setMcpComplete(outcome = McpOutcome.Skipped, installedClients = []) {
         this.$session.setKey('mcpComplete', true);
         this.$session.setKey('mcpOutcome', outcome);
         this.$session.setKey('mcpInstalledClients', installedClients);
-        analytics.wizardCapture('mcp complete', {
+        analytics.wizardCapture('MCP Complete', {
             mcp_outcome: outcome,
             mcp_installed_clients: installedClients,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
     setSlackComplete(outcome = SlackOutcome.Skipped) {
         this.$session.setKey('slackComplete', true);
         this.$session.setKey('slackOutcome', outcome);
-        analytics.wizardCapture('slack complete', {
+        analytics.wizardCapture('Slack Complete', {
             slack_outcome: outcome,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
@@ -512,9 +560,10 @@ export class WizardStore {
                 for (const fn of hooks)
                     fn();
             }
-            analytics.wizardCapture(`screen ${next}`, {
-                from_screen: prev,
-                ...sessionProperties(this.session),
+            analytics.wizardCapture('Wizard Screen Entered', {
+                screen_name: next,
+                previous_screen: prev,
+                ...sessionPropertiesCompact(this.session),
             });
         }
     }

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

@@ -1,17 +1,29 @@
 import type { WizardSession } from '../lib/wizard-session';
+/**
+ * Telemetry project API key. Empty or whitespace-only env value means “no key”
+ * (use default only when the variable is unset).
+ */
+export declare function resolveTelemetryApiKey(): string;
+/** HTTP API URL for `@amplitude/analytics-node` (same shape as manual HTTP ingest). */
+export declare function getAmplitudeNodeServerUrl(): string;
 /**
  * Extract a standard property bag from the current session.
  * Used by store-level analytics and available for ad-hoc captures.
  */
 export declare function sessionProperties(session: WizardSession): Record<string, unknown>;
+/**
+ * Smaller session bag for high-volume wizard events (taxonomy: keep event
+ * properties chart-useful and within a small count).
+ */
+export declare function sessionPropertiesCompact(session: WizardSession): Record<string, unknown>;
 export declare class Analytics {
     private tags;
     private distinctId?;
     private anonymousId;
     private appName;
     private activeFlags;
-    private pendingEvents;
-    private flushTimer;
+    private readonly client;
+    private initPromise;
     constructor();
     setDistinctId(distinctId: string): void;
     setTag(key: string, value: string | boolean | number | null | undefined): void;
@@ -20,10 +32,30 @@ export declare class Analytics {
     /**
      * Capture a wizard-specific event. Automatically prepends "wizard: " to the event name.
      * All new wizard analytics should use this method instead of capture() directly.
+     * Use lowercase with spaces for eventName (e.g. "agent started", "api key submitted")
+     * per Amplitude quickstart taxonomy guidelines.
      */
     wizardCapture(eventName: string, properties?: Record<string, unknown>): void;
-    private flush;
+    /**
+     * Apply feature-flag–based opt-out to the Amplitude SDK.
+     * Defaults to ON — only opts out when `wizard-agent-analytics` is explicitly 'off'/'false'.
+     */
+    applyOptOut(): void;
+    private ensureInitStarted;
+    /**
+     * Initialize the Amplitude Experiment feature-flag client.
+     * Call once early in startup (e.g. after obtaining a user/device ID).
+     */
+    initFlags(): Promise<void>;
+    /**
+     * Re-evaluate flags after the user identity changes (e.g. post-login).
+     */
+    refreshFlags(): Promise<void>;
     getFeatureFlag(flagKey: string): Promise<string | boolean | undefined>;
+    /**
+     * Check if a flag is enabled (variant is 'on' or 'true').
+     */
+    isFeatureFlagEnabled(flagKey: string): boolean;
     /**
      * Evaluate all feature flags for the current user at the start of a run.
      * Result is cached; subsequent calls in the same run return the same map.
@@ -32,4 +64,14 @@ export declare class Analytics {
     getAllFlagsForWizard(): Promise<Record<string, string>>;
     shutdown(status: 'success' | 'error' | 'cancelled'): Promise<void>;
 }
+/**
+ * Full Amplitude `event_type` for CLI/TUI product feedback.
+ * Same string as `wizardCapture('Feedback Submitted', …)`.
+ */
+export declare const WIZARD_FEEDBACK_EVENT_TYPE = "wizard: feedback submitted";
 export declare const analytics: Analytics;
+/**
+ * Unified wizard error telemetry (aligns with starter taxonomy “Error Encountered”).
+ * Emits `wizard: error encountered` with category / message / context.
+ */
+export declare function captureWizardError(errorCategory: string, errorMessage: string, errorContext: string, extra?: Record<string, unknown>): void;

package/dist/src/utils/analytics.js

@@ -1,11 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analytics = exports.Analytics = void 0;
+exports.analytics = exports.WIZARD_FEEDBACK_EVENT_TYPE = exports.Analytics = void 0;
+exports.resolveTelemetryApiKey = resolveTelemetryApiKey;
+exports.getAmplitudeNodeServerUrl = getAmplitudeNodeServerUrl;
 exports.sessionProperties = sessionProperties;
+exports.sessionPropertiesCompact = sessionPropertiesCompact;
+exports.captureWizardError = captureWizardError;
+const analytics_node_1 = require("@amplitude/analytics-node");
 const uuid_1 = require("uuid");
 const debug_1 = require("./debug");
-const AMPLITUDE_API_KEY = process.env.AMPLITUDE_API_KEY ?? 'e5a2c9bdffe949f7da77e6b481e118fa';
-const AMPLITUDE_SERVER_URL = process.env.AMPLITUDE_SERVER_URL ?? 'https://api2.amplitude.com';
+const feature_flags_1 = require("../lib/feature-flags");
+const DEFAULT_TELEMETRY_API_KEY = 'e5a2c9bdffe949f7da77e6b481e118fa';
+/**
+ * Telemetry project API key. Empty or whitespace-only env value means “no key”
+ * (use default only when the variable is unset).
+ */
+function resolveTelemetryApiKey() {
+    const fromEnv = process.env.AMPLITUDE_API_KEY;
+    const raw = fromEnv !== undefined ? fromEnv : DEFAULT_TELEMETRY_API_KEY;
+    return raw.trim();
+}
+/** HTTP API URL for `@amplitude/analytics-node` (same shape as manual HTTP ingest). */
+function getAmplitudeNodeServerUrl() {
+    const base = process.env.AMPLITUDE_SERVER_URL ?? 'https://api2.amplitude.com';
+    return `${base.replace(/\/$/, '')}/2/httpapi`;
+}
 /**
  * Extract a standard property bag from the current session.
  * Used by store-level analytics and available for ad-hoc captures.
@@ -21,18 +40,31 @@ function sessionProperties(session) {
         run_phase: session.runPhase,
     };
 }
+/**
+ * Smaller session bag for high-volume wizard events (taxonomy: keep event
+ * properties chart-useful and within a small count).
+ */
+function sessionPropertiesCompact(session) {
+    return {
+        integration: session.integration,
+        detected_framework: session.detectedFrameworkLabel,
+        run_phase: session.runPhase,
+        project_id: session.credentials?.projectId,
+    };
+}
 class Analytics {
     tags = {};
     distinctId;
     anonymousId;
     appName = 'wizard';
     activeFlags = null;
-    pendingEvents = [];
-    flushTimer = null;
+    client;
+    initPromise = null;
     constructor() {
         this.tags = { $app_name: this.appName };
         this.anonymousId = (0, uuid_1.v4)();
         this.distinctId = undefined;
+        this.client = (0, analytics_node_1.createInstance)();
     }
     setDistinctId(distinctId) {
         this.distinctId = distinctId;
@@ -48,64 +80,81 @@ class Analytics {
         });
     }
     capture(eventName, properties) {
-        if (!AMPLITUDE_API_KEY) {
+        const apiKey = resolveTelemetryApiKey();
+        if (!apiKey) {
             (0, debug_1.debug)('capture (no API key):', eventName, properties);
             return;
         }
-        const event = {
-            event_type: eventName,
+        this.ensureInitStarted();
+        const eventProps = {
+            ...this.tags,
+            ...properties,
+        };
+        const options = {
             device_id: this.anonymousId,
-            time: Date.now(),
-            event_properties: {
-                ...this.tags,
-                ...properties,
-            },
         };
         if (this.distinctId) {
-            event.user_id = this.distinctId;
+            options.user_id = this.distinctId;
         }
-        this.pendingEvents.push(event);
+        this.client.track(eventName, eventProps, options);
         (0, debug_1.debug)('capture:', eventName, properties);
-        // Debounce flush to batch events
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-        }
-        this.flushTimer = setTimeout(() => {
-            void this.flush();
-        }, 500);
     }
     /**
      * Capture a wizard-specific event. Automatically prepends "wizard: " to the event name.
      * All new wizard analytics should use this method instead of capture() directly.
+     * Use lowercase with spaces for eventName (e.g. "agent started", "api key submitted")
+     * per Amplitude quickstart taxonomy guidelines.
      */
     wizardCapture(eventName, properties) {
         this.capture(`wizard: ${eventName}`, properties);
     }
-    async flush() {
-        if (this.pendingEvents.length === 0)
-            return;
-        if (!AMPLITUDE_API_KEY)
+    /**
+     * Apply feature-flag–based opt-out to the Amplitude SDK.
+     * Defaults to ON — only opts out when `wizard-agent-analytics` is explicitly 'off'/'false'.
+     */
+    applyOptOut() {
+        const flagValue = (0, feature_flags_1.getFlag)(feature_flags_1.FLAG_AGENT_ANALYTICS);
+        const optOut = flagValue === 'off' || flagValue === 'false';
+        this.client.setOptOut(optOut);
+        if (optOut) {
+            (0, debug_1.debug)('analytics: opted out via wizard-agent-analytics flag');
+        }
+    }
+    ensureInitStarted() {
+        if (this.initPromise !== null) {
             return;
-        const events = [...this.pendingEvents];
-        this.pendingEvents = [];
-        try {
-            const response = await fetch(`${AMPLITUDE_SERVER_URL}/2/httpapi`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ api_key: AMPLITUDE_API_KEY, events }),
-            });
-            if (!response.ok) {
-                (0, debug_1.debug)('Amplitude upload failed:', response.status, await response.text());
-            }
         }
-        catch (err) {
-            (0, debug_1.debug)('Amplitude upload error:', err);
+        const apiKey = resolveTelemetryApiKey();
+        if (!apiKey) {
+            return;
         }
+        this.initPromise = this.client.init(apiKey, {
+            serverUrl: getAmplitudeNodeServerUrl(),
+        }).promise;
+    }
+    /**
+     * Initialize the Amplitude Experiment feature-flag client.
+     * Call once early in startup (e.g. after obtaining a user/device ID).
+     */
+    async initFlags() {
+        await (0, feature_flags_1.initFeatureFlags)(this.distinctId, this.anonymousId);
+    }
+    /**
+     * Re-evaluate flags after the user identity changes (e.g. post-login).
+     */
+    async refreshFlags() {
+        await (0, feature_flags_1.refreshFlags)(this.distinctId, this.anonymousId);
+        this.activeFlags = (0, feature_flags_1.getAllFlags)();
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async getFeatureFlag(flagKey) {
-        (0, debug_1.debug)('getFeatureFlag (noop):', flagKey);
-        return undefined;
+        return (0, feature_flags_1.getFlag)(flagKey);
+    }
+    /**
+     * Check if a flag is enabled (variant is 'on' or 'true').
+     */
+    isFeatureFlagEnabled(flagKey) {
+        return (0, feature_flags_1.isFlagEnabled)(flagKey);
     }
     /**
      * Evaluate all feature flags for the current user at the start of a run.
@@ -117,17 +166,39 @@ class Analytics {
         if (this.activeFlags !== null) {
             return this.activeFlags;
         }
-        this.activeFlags = {};
+        this.activeFlags = (0, feature_flags_1.getAllFlags)();
         return this.activeFlags;
     }
     async shutdown(status) {
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = null;
+        this.wizardCapture('Session Ended', { status });
+        if (this.initPromise === null) {
+            return;
+        }
+        try {
+            await this.initPromise;
+            await this.client.flush().promise;
+        }
+        catch (err) {
+            (0, debug_1.debug)('analytics shutdown flush error:', err);
         }
-        this.capture('wizard: session ended', { status });
-        await this.flush();
     }
 }
 exports.Analytics = Analytics;
+/**
+ * Full Amplitude `event_type` for CLI/TUI product feedback.
+ * Same string as `wizardCapture('Feedback Submitted', …)`.
+ */
+exports.WIZARD_FEEDBACK_EVENT_TYPE = 'wizard: feedback submitted';
 exports.analytics = new Analytics();
+/**
+ * Unified wizard error telemetry (aligns with starter taxonomy “Error Encountered”).
+ * Emits `wizard: error encountered` with category / message / context.
+ */
+function captureWizardError(errorCategory, errorMessage, errorContext, extra) {
+    exports.analytics.wizardCapture('Error Encountered', {
+        error_category: errorCategory,
+        error_message: errorMessage,
+        error_context: errorContext,
+        ...extra,
+    });
+}

package/dist/src/utils/oauth.js

@@ -315,7 +315,7 @@ async function performAmplitudeAuth(options) {
             (0, index_js_1.getUI)().log.info(`${chalk_1.default.yellow('Authorization was cancelled.')}\n\nRe-run the wizard to try again.`);
         }
         else {
-            (0, index_js_1.getUI)().log.error(`${chalk_1.default.red('Authorization failed:')}\n\n${error.message}\n\n${chalk_1.default.dim(`File an issue:\n${constants_js_1.ISSUES_URL}`)}`);
+            (0, index_js_1.getUI)().log.error(`${chalk_1.default.red('Authorization failed:')}\n\n${error.message}\n\n${chalk_1.default.dim(`File an issue:\n${constants_js_1.OUTBOUND_URLS.githubIssues}`)}`);
         }
         analytics_js_1.analytics.captureException(error, { step: 'oauth_flow' });
         await (0, setup_utils_js_1.abort)();

package/dist/src/utils/setup-utils.d.ts

@@ -60,6 +60,17 @@ export declare function getPackageManager(options: Pick<WizardOptions, 'installD
     ci?: boolean;
 }): Promise<PackageManager>;
 export declare function isUsingTypeScript({ installDir, }: Pick<WizardOptions, 'installDir'>): boolean;
+/**
+ * Best-effort credentials for `--ci` when `--api-key` / AMPLITUDE_WIZARD_API_KEY
+ * is not set: project-local key (.env.local / keychain), then OAuth id token from
+ * ~/.ampli.json plus org/workspace from ampli.json (same resolution as interactive bootstrap).
+ */
+export declare function tryResolveCredentialsForCi(installDir: string): Promise<{
+    host: string;
+    projectApiKey: string;
+    accessToken: string;
+    cloudRegion: CloudRegion;
+} | null>;
 /**
  * Get project data for the wizard via Amplitude OAuth or CI API key.
  *

package/dist/src/utils/setup-utils.js

@@ -46,6 +46,7 @@ exports.tryGetPackageJson = tryGetPackageJson;
 exports.updatePackageDotJson = updatePackageDotJson;
 exports.getPackageManager = getPackageManager;
 exports.isUsingTypeScript = isUsingTypeScript;
+exports.tryResolveCredentialsForCi = tryResolveCredentialsForCi;
 exports.getOrAskForProjectData = getOrAskForProjectData;
 exports.createNewConfigFile = createNewConfigFile;
 const childProcess = __importStar(require("node:child_process"));
@@ -63,7 +64,6 @@ const ui_1 = require("../ui");
 const oauth_1 = require("./oauth");
 const api_1 = require("../lib/api");
 const ampli_settings_1 = require("./ampli-settings");
-const constants_2 = require("../lib/constants");
 const urls_1 = require("./urls");
 const semver_1 = require("./semver");
 const wizard_abort_1 = require("./wizard-abort");
@@ -151,11 +151,11 @@ async function installPackage({ packageName, alreadyInstalled, packageNameDispla
         }
         catch (e) {
             sdkInstallSpinner.stop('Installation failed.');
-            (0, ui_1.getUI)().log.error(`${chalk_1.default.red('Encountered the following error during installation:')}\n\n${e}\n\n${chalk_1.default.dim(`The wizard has created a \`amplitude-wizard-installation-error-*.log\` file. If you think this issue is caused by the Amplitude wizard, create an issue on GitHub and include the log file's content:\n${constants_1.ISSUES_URL}`)}`);
+            (0, ui_1.getUI)().log.error(`${chalk_1.default.red('Encountered the following error during installation:')}\n\n${e}\n\n${chalk_1.default.dim(`The wizard has created a \`amplitude-wizard-installation-error-*.log\` file. If you think this issue is caused by the Amplitude wizard, create an issue on GitHub and include the log file's content:\n${constants_1.OUTBOUND_URLS.githubIssues}`)}`);
             await abort();
         }
         sdkInstallSpinner.stop(`${alreadyInstalled ? 'Updated' : 'Installed'} ${chalk_1.default.bold.cyan(packageNameDisplayLabel ?? packageName)} with ${chalk_1.default.bold(pkgManager.label)}.`);
-        analytics_1.analytics.wizardCapture('package installed', {
+        analytics_1.analytics.wizardCapture('Package Installed', {
             package_name: packageName,
             package_manager: pkgManager.name,
             integration,
@@ -237,6 +237,57 @@ function isUsingTypeScript({ installDir, }) {
         return false;
     }
 }
+/**
+ * Best-effort credentials for `--ci` when `--api-key` / AMPLITUDE_WIZARD_API_KEY
+ * is not set: project-local key (.env.local / keychain), then OAuth id token from
+ * ~/.ampli.json plus org/workspace from ampli.json (same resolution as interactive bootstrap).
+ */
+async function tryResolveCredentialsForCi(installDir) {
+    const { readApiKeyWithSource } = await import('./api-key-store.js');
+    const local = readApiKeyWithSource(installDir);
+    if (local) {
+        return {
+            host: constants_1.DEFAULT_HOST_URL,
+            projectApiKey: local.key,
+            accessToken: local.key,
+            cloudRegion: 'us',
+        };
+    }
+    const { getStoredUser, getStoredToken } = await import('./ampli-settings.js');
+    const { readAmpliConfig } = await import('../lib/ampli-config.js');
+    const { getAPIKey } = await import('./get-api-key.js');
+    const { getHostFromRegion } = await import('./urls.js');
+    const storedUser = getStoredUser();
+    const realUser = storedUser && storedUser.id !== 'pending' ? storedUser : null;
+    const projectConfig = readAmpliConfig(installDir);
+    const projectZone = projectConfig.ok ? projectConfig.config.Zone : undefined;
+    const zone = realUser?.zone ?? projectZone ?? constants_1.DEFAULT_AMPLITUDE_ZONE;
+    const storedToken = realUser
+        ? getStoredToken(realUser.id, realUser.zone)
+        : getStoredToken(undefined, zone);
+    if (!storedToken?.idToken) {
+        return null;
+    }
+    const workspaceId = projectConfig.ok
+        ? projectConfig.config.WorkspaceId
+        : undefined;
+    const projectApiKey = await getAPIKey({
+        installDir,
+        idToken: storedToken.idToken,
+        zone,
+        workspaceId,
+    });
+    if (!projectApiKey) {
+        return null;
+    }
+    const cloudRegion = zone === 'eu' ? 'eu' : 'us';
+    return {
+        host: getHostFromRegion(cloudRegion),
+        projectApiKey,
+        accessToken: storedToken.idToken,
+        cloudRegion,
+    };
+}
 /**
  * Get project data for the wizard via Amplitude OAuth or CI API key.
  *
@@ -258,6 +309,32 @@ async function getOrAskForProjectData(_options) {
             cloudRegion: 'us',
         };
     }
+    if (_options.ci) {
+        const ciInstallDir = _options.installDir;
+        if (!ciInstallDir) {
+            (0, ui_1.getUI)().log.error(chalk_1.default.red('CI mode requires --install-dir (or AMPLITUDE_WIZARD_INSTALL_DIR).'));
+            await (0, wizard_abort_1.wizardAbort)({
+                message: 'CI mode requires an install directory.',
+            });
+        }
+        else {
+            const resolved = await tryResolveCredentialsForCi(ciInstallDir);
+            if (resolved) {
+                (0, ui_1.getUI)().log.info(chalk_1.default.dim('Resolved Amplitude API key non-interactively (CI mode).'));
+                return {
+                    host: resolved.host,
+                    projectApiKey: resolved.projectApiKey,
+                    accessToken: resolved.accessToken,
+                    projectId: _options.projectId ?? 0,
+                    cloudRegion: resolved.cloudRegion,
+                };
+            }
+            (0, ui_1.getUI)().log.error(chalk_1.default.red('CI mode could not resolve a project API key. Pass --api-key or AMPLITUDE_WIZARD_API_KEY, store a key in the project (.env.local / keychain), or ensure ~/.ampli.json has a valid OAuth session (and ampli.json includes WorkspaceId if needed).'));
+            await (0, wizard_abort_1.wizardAbort)({
+                message: 'CI mode requires a project API key or resolvable Amplitude credentials.',
+            });
+        }
+    }
     // Force fresh OAuth for projects that haven't been set up yet — no local
     // ampli.json means we don't know which Amplitude org this project belongs to.
     let forceFresh = false;
@@ -280,7 +357,7 @@ async function getOrAskForProjectData(_options) {
 async function askForWizardLogin(opts = {}) {
     // ── 1. Authenticate via Amplitude OAuth (reuses ampli CLI session) ──
     const auth = await (0, oauth_1.performAmplitudeAuth)({
-        zone: constants_2.DEFAULT_AMPLITUDE_ZONE,
+        zone: constants_1.DEFAULT_AMPLITUDE_ZONE,
         forceFresh: opts.forceFresh,
     });
     // ── 2. Detect actual cloud region (EU users auth via US endpoint but