Skip to content

Commit 41a5ca7

Browse files
sarahxsandersclaudegewenyu99
authored
docs(wizard): document CLI commands and old→new mapping (#17680)
* docs(wizard): document CLI commands and old→new command mapping Adds a Commands section to the AI wizard page with the command list, the overhaul's old→new mapping table, and a supplemental diagram. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(wizard): list audit subcommands and clarify commands vs. skills Add the full audit subcommand list, the `wizard skill` command, and a note that `wizard audit <subcommand>` chooses an audit area rather than taking a skill name. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(wizard): `wizard audit` runs events by default (not a picker) Bare `wizard audit` runs the events audit directly; pass a subcommand for others. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * final docs tweak, user facing and handbook * Update contents/docs/ai-engineering/ai-wizard.mdx Co-authored-by: Vincent (Wen Yu) Ge <29069505+gewenyu99@users.noreply.github.com> * Update MCP commands and add tutorial optionnits Added 'wizard mcp tutorial' command to manage the PostHog MCP server and explore the tutorial. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Vincent (Wen Yu) Ge <29069505+gewenyu99@users.noreply.github.com>
1 parent ed4dd6e commit 41a5ca7

2 files changed

Lines changed: 53 additions & 2 deletions

File tree

‎contents/docs/ai-engineering/ai-wizard.mdx‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ title: AI wizard
44

55
import WizardInstall from 'getting-started/_snippets/wizard.mdx'
66

7-
The PostHog wizard automatically installs and instruments PostHog into your application codebase using AI. It's an agentic CLI tool that handles the entire PostHog integration process on your behalf.
7+
The PostHog wizard is an agentic CLI tool that uses AI to set up and manage PostHog in your codebase. By default, it installs and instruments PostHog for you with a single command: `npx -y @posthog/wizard@latest`.
88

9-
Set up the PostHog platform in minutes, with a single command.
9+
It does more than installation, though. The wizard can also audit an existing integration, migrate you from another vendor, upload source maps, set up Revenue Analytics, and diagnose configuration issues – so it's just as useful after you're up and running as it is on day one.
1010

1111
<WizardCommand slim />
1212

@@ -48,6 +48,49 @@ The AI wizard integrating both the JS Web SDK and Node SDK into a Next.js applic
4848

4949
<WizardInstall />
5050

51+
## Commands
52+
53+
Running `npx @posthog/wizard` starts the default integration flow. The wizard also supports the following commands:
54+
55+
| Command | What it does |
56+
|---|---|
57+
| `wizard` | Default flow – installs and instruments PostHog |
58+
| `wizard audit <subcommand>` | Audit an existing integration – see [Audit subcommands](#audit-subcommands) |
59+
| `wizard revenue-analytics` | Wire up Stripe + PostHog revenue analytics |
60+
| `wizard migrate` | Migrate from another analytics or feature-flag vendor |
61+
| `wizard upload-source-maps` | Upload source maps to PostHog Error Tracking |
62+
| `wizard mcp add` / `wizard mcp remove` / `wizard mcp tutorial` | Manage the PostHog MCP server for your AI agent, or explore the MCP tutorial |
63+
| `wizard slack add` | Connect PostHog to your Slack |
64+
| `wizard skill <skill-name>` | Run a single skill by name – browse the available skills in the [context-mill releases](https://github.com/PostHog/context-mill/releases/latest) |
65+
66+
### Audit subcommands
67+
68+
`@npx @posthog/wizard audit` on its own runs the `events` audit. Pass a subcommand to run a specific one.
69+
70+
| Command | What it does |
71+
|---|---|
72+
| `wizard audit events` | Audit event capture quality and cost (default) |
73+
| `wizard audit all` | Comprehensive audit across every area |
74+
| `wizard audit autocapture` | Audit autocapture setup and cost |
75+
| `wizard audit feature-flags` | Audit feature flag usage and cost |
76+
| `wizard audit identify` | Audit your `$identify` implementation |
77+
| `wizard audit session-replay` | Audit session replay setup |
78+
| `wizard audit web-analytics` | Audit web analytics setup |
79+
80+
### Legacy commands
81+
82+
The CLI was overhauled to consolidate commands into a smaller, more consistent surface. If you used an older command name, here's where it went:
83+
84+
| Old command | New command | What changed |
85+
|---|---|---|
86+
| `wizard integrate` | `wizard` | The default flow now runs the integration |
87+
| `wizard events-audit` | `wizard audit events` | Now an `audit` subcommand |
88+
| `wizard audit` | `wizard audit <subcommand>` | Now takes a subcommand; `wizard audit all` runs a full audit |
89+
| `wizard revenue` | `wizard revenue-analytics` | Renamed – update any scripts using `revenue` |
90+
| `wizard upload-sourcemaps` | `wizard upload-source-maps` | Renamed (the old `upload-sourcemaps` still works) |
91+
92+
## Feedback
93+
5194
We think flows like the AI wizard are pretty cool and the future of developer experience. The AI wizard is our recommended and default method for [installing PostHog](/docs/getting-started/install?tab=wizard) and getting started.
5295

5396
If you have any feedback or requests, we would love to hear from you. Feel free to comment on this page or open an issue on [GitHub](https://github.com/PostHog/wizard/issues).

‎contents/handbook/docs-and-wizard/developing-the-wizard.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,14 @@ To direct the agent, the wizard uses the PostHog [context mill repository](https
2222

2323
The context mill repo generates a zip file and manifest that determines the structure of the skills packages.
2424

25+
### Commands and skills
26+
27+
The wizard's command surface comes from context mill, not hardcoded in the wizard. A skill becomes a command when its `config.yaml` declares a `cli:` block with `role: command` – so `wizard audit events` *is* the `audit-events` skill, promoted to a command. A skill without that block stays reachable only via `wizard skill <name>`. Same machinery, two surfaces — which is why `wizard audit <subcommand>` chooses an audit area rather than taking a skill name (the `[skill]` label in `wizard audit --help` is an internal positional name, not a prompt for a skill).
28+
29+
Because these entries are read from the published manifest at runtime, adding or renaming a skill-backed command is a **context mill release – no wizard release required**. Family parents (like `audit`) and their picker behavior live in the wizard; their subcommands resolve at runtime.
30+
31+
The full `cli:` block schema (roles, `parentCommand`, the `default` leaf, naming rules) lives in [context mill's CONTRIBUTING.md](https://github.com/PostHog/context-mill/blob/main/CONTRIBUTING.md); the wizard side (command registration, families, aliases) is documented in the wizard repo's [AGENTS.md](https://github.com/PostHog/wizard/blob/main/AGENTS.md).
32+
2533
## Developing the wizard
2634

2735
Use the [wizard workbench](https://github.com/PostHog/wizard-workbench) for local, end-to-end development of the wizard. The workbench can run the full wizard stack in local development mode, with hot reload where supported.

0 commit comments

Comments
 (0)