feat: headless provision subcommand + --ci --signup for agents (#415)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Edwin Lim <edwin@posthog.com>

Author: 3 people

README.md

@@ -48,6 +48,46 @@ npx @posthog/wizard revenue
 Requires PostHog and Stripe SDKs already installed. Supports `--ci` with the
 same flags as the main wizard.
 
+## Headless signup + install (agents / CI)
+
+For a fully non-interactive first-run (no existing PostHog account, no TTY,
+no browser), combine `--ci --signup --email`. The wizard provisions a new
+account, uses the returned personal API key to run the normal CI install,
+and wires PostHog into the project at `--install-dir`:
+
+```bash
+npx @posthog/wizard --ci --signup \
+  --email you@example.com \
+  --install-dir .
+```
+
+Optional flags: `--name "Your Name"`, `--region eu` (default `us`),
+`--integration nextjs` (else auto-detected).
+
+### Provision only
+
+If you just want credentials — for tests, pre-flight checks, or wiring up
+PostHog yourself — use the `provision` subcommand, which emits a structured
+`ProvisioningResult` and does nothing else:
+
+```bash
+# Human-readable (when stdout is a TTY)
+npx @posthog/wizard provision --email user@example.com --region us
+
+# Machine-readable — auto when stdout is piped, or force with --json
+npx @posthog/wizard provision --email user@example.com --region eu --json
+```
+
+Success prints the full `ProvisioningResult` (`projectApiKey`, `host`,
+`projectId`, `accountId`, `accessToken`, `refreshToken`, and
+`personalApiKey` if present). Failure exits 1; in `--json` mode the error
+is emitted to stderr as `{"error":"...","code":"..."}`, with `code` set to
+`email_exists` when the address is already registered.
+
+> ⚠️ **Output contains live credentials.** Pipe it into a secrets store —
+> do not let it be captured by shared CI logs. Mask the step output or
+> redirect stdout to a file your job reads and discards.
+
 # Options
 
 The following CLI arguments are available:

bin.ts

@@ -185,6 +185,11 @@ const cli = yargs(hideBin(process.argv))
             'Run a specific context-mill skill by ID\nenv: POSTHOG_WIZARD_SKILL',
           type: 'string',
         },
+        name: {
+          describe:
+            'Name for account creation with --ci --signup\nenv: POSTHOG_WIZARD_NAME',
+          type: 'string',
+        },
       });
     },
     (argv) => {
@@ -193,25 +198,81 @@ const cli = yargs(hideBin(process.argv))
       // CI mode validation and TTY check
       if (options.ci) {
         if (!options.region) options.region = 'us';
-        if (!options.apiKey) {
+        if (!options.installDir) {
           setUI(new LoggingUI());
           getUI().intro('PostHog Wizard');
           getUI().log.error(
-            'CI mode requires --api-key (personal API key phx_xxx)',
+            'CI mode requires --install-dir (directory to install in)',
           );
           process.exit(1);
           return;
         }
-        if (!options.installDir) {
+        if (!options.apiKey && !options.signup) {
           setUI(new LoggingUI());
           getUI().intro('PostHog Wizard');
           getUI().log.error(
-            'CI mode requires --install-dir (directory to install in)',
+            'CI mode requires --api-key (personal API key phx_xxx). ' +
+              'To create a new account instead, use --signup --email you@example.com.',
+          );
+          process.exit(1);
+          return;
+        }
+        if (!options.apiKey && options.signup && !options.email) {
+          setUI(new LoggingUI());
+          getUI().intro('PostHog Wizard');
+          getUI().log.error(
+            'CI --signup requires --email to create a new account.',
           );
           process.exit(1);
           return;
         }
         void (async () => {
+          // If --signup but no existing key, provision a new account first and
+          // use its personal API key for the rest of the CI install.
+          if (!options.apiKey && options.signup) {
+            setUI(new LoggingUI());
+            getUI().intro('PostHog Wizard');
+            try {
+              const { provisionNewAccount } = await import(
+                './src/utils/provisioning.js'
+              );
+              const signupRegion = (options.region as string).toUpperCase() as
+                | 'US'
+                | 'EU';
+              getUI().log.info(
+                `Provisioning new PostHog account for ${String(
+                  options.email,
+                )} in ${signupRegion}...`,
+              );
+              const result = await provisionNewAccount(
+                options.email as string,
+                options.name ?? '',
+                signupRegion,
+              );
+              if (!result.personalApiKey) {
+                getUI().log.error(
+                  'Provisioning succeeded but no personal API key was returned — cannot continue install.',
+                );
+                process.exit(1);
+                return;
+              }
+              getUI().log.success('Account ready.');
+              getUI().log.info(`  Project API Key:  ${result.projectApiKey}`);
+              getUI().log.info(`  Personal API Key: ${result.personalApiKey}`);
+              getUI().log.info(`  Host:             ${result.host}`);
+              options.apiKey = result.personalApiKey;
+              if (options.projectId == null) {
+                options.projectId = result.projectId;
+              }
+            } catch (error) {
+              const msg =
+                error instanceof Error ? error.message : String(error);
+              getUI().log.error(`Provisioning failed: ${msg}`);
+              process.exit(1);
+              return;
+            }
+          }
+
           const { posthogIntegrationConfig } = await import(
             './src/lib/workflows/posthog-integration/index.js'
           );
@@ -428,6 +489,90 @@ const cli = yargs(hideBin(process.argv))
       .help();
   });
 
+cli.command(
+  'provision',
+  'Create a new PostHog account (headless, no TUI)',
+  (yargs) => {
+    return yargs
+      .options({
+        email: {
+          describe: 'Email address for the new account',
+          type: 'string' as const,
+          demandOption: true,
+        },
+        region: {
+          describe: 'Cloud region (us or eu)',
+          choices: ['us', 'eu'] as const,
+          default: 'us',
+        },
+        name: {
+          describe: 'Name for the new account',
+          type: 'string' as const,
+          default: '',
+        },
+        json: {
+          describe:
+            'Emit JSON result to stdout (defaults to true when stdout is not a TTY)',
+          type: 'boolean' as const,
+        },
+      })
+      .example('wizard provision --email matt+test@posthog.com --region us', '')
+      .example(
+        'wizard provision --email user@example.com --region eu --json',
+        '',
+      );
+  },
+  (argv) => {
+    const email = argv.email;
+    const region = argv.region.toUpperCase() as 'US' | 'EU';
+    const name = argv.name ?? '';
+    const jsonMode =
+      argv.json === undefined ? !process.stdout.isTTY : argv.json;
+
+    if (!jsonMode) {
+      setUI(new LoggingUI());
+    }
+
+    void (async () => {
+      try {
+        const { provisionNewAccount } = await import(
+          './src/utils/provisioning.js'
+        );
+        if (!jsonMode) {
+          getUI().log.info(`Provisioning account for ${email} in ${region}...`);
+        }
+        const result = await provisionNewAccount(email, name, region);
+        if (jsonMode) {
+          process.stdout.write(`${JSON.stringify(result)}\n`);
+        } else {
+          getUI().log.success('Account provisioned successfully:');
+          getUI().log.info(`  API Key:       ${result.projectApiKey}`);
+          getUI().log.info(`  Host:          ${result.host}`);
+          getUI().log.info(`  Project ID:    ${result.projectId}`);
+          getUI().log.info(`  Account ID:    ${result.accountId}`);
+          getUI().log.info(`  Access Token:  ${result.accessToken}`);
+          getUI().log.info(`  Refresh Token: ${result.refreshToken}`);
+          if (result.personalApiKey) {
+            getUI().log.info(`  Personal API Key: ${result.personalApiKey}`);
+          }
+        }
+        process.exit(0);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        const code = msg.includes('already associated')
+          ? 'email_exists'
+          : 'provisioning_failed';
+        if (jsonMode) {
+          process.stderr.write(`${JSON.stringify({ error: msg, code })}\n`);
+        } else {
+          getUI().log.error(`Provisioning failed: ${msg}`);
+        }
+        process.exit(1);
+      }
+    })();
+  },
+);
+
 // ── Skill-based workflow subcommands (derived from registry) ─────────
 for (const wfConfig of getSubcommandWorkflows()) {
   cli.command(