{"id":"a1bdefc6-6b55-47db-adb4-ae2e80c3422c","slug":"plugin-posthog-cli","kind":"skill","name":"plugin-posthog-cli","summary":"PostHog CLI workflows for Claude Code and Codex — schema-first analytics, HogQL, endpoints, and verified symbolication.","owner":"yigitkonur","repoUrl":"https://github.com/yigitkonur/plugin-posthog-cli","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-13T07:44:00.000Z","addedAt":"2026-10-31T23:06:58.881Z","logoUrl":"https://avatars.githubusercontent.com/u/9989650?u=1f45f93527e1c266fd13a8bfed90d4193d0e4c44&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","data-analytics"],"tags":["claude-code","codex","error-tracking","hogql","posthog","product-analytics","sourcemaps"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-31T23:08:02.031Z","sample":false,"url":"https://conduits.dev/tools/plugin-posthog-cli","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# plugin-posthog-cli\n\nA dual Claude Code and Codex plugin that teaches agents to use **`posthog-cli`** as a real product-analytics and observability control plane — not just a source-map uploader.\n\nWhen someone asks “what are users doing?”, “why did this funnel drop?”, “is analytics ingestion working?”, “find the replay for this error”, “manage this feature flag”, or “upload the Hermes maps”, the agent should not guess and should not dump the entire PostHog schema into context. This plugin gives it a project-scoped, schema-first ladder for getting evidence from the terminal safely.\n\n## What it fixes\n\nAgents tend to fail at PostHog in predictable ways:\n\n- query the wrong project or region and trust a successful HTTP response\n- confuse ingestion keys (`phc_…`) with personal API tokens (`phx_…`)\n- guess one of ~400 API tool names or nested input schemas\n- reach for raw HogQL when a typed trends/funnel tool is more correct\n- dump persons/events/replays with PII into context\n- use `--dry-run` and claim an upload was validated even though file processing and network were skipped\n- assume sourcemap injection is local-only (it can create a release)\n- persist a credential-bearing CI git remote into PostHog release metadata\n- trust a “Successfully cloned metadata” message without inspecting the Hermes map\n- create test flags/endpoints/annotations in production just to prove auth\n\nThe skill makes these failure paths explicit and gives exact recovery commands.\n\n## The operating ladder\n\n```text\nrung 0  target      prove host + project + auth\nrung 1  discover    search tools / read schema / inspect taxonomy\nrung 2  query       typed trends/funnel/replay/error tools (preferred)\nrung 3  SQL         bounded HogQL only for unsupported shapes\nrung 4  mutate      dry-run / diff / confirm / verify / clean up\n```\n\n## What's included\n\nOne auto-triggering `posthog` skill plus fourteen progressively disclosed references:\n\n- `cli-command-catalog.md` — complete `posthog-cli 0.8.1` command tree and key flags\n- `auth-project-scoping.md` — npm installation, allowScripts, OAuth, env/direnv, CI scopes, region proof\n- `api-tools.md` — `tools/search/info/schema/call`, JSON shaping, safety annotations, skills and AGENTS installers\n- `analytics-workflows.md` — schema-first trends, funnels, retention, paths, persons, dashboards, recordings\n- `hogql.md` — `exp query`, validation, bounded recipes, system tables, shell quoting, privacy-safe output\n- `observability.md` — errors, replays, logs, APM, LLM analytics, releases, missing-data diagnosis\n- `product-operations.md` — flags, experiments, surveys, insights, cohorts, workflows, warehouse operations\n- `endpoints-schema-tasks.md` — endpoints-as-YAML, typed SDK generation, tasks, experimental caveats\n- `symbolication-releases.md` — web/Hermes/dSYM/ProGuard/native symbols and release metadata hygiene\n- `safety-data-handling.md` — PII minimization, authorization boundaries, temporary data and cleanup\n- `troubleshooting.md` — real failures observed against CLI 0.8.1 and exact recovery paths\n- `project-map.md` — optional per-repo non-secret context and capability matrix\n- `investigation-playbooks.md` — end-to-end metric, ingestion, audit, release, endpoint, and rollout workflows\n- `sources-versioning.md` — source authority, official links, version drift, and upgrade re-validation\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add yigitkonur/plugin-posthog-cli\n/plugin install posthog-cli@plugin-posthog-cli\n```\n\n### Codex plugin\n\n```bash\ncodex plugin marketplace add yigitkonur/plugin-posthog-cli\ncodex plugin add posthog-cli@plugin-posthog-cli\n```\n\nThe same canonical `skills/posthog/` directory powers both clients. Codex receives it through\n`.codex-plugin/plugin.json`; repository-local Codex discovery is also supported through the\n`.agents/skills/posthog` symlink. Invoke the installed plugin explicitly as\n`$posthog-cli:posthog` or select it from `/skills`; repository-local discovery also exposes\n`$posthog`. Prefer the namespaced form when OpenAI's official PostHog plugin is installed, since\nan unqualified `$posthog` can be ambiguous. Implicit selection remains enabled for matching\nPostHog CLI tasks.\n\n### Agent Skills CLI\n\n```bash\nnpx -y skills add -y -g yigitkonur/plugin-posthog-cli/skills/posthog\n```\n\n### Install the PostHog CLI\n\n```shell\nnpm install -g @posthog/cli@latest\nposthog-cli --version\n```\n\nThe binary is named **`posthog-cli`**, not `posthog`.\n\n## Authenticate\n\nInteractive:\n\n```shell\nposthog-cli login\n```\n\nFor project-local and CI use, prefer explicit variables:\n\n```shell\nexport POSTHOG_CLI_HOST='https://us.posthog.com'   # or https://eu.posthog.com\nexport POSTHOG_CLI_PROJECT_ID='12345'\nexport POSTHOG_CLI_API_KEY='phx_…'\n```\n\nThen prove the target:\n\n```shell\nposthog-cli api call --json project-get '{}' | jq '{id,name}'\n```\n\nFor local multi-project work, put those exports in a gitignored, mode-600 `.envrc` and run `direnv allow`. Never commit the API key.\n\n## Why CLI instead of only the PostHog MCP plugin?\n\nThe CLI exposes the same broad agent-first tool catalog while adding deterministic shell composition, `jq`, HogQL validation, endpoint YAML workflows, artifact/symbol uploaders, and CI-friendly auth. MCP remains useful when a terminal is unavailable; the CLI is better for reproducible repo and release workflows.\n\n## Example asks that trigger the skill\n\n- “Check our PostHog data and tell me what users did this week.”\n- “Why did onboarding conversion drop?”\n- “Run a HogQL query for top events by app version.”\n- “Find session replays where this error happened.”\n- “Audit whether our SDK is sending to the right region.”\n- “List our active feature flags and blast radius.”\n- “Turn this query into a PostHog endpoint YAML.”\n- “Upload and verify Expo Hermes source maps.”\n- “Why are PostHog stack frames still minified?”\n- “Check whether `$ai_generation` is arriving.”\n\n## Built from runtime evidence\n\nThis was produced by driving every command family of `posthog-cli 0.8.1` against a live PostHog Cloud project: API tool discovery/calls, typed analytics, HogQL check/run, endpoint file-run→push→pull→diff→delete, schema generation, artifact dry-runs, and a real sourcemap inject→upload→download round trip with cleanup.\n\nThat exercise found behavior absent or easy to miss in help text:\n\n- npm global `approve-scripts` fails with `EGLOBAL`\n- `api run` does not exist; the command is `api call`\n- endpoint file variables can fail from CLI/server schema mismatch\n- schema generation can omit ingested custom events\n- `sourcemap inject` can create a release\n- `hermes clone` can report success while only copying `chunk_id`\n- workflow expressions can land literally as release versions\n- CLI-derived git metadata can persist a CI checkout token in `remote_url`\n- a wrong regional ingestion host can return HTTP 200 while the intended project remains empty\n\nThe plugin routes all of those directly to the relevant workflow rather than burying them in an errata file.\n\n## Optional local context\n\nCreate `.claude/posthog-cli.local.md` (gitignored) with non-secret project facts such as host, project ID, canonical events, available PostHog products, and test-account markers. See `skills/posthog/references/project-map.md`. Never store tokens there.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"}