feat: add experimental headless mode for published, non-interactive runs (#732)

Adds a non-interactive run path that works in the *published* package, for
PostHog's cloud setup runs and CI/CD. Until now --ci was the only headless
path and it is stripped from published builds.

Flag & routing
- New global flag --headless-DONOTUSE-EXPERIMENTAL: hidden from --help and
  declared unconditionally so it survives in the shipped package (unlike --ci).
  Intentionally ugly-named and undocumented — the contract is still unstable.
  Its name + detection live in one place, src/lib/headless-mode.ts
  (HEADLESS_FLAG + isHeadless).
- basic-integration dispatch routes the flag to its own entry point with a
  plain `if (isHeadless(argv))` check, separate from the `if (argv.ci)` check.

CI / headless division (shared now, easy to diverge later)
- runHeadlessInstall / runWizardHeadless are siblings of runCIInstall /
  runWizardCI. Both delegate to one shared pipeline,
  runNonInteractive(config, options, mode), parameterized by an explicit
  NonInteractiveMode ('ci' | 'headless'). To diverge: branch on mode, or give
  the headless functions their own body — no CI-path or caller changes needed.

Auth
- Headless accepts a pha_ OAuth access token as first-class (PostHog mints one
  under the wizard's OAuth app for cloud runs) in addition to a phx_ personal
  key; CI still warns on pha_. keyPrefixWarning extracted as a pure predicate.
- The token is passed via POSTHOG_WIZARD_API_KEY (already wired through yargs
  .env), never on the command line.

Analytics / instrumentation
- runNonInteractive tags the analytics build type by mode ('headless' vs 'ci').
  That tag rides on every analytics event and on LLM-gateway trace tags (via
  buildRunTags reading analytics.build), so headless cloud runs segment cleanly
  from prod / dev / ci everywhere.

Other
- --ci stays dev/test-only; its published-build rejection is unchanged and
  failNonInteractive still points at --ci (headless is not advertised).
- README untouched (flag is undocumented); smoke test verifies the flag is
  accepted in published builds and reaches the headless install path.
- Tests: keyPrefixWarning unit tests, headless routing + build-tag tests,
  flag parsing tests, and a gateway-trace build-tag case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rafaeelaudibert

scripts/smoke-test.sh

@@ -7,6 +7,10 @@
 #      with the tailored "CI mode is not currently supported" error and a
 #      non-zero exit. Guards against a future change that re-enables --ci in
 #      published builds without anyone noticing.
+#   3. In production builds, the experimental headless flag IS accepted (the
+#      non-interactive published-build path) — it must not be rejected as an
+#      unknown argument. It is intentionally undocumented; this check only keeps
+#      the published binary from silently dropping the flag the cloud runs need.
 #
 # Runs from the wizard repo root via `pnpm test:smoke` (postbuild hook).
 set -e
@@ -76,3 +80,24 @@ if ! echo "$output" | grep -qi 'CI mode is not currently supported'; then
   echo "$output" >&2
   exit 1
 fi
+
+# ── 4. Experimental headless flag accepted in production builds ──────────────
+# The non-interactive path for published builds (cloud / CI runs). yargs must
+# not reject the flag, and it must not fall through to the --ci rejection. With
+# no api-key the run exits fast on "Headless mode requires --api-key" — all this
+# asserts is that the flag is recognized and live in the published binary. The
+# flag name is intentionally undocumented; keep it in sync with @lib/headless-mode.
+HEADLESS_FLAG='--headless-DONOTUSE-EXPERIMENTAL'
+hl_output=$(node "$DIST_BIN" "$HEADLESS_FLAG" --install-dir /tmp/wizard-smoke-probe 2>&1) || true
+if echo "$hl_output" | grep -qiE 'unknown argument|not currently supported'; then
+  echo 'Smoke test failed: headless flag not accepted in production build' >&2
+  echo "Output was:" >&2
+  echo "$hl_output" | head -5 >&2
+  exit 1
+fi
+if ! echo "$hl_output" | grep -qi 'Headless mode requires --api-key'; then
+  echo 'Smoke test failed: headless flag did not reach the headless install path' >&2
+  echo "Output was:" >&2
+  echo "$hl_output" | head -5 >&2
+  exit 1
+fi

src/__tests__/basic-integration-cli.test.ts

@@ -1,4 +1,5 @@
 import { basicIntegrationCommand } from '../commands/basic-integration';
+import { HEADLESS_FLAG } from '../lib/headless-mode';
 import { parseCommand } from './helpers/parse-command.no-jest';
 
 describe('basic-integration parsing (end-to-end yargs)', () => {
@@ -11,20 +12,34 @@ describe('basic-integration parsing (end-to-end yargs)', () => {
     expect(argv.installDir).toBe('/tmp/app');
   });
 
-  test('rejects --playground with --ci', async () => {
-    await expect(
-      parseCommand(basicIntegrationCommand, '--ci --playground'),
-    ).rejects.toThrow(/--playground cannot be combined/i);
+  test('parses the experimental headless flag under its declared key', async () => {
+    const argv = await parseCommand(
+      basicIntegrationCommand,
+      `--${HEADLESS_FLAG} --api-key pha_x --install-dir /tmp/app`,
+    );
+    // yargs always sets the value under the declared (kebab) key.
+    expect(argv[HEADLESS_FLAG]).toBe(true);
   });
 
-  // Default boolean values (ci/playground default false) must not register as
-  // a spurious conflict when only one mode flag is actually passed.
-  test.each(['', '--ci --api-key phx_x --install-dir /tmp', '--playground'])(
-    'accepts a single mode: "%s"',
+  test.each(['--ci --playground', `--${HEADLESS_FLAG} --playground`])(
+    'rejects --playground with a non-interactive flag: "%s"',
     async (args) => {
-      await expect(
-        parseCommand(basicIntegrationCommand, args),
-      ).resolves.toBeDefined();
+      await expect(parseCommand(basicIntegrationCommand, args)).rejects.toThrow(
+        /--playground cannot be combined/i,
+      );
     },
   );
+
+  // Default boolean values (ci/headless/playground default false) must not
+  // register as a spurious conflict when only one mode flag is actually passed.
+  test.each([
+    '',
+    '--ci --api-key phx_x --install-dir /tmp',
+    `--${HEADLESS_FLAG} --api-key pha_x --install-dir /tmp`,
+    '--playground',
+  ])('accepts a single mode: "%s"', async (args) => {
+    await expect(
+      parseCommand(basicIntegrationCommand, args),
+    ).resolves.toBeDefined();
+  });
 });

src/__tests__/cli.test.ts

@@ -272,6 +272,93 @@ describe('CLI argument parsing', () => {
       const args = getLastBuildSessionArgs();
       expect(args.apiKey).toBe('phx_test_key');
     });
+
+    test("tags the build as 'ci'", async () => {
+      await runCLI([
+        '--ci',
+        '--api-key',
+        'phx_test',
+        '--install-dir',
+        '/tmp/test',
+      ]);
+
+      const { analytics } = await import('../utils/analytics');
+      expect(analytics.setTag).toHaveBeenCalledWith('build', 'ci');
+    });
+  });
+
+  // The experimental headless flag is the published-build sibling of --ci: it
+  // routes through the same non-interactive runner (session.ci === true), but
+  // is its own flag and tags the build distinctly so the two modes segment in
+  // analytics. Its CLI name is intentionally ugly/undocumented — sourced from
+  // @lib/headless-mode so this test never has to spell it out.
+  describe('headless flag', () => {
+    // Source of truth: HEADLESS_FLAG in src/lib/headless-mode.ts. Hardcoded
+    // here (not imported) to keep this file free of top-level imports — see the
+    // note at the top of the file.
+    const headlessFlag = '--headless-DONOTUSE-EXPERIMENTAL';
+
+    test('routes through the CI runner (builds a ci session)', async () => {
+      await runCLI([
+        headlessFlag,
+        '--api-key',
+        'pha_test',
+        '--install-dir',
+        '/tmp/test',
+      ]);
+
+      const args = getLastBuildSessionArgs();
+      expect(args.ci).toBe(true);
+    });
+
+    test("tags the build as 'headless' (not 'ci')", async () => {
+      await runCLI([
+        headlessFlag,
+        '--api-key',
+        'pha_test',
+        '--install-dir',
+        '/tmp/test',
+      ]);
+
+      const { analytics } = await import('../utils/analytics');
+      expect(analytics.setTag).toHaveBeenCalledWith('build', 'headless');
+      expect(analytics.setTag).not.toHaveBeenCalledWith('build', 'ci');
+    });
+
+    // The dispatch checks the headless flag before --ci, so headless wins when
+    // both are passed. Not a supported combination, but pin the precedence.
+    test('takes precedence over --ci when both are passed', async () => {
+      await runCLI([
+        '--ci',
+        headlessFlag,
+        '--api-key',
+        'pha_test',
+        '--install-dir',
+        '/tmp/test',
+      ]);
+
+      const { analytics } = await import('../utils/analytics');
+      expect(analytics.setTag).toHaveBeenCalledWith('build', 'headless');
+      expect(analytics.setTag).not.toHaveBeenCalledWith('build', 'ci');
+    });
+
+    test('does not require --region when headless is set', async () => {
+      await runCLI([
+        headlessFlag,
+        '--api-key',
+        'pha_test',
+        '--install-dir',
+        '/tmp/test',
+      ]);
+
+      expect(process.exit).not.toHaveBeenCalledWith(1);
+    });
+
+    test('requires --api-key when headless is set', async () => {
+      await runCLI([headlessFlag, '--install-dir', '/tmp/test']);
+
+      expect(process.exit).toHaveBeenCalledWith(1);
+    });
   });
 
   describe('CI environment variables', () => {

src/commands/basic-integration/__tests__/ci-install.test.ts

@@ -0,0 +1,31 @@
+import { keyPrefixWarning } from '../ci-install';
+
+/**
+ * `keyPrefixWarning` is the one behavioral fork between `--ci` and headless
+ * mode: headless accepts a `pha_` OAuth access token as first-class, CI does
+ * not. Everything else about the two modes is shared.
+ */
+describe('keyPrefixWarning', () => {
+  describe.each([false, true])('headless=%s', (headless) => {
+    test('a personal API key (phx_) is always accepted', () => {
+      expect(keyPrefixWarning('phx_abc', headless)).toBeNull();
+    });
+
+    test('no key returns no warning', () => {
+      expect(keyPrefixWarning(undefined, headless)).toBeNull();
+    });
+
+    test('a project/client key (phc_) always warns', () => {
+      expect(keyPrefixWarning('phc_abc', headless)).toMatch(/phc_/);
+    });
+  });
+
+  test('headless accepts a pha_ OAuth access token without warning', () => {
+    expect(keyPrefixWarning('pha_abc', true)).toBeNull();
+  });
+
+  test('CI mode warns on a pha_ OAuth access token', () => {
+    const warning = keyPrefixWarning('pha_abc', false);
+    expect(warning).toMatch(/OAuth access token/);
+  });
+});

src/commands/basic-integration/ci-install.ts

@@ -1,7 +1,8 @@
 import type { Arguments } from 'yargs';
 import { getUI, setUI } from '@ui';
 import { LoggingUI } from '@ui/logging-ui';
-import { runWizardCI } from '@lib/runners';
+import { runWizardCI, runWizardHeadless } from '@lib/runners';
+import type { NonInteractiveMode } from '@lib/runners';
 import { provisionNewAccount } from '@utils/provisioning';
 import { posthogIntegrationConfig } from '@lib/programs/posthog-integration/index';
 
@@ -15,36 +16,70 @@ type Options = Arguments & {
   projectId?: string;
 };
 
-/** CI-mode entry point: validate signup flags, optionally provision an account, then install. */
+/**
+ * CI-mode install entry point (`--ci`, dev/test builds). Thin shell over the
+ * shared non-interactive install — see `runNonInteractiveInstall`.
+ */
 export function runCIInstall(argv: Arguments): void {
+  runNonInteractiveInstall(argv, 'ci');
+}
+
+/**
+ * Headless install entry point (the experimental published-build run path; see
+ * @lib/headless-mode). Thin shell over the shared non-interactive install.
+ * Today it behaves exactly like `runCIInstall`; it is a separate function so
+ * headless can diverge later (auth, prompts, …) without touching the CI path.
+ */
+export function runHeadlessInstall(argv: Arguments): void {
+  runNonInteractiveInstall(argv, 'headless');
+}
+
+/**
+ * Non-interactive install shared by CI and headless. Validates signup flags,
+ * optionally provisions an account, then installs. `mode` only changes
+ * user-facing labels, which api-key prefixes are accepted, and which runner is
+ * invoked — the install itself is identical (see runNonInteractive).
+ */
+function runNonInteractiveInstall(
+  argv: Arguments,
+  mode: NonInteractiveMode,
+): void {
   const options = { ...argv } as Options;
+  const headless = mode === 'headless';
+  const label = headless ? 'Headless' : 'CI';
+  const runWizard = headless ? runWizardHeadless : runWizardCI;
 
-  // Base CI validation (region/install-dir/api-key) is owned by runWizardCI.
-  // runCIInstall only layers the signup branch on top.
+  // Base validation (region/install-dir/api-key) is owned by the runner.
+  // This layer only adds the signup branch on top.
   if (!options.apiKey && !options.signup) {
+    const keyHint = headless
+      ? 'personal API key phx_xxx or pha_ OAuth access token'
+      : 'personal API key phx_xxx';
     return failCI(
-      'CI mode requires --api-key (personal API key phx_xxx). ' +
+      `${label} mode requires --api-key (${keyHint}). ` +
         'To create a new account instead, use --signup --email you@example.com.',
     );
   }
   if (!options.apiKey && options.signup && !options.email) {
-    return failCI('CI --signup requires --email to create a new account.');
+    return failCI(
+      `${label} --signup requires --email to create a new account.`,
+    );
   }
-  warnOnUnexpectedKeyPrefix(options.apiKey);
+  warnOnUnexpectedKeyPrefix(options.apiKey, headless);
 
   void (async () => {
     if (!options.apiKey && options.signup) {
       // Fail before the irreversible provisioning step rather than after it.
       if (!options.installDir) {
         return failCI(
-          'CI mode requires --install-dir (directory to install in)',
+          `${label} mode requires --install-dir (directory to install in)`,
         );
       }
       const provisioned = await provisionForSignup(options);
       options.apiKey = provisioned.personalApiKey;
       if (options.projectId == null) options.projectId = provisioned.projectId;
     }
-    runWizardCI(posthogIntegrationConfig, options);
+    runWizard(posthogIntegrationConfig, options);
   })().catch(() => {
     process.exit(1);
   });
@@ -57,21 +92,43 @@ function failCI(message: string): void {
   process.exit(1);
 }
 
-/** `phx_` is the personal-API-key prefix the LLM Gateway expects. */
-function warnOnUnexpectedKeyPrefix(apiKey: string | undefined): void {
-  if (!apiKey || apiKey.startsWith('phx_')) return;
-  setUI(new LoggingUI());
-  getUI().intro('PostHog Wizard');
+/**
+ * Decide whether to warn about an unexpected `--api-key` prefix, and with what
+ * message. Returns `null` when the key is acceptable for the mode.
+ *
+ * This is the one behavioral fork between `--ci` and headless mode: the LLM
+ * Gateway accepts a personal API key (`phx_`) in either mode, but in headless
+ * a `pha_` OAuth access token is *also* first-class — PostHog mints one under
+ * the wizard's own OAuth application for cloud runs and passes it as the
+ * api-key. Outside headless that token is unexpected and still warns.
+ *
+ * Extracted as a pure predicate so the fork can be unit-tested without a UI.
+ */
+export function keyPrefixWarning(
+  apiKey: string | undefined,
+  headless: boolean,
+): string | null {
+  if (!apiKey || apiKey.startsWith('phx_')) return null;
+  if (headless && apiKey.startsWith('pha_')) return null;
   const prefix = apiKey.slice(0, 4);
   const hint =
     prefix === 'pha_'
       ? ' (pha_ is an OAuth access token — CI mode expects a personal API key)'
       : prefix === 'phc_'
-      ? ' (phc_ is a project/client key — CI mode expects a personal API key)'
+      ? ' (phc_ is a project/client key — expected a personal API key)'
       : '';
-  getUI().log.warn(
-    `--api-key does not start with "phx_"${hint}. Continuing anyway, but the LLM Gateway may reject it with a 401.`,
-  );
+  return `--api-key does not start with "phx_"${hint}. Continuing anyway, but the LLM Gateway may reject it with a 401.`;
+}
+
+function warnOnUnexpectedKeyPrefix(
+  apiKey: string | undefined,
+  headless: boolean,
+): void {
+  const message = keyPrefixWarning(apiKey, headless);
+  if (!message) return;
+  setUI(new LoggingUI());
+  getUI().intro('PostHog Wizard');
+  getUI().log.warn(message);
 }
 
 /**

src/commands/basic-integration/index.ts

@@ -1,5 +1,6 @@
 import { isNonInteractiveEnvironment } from '@utils/environment';
 import { setEntryCommand } from '@utils/links';
+import { isHeadless } from '@lib/headless-mode';
 import { provisionCommand } from '../provision';
 import type { Command } from '../command';
 
@@ -30,9 +31,10 @@ export const basicIntegrationCommand: Command = {
     },
   },
   check: (argv) => {
-    // --playground is the standalone TUI demo; it can't combine with --ci.
-    if (argv.playground && argv.ci) {
-      throw new Error('--playground cannot be combined with --ci.');
+    // --playground is the standalone TUI demo; it can't combine with a
+    // non-interactive run (either --ci or the experimental headless flag).
+    if (argv.playground && (argv.ci || isHeadless(argv))) {
+      throw new Error('--playground cannot be combined with a headless run.');
     }
     return true;
   },
@@ -42,6 +44,18 @@ export const basicIntegrationCommand: Command = {
     // Each mode file is loaded only when its branch is taken, so a plain
     // `npx @posthog/wizard` never pulls in the CI or playground paths.
     void (async () => {
+      // ── The CI / headless division ───────────────────────────────────
+      // --ci (dev/test only) and the experimental headless flag (the
+      // published-build, non-interactive path; see @lib/headless-mode) both
+      // request a non-interactive install, but route to dedicated entry points
+      // — runHeadlessInstall vs runCIInstall (and below them runWizardHeadless
+      // vs runWizardCI). Both share one pipeline today but are separate
+      // functions end-to-end, so headless can diverge later without touching
+      // the CI path or its callers.
+      if (isHeadless(argv)) {
+        const { runHeadlessInstall } = await import('./ci-install');
+        return runHeadlessInstall(argv);
+      }
       if (argv.ci) {
         const { runCIInstall } = await import('./ci-install');
         return runCIInstall(argv);