have any feedback, please drop an email to [email protected].

The PostHog wizard helps you quickly add PostHog to your project using AI.

Usage

To use the wizard, you can run it directly using:

npx @posthog/wizard

Currently the wizard can be used for over 16+ frameworks for frontend, backend, and mobile applications. If you have other integrations you would like the wizard to support, please open a GitHub issue!

Visit our docs to learn more.

Privacy & data usage

The wizard uses Anthropic Claude (via PostHog's LLM gateway) to read your project's source files and integrate PostHog. A few things worth knowing up front:

• Source files are sent to Anthropic as part of the agent's context.
• .env* files and secrets stay on your machine. The wizard's security scanner blocks anything it identifies as a secret from being read by the agent.
• Telemetry (run metadata — phase, task list, planned events) is sent to PostHog by default. Pass --no-telemetry (or set POSTHOG_WIZARD_NO_TELEMETRY=1) to disable.
• AI opt-in: the wizard honors your PostHog organization's is_ai_data_processing_approved setting (the same toggle that gates Max). If your org has not opted in, the wizard explains how to enable it and exits without sending source to Anthropic.
• Prefer your own AI? The wizard's integration knowledge ships as a context-mill skill you can download and run inside your own agent.

The wizard's "Privacy & data usage" menu (intro screen) and the [I] shortcut on the auth screen surface the same information in-terminal.

MCP Commands

The wizard also includes commands for managing PostHog MCP (Model Context Protocol) servers:

# Install PostHog MCP server to supported clients
npx @posthog/wizard mcp add

# Remove PostHog MCP server from supported clients
npx @posthog/wizard mcp remove

Wizard programs

The wizard's commands are grouped into programs — self-contained agentic jobs that install, audit, or wire up a specific piece of PostHog. They're powered by skills from the context mill.

PostHog integration (default)

Running the wizard with no arguments installs PostHog into your project. It detects your framework, wires up initialization, instruments a starter set of events, and walks you through a first dashboard:

npx @posthog/wizard

Powered by the posthog-integration program. Most other programs below build on it (they declare requires: ['posthog-integration']) and will offer to run it first if PostHog isn't already set up.

Self-driving

Autonomously sets up PostHog self-driving end-to-end. It connects GitHub, enables Session Replay and Error Tracking, wires up signal sources, and configures a Signals scout troop that watches your project for you.

npx @posthog/wizard self-driving

If PostHog isn't already installed, the wizard runs the default integration first (composed run) before starting the self-driving setup.

Audit

Audit an existing PostHog integration for correctness and best practices. The audit command is a family. With no subcommand it runs the events audit (the default); pass a subcommand to run a specific one:

# Runs the events audit (the default) — no subcommand needed
npx @posthog/wizard audit

# Or run a specific audit directly
npx @posthog/wizard audit events           # event capture quality + cost (default)
npx @posthog/wizard audit all              # comprehensive audit across every area
npx @posthog/wizard audit autocapture      # autocapture setup + cost
npx @posthog/wizard audit feature-flags    # feature flag usage + cost
npx @posthog/wizard audit identify         # your $identify implementation
npx @posthog/wizard audit session-replay   # session replay setup
npx @posthog/wizard audit web-analytics    # web analytics setup

Most audit subcommands resolve at runtime from the published skill registry, so new audits appear without a wizard release (web-analytics is wizard-native).

audit <subcommand> chooses an audit area — it does not take a skill name. The audit subcommands above are context-mill skills promoted to commands (via a cli: role: command block); wizard skill <skill-name> runs a skill that hasn't been promoted. Same machinery, two surfaces. (wizard audit --help still labels the positional [skill] — read it as "pick a subcommand.")

Revenue Analytics

Wire up an existing PostHog + Stripe project for revenue analytics:

npx @posthog/wizard revenue-analytics

Requires PostHog and Stripe SDKs already installed. Supports --ci with the same flags as the main wizard. (Renamed from revenue in the CLI overhaul.)

Data Warehouse

Detect data sources your project already uses (Postgres, MySQL, MongoDB, Snowflake, BigQuery, Stripe, …) and connect them to PostHog's data warehouse:

npx @posthog/wizard warehouse

The wizard scans your dependencies and .env key names (never the values) to identify sources. Database and API-key sources are created from the terminal; OAuth sources open the PostHog app's new-source flow in your browser.

Upload source maps

Upload JavaScript source maps to PostHog error tracking so stack traces are symbolicated back to your original code:

npx @posthog/wizard upload-source-maps

Run skill

Run any context-mill skill directly by name, even if it isn't exposed as its own command:

npx @posthog/wizard skill list              # list every available skill
npx @posthog/wizard skill <skill-name>      # run one by name

Wizard ownership

Reviews are auto-requested via .github/CODEOWNERS — the file is the source of truth; this table just mirrors it for readability. team-wizard-docs is the default reviewer; the team-owned programs below route review to their owning team instead.

| Path | Owning team | |---|---| | * (everything else, including all other programs) | @PostHog/team-wizard-docs | | src/lib/agent/ | @PostHog/team-wizard-docs | | src/lib/programs/posthog-integration/ | @PostHog/team-wizard-docs | | src/lib/programs/error-tracking-upload-source-maps/ | @PostHog/team-error-tracking | | src/lib/programs/mcp-analytics/ | @PostHog/team-mcp-analytics | | src/lib/programs/revenue-analytics/ | @PostHog/team-web-analytics | | src/lib/programs/self-driving/ | @PostHog/team-self-driving | | src/lib/programs/warehouse-source/ | @PostHog/team-warehouse-sources | | src/lib/programs/web-analytics-doctor/ | @PostHog/team-web-analytics |

Ownership is by directory. Programs not listed above (agent-skill, audit, events-audit, mcp, migration, posthog-doctor, shared, slack) fall through the default and are owned by team-wizard-docs. Today CODEOWNERS only auto-requests review — approval is not a merge gate.

Headless signup + install (agents / CI)

⚠️ --ci is not currently supported in published builds (see CI Mode). This flow works in development builds only.

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:

npx @posthog/wizard --ci --signup \
  --email [email protected] \
  --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:

# Human-readable (when stdout is a TTY)
npx @posthog/wizard provision --email [email protected] --region us

# Machine-readable — auto when stdout is piped, or force with --json
npx @posthog/wizard provision --email [email protected] --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:

| Option | Description | Type | Default | Choices | Environment Variable | | ----------------- | ---------------------------------------------------------------- | ------- | ------- | ---------------------------------------------------- | ------------------------------ | | --help | Show help | boolean | | | | | --version | Show version number | boolean | | | | | --debug | Enable verbose logging | boolean | false | | POSTHOG_WIZARD_DEBUG | | --signup | Create a new PostHog account during setup | boolean | false | | POSTHOG_WIZARD_SIGNUP | | --install-dir | Directory to install PostHog in | string | | | POSTHOG_WIZARD_INSTALL_DIR | | --ci | Enable CI mode for non-interactive execution | boolean | false | | POSTHOG_WIZARD_CI | | --api-key | PostHog personal API key (phx_xxx) for authentication | string | | | POSTHOG_WIZARD_API_KEY | | --no-telemetry | Disable wizard run-state telemetry | boolean | false | | POSTHOG_WIZARD_NO_TELEMETRY |

CI Mode

⚠️ CI mode is not currently supported in published builds. PostHog's LLM gateway doesn't yet grant the scopes the wizard needs to personal API keys for most users, so non-interactive --ci runs fail at the gateway. The flag is disabled in the published package and exits with an error — run the wizard in an interactive terminal instead (npx @posthog/wizard). The notes below describe CI mode as it works in development builds.

Run the wizard non-interactive executions with --ci:

npx @posthog/wizard --ci --api-key $POSTHOG_PERSONAL_API_KEY --install-dir .

When running in CI mode (--ci):

• Bypasses OAuth login flow (uses personal API key directly)
• Auto-selects defaults for all prompts
• Skips MCP server installation
• Auto-continues on git warnings (uncommitted/untracked files)
• Auto-consents to AI usage

The CLI args override environment variables in CI mode.

Required Flags for CI Mode

• --api-key: Personal API key (phx_xxx) from your PostHog settings
• --install-dir: Directory to install PostHog in (e.g., . for current directory)

Required API Key Scopes

When creating your personal API key, ensure it has the following scopes enabled:

• user:read - Required to fetch user information
• project:read - Required to fetch project details and API token
• llm_gateway:read - Required for LLM gateway access
• dashboard:write - Required to create dashboards
• insight:write - Required to create insights

OAuth app scope ceiling

The wizard's OAuth app on the PostHog side caps the scopes its tokens may carry (OAuthApplication.scopes). Any scope requested in this repo (see src/lib/oauth/program-scopes.ts) must be present in that list. This is the allow-list to keep in sync — a net-new scope (e.g. product_enablement:write) must be added to the live OAuthApplication.scopes on the PostHog side before a token can be granted it:

user:read,project:read,llm_gateway:read,dashboard:read,dashboard:write,insight:read,insight:write,query:read,notebook:read,notebook:write,health_issue:read,wizard_session:read,wizard_session:write,feature_flag:read,experiment:read,experiment_saved_metric:read,survey:read,session_recording:read,error_tracking:read,web_analytics:read,llm_analytics:read,cohort:read,person:read,annotation:read,annotation:write,activity_log:read,property_definition:read,event_definition:read,action:read,warehouse_table:read,warehouse_view:read,external_data_source:read,external_data_source:write,alert:read,subscription:read,feature_flag:write,integration:read,organization:read,task:read,task:write,signal_scout:read,signal_scout:write,external_data_source:read,external_data_source:write,llm_skill:read,llm_skill:write,product_enablement:write

Command changes (CLI overhaul)

The CLI was overhauled to consolidate commands into a smaller, extensible surface. If you used an older command, here's where it went:

| Old command | New command | What changed | |---|---|---| | wizard integrate | wizard (default flow) | Command removed; the default flow runs the integration | | wizard events-audit | wizard audit events | Now an audit-family subcommand | | wizard audit (single audit) | wizard audit <subcommand> | Now a family; see Audit for the subcommands | | wizard audit-3000 | removed | Retired | | wizard revenue | wizard revenue-analytics | Renamed (old revenue removed) | | wizard upload-sourcemaps | wizard upload-source-maps | Renamed; upload-sourcemaps still works as an alias |

Commands vs. programs: integrate was the command; the program behind it is posthog-integration, which still exists and now powers the default flow. Other commands depend on it via requires: ['posthog-integration']. The program id is internal — it was never a command you typed.

Steal this code

While the wizard works great on its own, we also find the approach used by this project is a powerful way to improve AI agent coding sessions. Agents can run CLI tools, which means that conventional code like this can participate in the AI revolution as well – with all the benefits and control that conventional code implies.

If you want to use this code as a starting place for your own project, here's a quick explainer on its structure.

Entrypoint: run.ts

The entrypoint for this tool is run.ts. Use this file to interpret arguments and set up the general flow of the application.

Analytics

Did you know you can capture PostHog events even for smaller, supporting products like a command line tool? src/utils/analytics.ts is a great example of how to do it.

This file wraps posthog-node with some convenience functions to set up an analytics session and log events. We can see the usage and outcomes of this wizard alongside all of our other PostHog product data, and this is very powerful. For example: we could show in-product surveys to people who have used the wizard to improve the experience.

When the user authenticates, the wizard also streams live run state — current phase, task list, planned events — to POST /api/projects/{id}/wizard/sessions/ so the PostHog web app can render real-time progress. Updates are debounced (250ms) with phase changes flushed immediately; failures fall back silently to the wizard's debug log without disturbing the TUI. Pass --no-telemetry (or set POSTHOG_WIZARD_NO_TELEMETRY=1) to disable.

Leave rules behind

Supporting agent sessions after we leave is important. There are plenty of ways to break or misconfigure PostHog, so guarding against this is key.

src/utils/rules/add-editor-rules.ts demonstrates how to dynamically construct rules files and store them in the project's .cursor/rules directory.

Prompts and LLM interactions

LLM agent sessions are anti-deterministic: really, anything can happen.

But using LLMs for code generation is really advantageous: they can interpret existing code at scale and then modify it reliably.

If they are well prompted.

src/lib/prompts.ts demonstrates how to wrap a deterministic fence around a chaotic process. Every wizard session gets the same prompt, tailored to the specific files in the project.

These prompts are channeled using src/utils/query.ts to an LLM interface we host. This gives us more control: we can be certain of the model version and provider which interpret the prompts and modify the files. This way, we can find the right tools for the job and again, apply them consistently.

This also allows us to pick up the bill on behalf of our customers.

When we make improvements to this process, these are available instantly to all users of the wizard, no training delays or other ambiguity.

Keep secrets out of the LLM

The wizard somtimes needs to move a secret. The agent orchestrates that journey, but the raw value should never enter the LLM conversation, where it would be sent to the model provider, written to transcripts, and captured in logs.

src/lib/secret-vault.ts is a small, reusable pattern for exactly this. It's a session-scoped, in-memory vault: a tool that handles a secret calls put() to store the raw value and hands the agent an opaque secret:<uuid> reference instead. The agent passes that ref between tools as if it were the value; the host resolves it back to the real secret only at the last moment, inside the process, when it writes the file.

Two tools in src/lib/wizard-tools.ts form the ends of that pipe:

• wizard_ask with sensitive: true vaults the user's typed answer and returns { secretRef: "secret:..." } to the agent rather than the string.
• set_env_values accepts { secretRef } in place of a literal value and resolves it against the vault before writing — the value lands in the .env file but is never returned to the model.

The vault has no persistence and is dropped at the end of the run; refs minted in one session can't be resolved in another. The net effect: the model gets to drive the work end to end, but the only thing it ever sees is an opaque handle.

Build system

Built with tsdown (Rolldown). pnpm build bundles bin.ts into ESM chunks in dist/, inlining all local source and keeping npm dependencies external.

Environment variables

Build-time (locked). NODE_ENV is replaced with "production" at compile time. It cannot be overridden at runtime. All URLs, OAuth client IDs, and dev-mode code paths resolve to their production values unconditionally.

To add a new build-time constant, add it to env in tsdown.config.ts and export it from src/env.ts.

Runtime (allowlisted). Runtime env reads go through runtimeEnv() in src/env.ts, which only accepts keys in the RuntimeEnvKey union:

| Variable | Purpose | |---|---| | POSTHOG_WIZARD_BENCHMARK_CONFIG | Path to benchmark config file | | POSTHOG_WIZARD_BENCHMARK_FILE | Output path for benchmark results | | POSTHOG_WIZARD_LOG_DIR | Log directory override | | POSTHOG_WIZARD_DEBUG / DEBUG | Enable debug output | | MCP_URL | Override MCP server URL | | POSTHOG_API_KEY | API key for MCP subprocess auth | | TERM, TERM_PROGRAM, CI, etc. | Terminal/platform detection | | APPDATA, XDG_CONFIG_HOME | Platform path resolution |

To add a new runtime env var, add its key to RuntimeEnvKey in src/env.ts.

Direct process.env access is only used for subprocess environment writes (e.g. agent-interface.ts setting ANTHROPIC_BASE_URL), vendored code, and tests.

Import aliases

Path aliases defined in tsconfig.build.json, resolved by tsdown:

| Alias | Maps to | |---|---| | @env | src/env.ts | | @lib/* | src/lib/* | | @utils/* | src/utils/* | | @ui/* | src/ui/* | | @steps/* | src/steps/* | | @frameworks/* | src/frameworks/* |

Running locally

Quick test without linking

pnpm try --install-dir=[a path]

Development with auto-rebuild

pnpm run dev

This builds, links globally, and watches for changes. Leave it running - any .ts file changes will auto-rebuild. Then from any project:

wizard --integration=nextjs

# Or use local MCP server:
wizard --integration=nextjs --local-mcp

Testing

To run unit tests, run:

bin/test

To run E2E tests run:

bin/test-e2e

E2E tests are a bit more complicated to create and adjust due to to their mocked LLM calls. See the e2e-tests/README.md for more information.

Explore with an agent

You can hand the wizard to an AI agent and have it drive the real flow itself — deciding each screen and snapshotting the TUI to see what happened. The agent drives through the wizard-ci MCP tools (open_app / read_state / perform_action / render_screen / run_agent), which are registered in this repo's .mcp.json and bound in every session here — approve wizard-ci the first time you're prompted. The how-to is the exploring-the-wizard skill (.claude/skills/exploring-the-wizard/SKILL.md), which an agent discovers automatically.

Example prompt — explore against open-saas:

Explore the PostHog wizard against open-saas, following the exploring-the-wizard skill. Ask me for my phx key file path and project id, then clone https://github.com/wasp-lang/open-saas into a throwaway /tmp copy. Drive the whole flow yourself through the wizard-ci MCP tools, deciding each screen:

1. open_app on the /tmp copy, then read_state to see the screen and the actions legal right now.
2. At each key moment, render_screen and save the frame to /tmp/wz-explore-snaps/NN-<screen>.txt (numbered in order) so we get a readable record of the run.
3. Act: confirm_setup at intro, dismiss_outage at health-check, choose for any setup question, then run_agent at auth.
4. Poll read_state until integration is done (or failed — then report integrationError), snapshotting as the run screen progresses.
5. Finish the tail: dismiss outro / mcp / slack, then keep_skills.

Then show me the saved snapshots in order, the screen path, whether posthog landed in the app, and anything that broke.

Publishing your tool

To make your version of a tool usable with a one-line npx command:

1. Edit package.json, especially details like name, version
2. Run npm publish from your project directory
3. Now you can run it with npx yourpackagename

Health checks

src/lib/health-checks/ checks external status pages and PostHog-owned services before the wizard runs to decide whether it can proceed. The entry point is evaluateWizardReadiness(), which returns one of three values:

| Decision | Meaning | | ------------------- | --------------------------------------------------------------- | | yes | All services healthy — proceed normally. | | yes_with_warnings | Some services degraded but no critical dependency is down. | | no | A critical dependency is down or degraded — do not run. |

Module layout

| File | Responsibility | | --- | --- | | types.ts | Enums, interfaces (ServiceHealthStatus, AllServicesHealth, etc.) | | statuspage.ts | Statuspage.io v2 API helpers + checks for Anthropic, PostHog, GitHub, npm, Cloudflare | | endpoints.ts | Direct endpoint checks for LLM Gateway (/_liveness) and MCP (/) | | readiness.ts | checkAllExternalServices, evaluateWizardReadiness, readiness config | | index.ts | Barrel re-export | | testme.md | Test running instructions and endpoint reference |

What blocks a run

The DEFAULT_WIZARD_READINESS_CONFIG in readiness.ts controls this. It has two arrays:

• downBlocksRun — if any of these report status Down, readiness is No.
• degradedBlocksRun — if any of these report Degraded (or worse), readiness is No.

Current defaults

downBlocksRun: ['anthropic', 'posthogOverall', 'npmOverall', 'llmGateway', 'mcp'],
degradedBlocksRun: ['anthropic'],

Smoke test helper (scripts/smoke-test-ci.sh)

This repo includes a helper script to run a full end‑to‑end smoke test of the wizard packaged in a tarball against a real app from posthog/wizard-workbench. This will catch certain packaging issues that might not be caught by other tests.

Prerequisites

• Point to a wizard-workbench checkout either by:
  • Setting WIZARD_WORKBENCH_ROOT=/absolute/path/to/wizard-workbench, or
  • Cloning wizard-workbench next to this repo (so it lives at ../wizard-workbench).
• Set POSTHOG_PERSONAL_API_KEY either in your shell or in ../wizard-workbench/.env.
• (Optional) Set POSTHOG_PROJECT_ID to target a specific PostHog project.

Usage

# Default app: next-js/15-app-router-todo
./scripts/smoke-test-ci.sh

# Specify a different app from wizard-workbench/apps
./scripts/smoke-test-ci.sh next-js/15-pages-router-saas

# With API key (and optional project ID) inline
POSTHOG_PERSONAL_API_KEY=phx_your_key_here \
POSTHOG_PROJECT_ID=12345 \
./scripts/smoke-test-ci.sh next-js/15-pages-router-saas

# Pointing at a custom wizard-workbench checkout
WIZARD_WORKBENCH_ROOT=/path/to/wizard-workbench \
./scripts/smoke-test-ci.sh

The script will:

• Build and pack the wizard
• Copy the selected app into a temp directory
• Install dependencies for the app
• Install the packed wizard tarball into an isolated temp project
• Run wizard in --ci mode against the copied app and perform basic post‑install checks