{"id":29554220,"url":"https://github.com/posthog/wizard","last_synced_at":"2026-04-02T21:50:35.188Z","repository":{"id":281648631,"uuid":"938775588","full_name":"PostHog/wizard","owner":"PostHog","description":"Quickly add PostHog to your project using the setup wizard ✨","archived":false,"fork":false,"pushed_at":"2026-03-03T22:32:43.000Z","size":5791,"stargazers_count":92,"open_issues_count":43,"forks_count":16,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-03-03T22:51:37.537Z","etag":null,"topics":["onboarding","posthog","wizard"],"latest_commit_sha":null,"homepage":"https://posthog.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PostHog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-25T13:38:13.000Z","updated_at":"2026-03-03T20:41:42.000Z","dependencies_parsed_at":"2025-04-04T22:22:32.222Z","dependency_job_id":"9df36770-3ba9-441e-8c5e-013ad26d372a","html_url":"https://github.com/PostHog/wizard","commit_stats":null,"previous_names":["posthog/wizard"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/PostHog/wizard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PostHog%2Fwizard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PostHog%2Fwizard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PostHog%2Fwizard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PostHog%2Fwizard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PostHog","download_url":"https://codeload.github.com/PostHog/wizard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PostHog%2Fwizard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30324185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["onboarding","posthog","wizard"],"created_at":"2025-07-18T07:08:40.013Z","updated_at":"2026-03-10T04:01:16.191Z","avatar_url":"https://github.com/PostHog.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"posthoglogo\" src=\"https://user-images.githubusercontent.com/65415371/205059737-c8a4f836-4889-4654-902e-f302b187b6a0.png\"\u003e\n\u003c/p\u003e\n\n\u003e **⚠️ Experimental:** This wizard is still in an experimental phase. If you\n\u003e have any feedback, please drop an email to **[wizard@posthog.com](mailto:wizard@posthog.com)**.\n\n\u003ch1\u003ePostHog wizard ✨\u003c/h1\u003e\n\u003ch4\u003eThe PostHog wizard helps you quickly add PostHog to your project using AI.\u003c/h4\u003e\n\n# Usage\n\nTo use the wizard, you can run it directly using:\n\n```bash\nnpx @posthog/wizard\n```\n\nCurrently the wizard can be used for **React, NextJS, Svelte, Astro and React\nNative** projects. If you have other integrations you would like the wizard to\nsupport, please open a [GitHub issue](https://github.com/posthog/wizard/issues)!\n\n## MCP Commands\n\nThe wizard also includes commands for managing PostHog MCP (Model Context\nProtocol) servers:\n\n```bash\n# Install PostHog MCP server to supported clients\nnpx @posthog/wizard mcp add\n\n# Remove PostHog MCP server from supported clients\nnpx @posthog/wizard mcp remove\n```\n\n# Options\n\nThe following CLI arguments are available:\n\n| Option            | Description                                                      | Type    | Default | Choices                                              | Environment Variable           |\n| ----------------- | ---------------------------------------------------------------- | ------- | ------- | ---------------------------------------------------- | ------------------------------ |\n| `--help`          | Show help                                                        | boolean |         |                                                      |                                |\n| `--version`       | Show version number                                              | boolean |         |                                                      |                                |\n| `--debug`         | Enable verbose logging                                           | boolean | `false` |                                                      | `POSTHOG_WIZARD_DEBUG`         |\n| `--default`       | Use default options for all prompts                              | boolean | `true`  |                                                      | `POSTHOG_WIZARD_DEFAULT`       |\n| `--signup`        | Create a new PostHog account during setup                        | boolean | `false` |                                                      | `POSTHOG_WIZARD_SIGNUP`        |\n| `--integration`   | Integration to set up                                            | string  |         | \"nextjs\", \"astro\", \"react\", \"svelte\", \"react-native\", \"tanstack-router\", \"tanstack-start\" |                                |\n| `--menu`          | Show menu for manual integration selection instead of auto-detecting | boolean | `false` |                                                      | `POSTHOG_WIZARD_MENU`          |\n| `--force-install` | Force install packages even if peer dependency checks fail       | boolean | `false` |                                                      | `POSTHOG_WIZARD_FORCE_INSTALL` |\n| `--install-dir`   | Directory to install PostHog in                                  | string  |         |                                                      | `POSTHOG_WIZARD_INSTALL_DIR`   |\n| `--ci`            | Enable CI mode for non-interactive execution                     | boolean | `false` |                                                      | `POSTHOG_WIZARD_CI`            |\n| `--api-key`       | PostHog personal API key (phx_xxx) for authentication            | string  |         |                                                      | `POSTHOG_WIZARD_API_KEY`       |\n\n\u003e Note: A large amount of the scaffolding for this came from the amazing Sentry\n\u003e wizard, which you can find [here](https://github.com/getsentry/sentry-wizard)\n\u003e 💖\n\n# CI Mode\n\nRun the wizard non-interactive executions with `--ci`:\n\n```bash\nnpx @posthog/wizard --ci --api-key $POSTHOG_PERSONAL_API_KEY --install-dir .\n```\n\nWhen running in CI mode (`--ci`):\n\n- Bypasses OAuth login flow (uses personal API key directly)\n- Auto-selects defaults for all prompts\n- Skips MCP server installation\n- Auto-continues on git warnings (uncommitted/untracked files)\n- Auto-consents to AI usage\n\nThe CLI args override environment variables in CI mode.\n\n### Required Flags for CI Mode\n\n- `--api-key`: Personal API key (`phx_xxx`) from your [PostHog settings](https://app.posthog.com/settings/user-api-keys)\n- `--install-dir`: Directory to install PostHog in (e.g., `.` for current directory)\n\n### Required API Key Scopes\n\nWhen creating your personal API key, ensure it has the following scopes enabled:\n\n- `user:read` - Required to fetch user information\n- `project:read` - Required to fetch project details and API token\n- `introspection` - Required for API introspection\n- `llm_gateway:read` - Required for LLM gateway access\n- `dashboard:write` - Required to create dashboards\n- `insight:write` - Required to create insights\n\n# Steal this code\n\nWhile the wizard works great on its own, we also find the approach used by this\nproject is\n[a powerful way to improve AI agent coding sessions](https://posthog.com/blog/envoy-wizard-llm-agent).\nAgents can run CLI tools, which means that conventional code like this can\nparticipate in the AI revolution as well – with all the benefits and control\nthat conventional code implies.\n\nIf you want to use this code as a starting place for your own project, here's a\nquick explainer on its structure.\n\n## Entrypoint: `run.ts`\n\nThe entrypoint for this tool is `run.ts`. Use this file to interpret arguments\nand set up the general flow of the application.\n\n## Analytics\n\nDid you know you can capture PostHog events even for smaller, supporting\nproducts like a command line tool? `src/utils/analytics.ts` is a great example\nof how to do it.\n\nThis file wraps `posthog-node` with some convenience functions to set up an\nanalytics session and log events. We can see the usage and outcomes of this\nwizard alongside all of our other PostHog product data, and this is very\npowerful. For example: we could show in-product surveys to people who have used\nthe wizard to improve the experience.\n\n## Leave rules behind\n\nSupporting agent sessions after we leave is important. There are plenty of ways\nto break or misconfigure PostHog, so guarding against this is key.\n\n`src/utils/rules/add-editor-rules.ts` demonstrates how to dynamically construct\nrules files and store them in the project's `.cursor/rules` directory.\n\n## Prompts and LLM interactions\n\nLLM agent sessions are _anti-deterministic_: really, anything can happen.\n\nBut using LLMs for code generation is really advantageous: they can interpret\nexisting code at scale and then modify it reliably.\n\n_If_ they are well prompted.\n\n`src/lib/prompts.ts` demonstrates how to wrap a deterministic fence around a\nchaotic process. Every wizard session gets the same prompt, tailored to the\nspecific files in the project.\n\nThese prompts are channeled using `src/utils/query.ts` to an LLM interface we\nhost. This gives us more control: we can be certain of the model version and\nprovider which interpret the prompts and modify the files. This way, we can find\nthe right tools for the job and again, apply them consistently.\n\nThis also allows us to pick up the bill on behalf of our customers.\n\nWhen we make improvements to this process, these are available instantly to all\nusers of the wizard, no training delays or other ambiguity.\n\n## Running locally\n\n### Quick test without linking\n\n```bash\npnpm try --install-dir=[a path]\n```\n\n### Development with auto-rebuild\n\n```bash\npnpm run dev\n```\n\nThis builds, links globally, and watches for changes. Leave it running - any `.ts` file changes will auto-rebuild. Then from any project:\n\n```bash\nwizard --integration=nextjs\n\n# Or use local MCP server:\nwizard --integration=nextjs --local-mcp\n```\n\n## Testing\n\nTo run unit tests, run:\n\n```bash\nbin/test\n```\n\nTo run E2E tests run:\n\n```bash\nbin/test-e2e\n```\n\nE2E tests are a bit more complicated to create and adjust due to to their mocked\nLLM calls. See the `e2e-tests/README.md` for more information.\n\n## Publishing your tool\n\nTo make your version of a tool usable with a one-line `npx` command:\n\n1. Edit `package.json`, especially details like `name`, `version`\n2. Run [`npm publish`](https://docs.npmjs.com/cli/v7/commands/npm-publish) from\n   your project directory\n3. Now you can run it with `npx yourpackagename`\n\n# Health checks\n\n`src/lib/health-checks/` checks external status pages and PostHog-owned\nservices before the wizard runs to decide whether it can proceed. The entry\npoint is `evaluateWizardReadiness()`, which returns one of three values:\n\n| Decision            | Meaning                                                         |\n| ------------------- | --------------------------------------------------------------- |\n| `yes`               | All services healthy — proceed normally.                        |\n| `yes_with_warnings` | Some services degraded but no critical dependency is down.      |\n| `no`                | A critical dependency is down or degraded — do not run.         |\n\n### Module layout\n\n| File | Responsibility |\n| --- | --- |\n| `types.ts` | Enums, interfaces (`ServiceHealthStatus`, `AllServicesHealth`, etc.) |\n| `statuspage.ts` | Statuspage.io v2 API helpers + checks for Anthropic, PostHog, GitHub, npm, Cloudflare |\n| `endpoints.ts` | Direct endpoint checks for LLM Gateway (`/_liveness`) and MCP (`/`) |\n| `readiness.ts` | `checkAllExternalServices`, `evaluateWizardReadiness`, readiness config |\n| `index.ts` | Barrel re-export |\n| `testme.md` | Test running instructions and endpoint reference |\n\n## What blocks a run\n\nThe `DEFAULT_WIZARD_READINESS_CONFIG` in `readiness.ts` controls this. It has\ntwo arrays:\n\n- **`downBlocksRun`** — if any of these report status **Down**, readiness is\n  **No**.\n- **`degradedBlocksRun`** — if any of these report **Degraded** (or worse),\n  readiness is **No**.\n\n### Current defaults\n\n```ts\ndownBlocksRun: ['anthropic', 'posthogOverall', 'npmOverall', 'llmGateway', 'mcp'],\ndegradedBlocksRun: ['anthropic'],\n```\n\n## Smoke test helper (`scripts/smoke-test-ci.sh`)\n\nThis 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`](https://github.com/PostHog/wizard-workbench). This will catch certain packaging issues that might not be caught by other tests.\n\n**Prerequisites**\n\n- Point to a `wizard-workbench` checkout either by:\n  - Setting `WIZARD_WORKBENCH_ROOT=/absolute/path/to/wizard-workbench`, or\n  - Cloning `wizard-workbench` next to this repo (so it lives at `../wizard-workbench`).\n- Set `POSTHOG_PERSONAL_API_KEY` either in your shell or in `../wizard-workbench/.env`.\n- (Optional) Set `POSTHOG_PROJECT_ID` to target a specific PostHog project.\n\n**Usage**\n\n```bash\n# Default app: next-js/15-app-router-todo\n./scripts/smoke-test-ci.sh\n\n# Specify a different app from wizard-workbench/apps\n./scripts/smoke-test-ci.sh next-js/15-pages-router-saas\n\n# With API key (and optional project ID) inline\nPOSTHOG_PERSONAL_API_KEY=phx_your_key_here \\\nPOSTHOG_PROJECT_ID=12345 \\\n./scripts/smoke-test-ci.sh next-js/15-pages-router-saas\n\n# Pointing at a custom wizard-workbench checkout\nWIZARD_WORKBENCH_ROOT=/path/to/wizard-workbench \\\n./scripts/smoke-test-ci.sh\n```\n\nThe script will:\n\n- Build and pack the wizard\n- Copy the selected app into a temp directory\n- Install dependencies for the app\n- Install the packed wizard tarball into an isolated temp project\n- Run `wizard` in `--ci` mode against the copied app and perform basic post‑install checks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthog%2Fwizard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposthog%2Fwizard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthog%2Fwizard/lists"}