plugin-posthog-cli

plugin-posthog-cli

A 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.

When 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.

What it fixes

Agents tend to fail at PostHog in predictable ways:

• query the wrong project or region and trust a successful HTTP response
• confuse ingestion keys (phc_…) with personal API tokens (phx_…)
• guess one of ~400 API tool names or nested input schemas
• reach for raw HogQL when a typed trends/funnel tool is more correct
• dump persons/events/replays with PII into context
• use --dry-run and claim an upload was validated even though file processing and network were skipped
• assume sourcemap injection is local-only (it can create a release)
• persist a credential-bearing CI git remote into PostHog release metadata
• trust a “Successfully cloned metadata” message without inspecting the Hermes map
• create test flags/endpoints/annotations in production just to prove auth

The skill makes these failure paths explicit and gives exact recovery commands.

The operating ladder

rung 0  target      prove host + project + auth
rung 1  discover    search tools / read schema / inspect taxonomy
rung 2  query       typed trends/funnel/replay/error tools (preferred)
rung 3  SQL         bounded HogQL only for unsupported shapes
rung 4  mutate      dry-run / diff / confirm / verify / clean up

What's included

One auto-triggering posthog skill plus fourteen progressively disclosed references:

• cli-command-catalog.md — complete posthog-cli 0.8.1 command tree and key flags
• auth-project-scoping.md — npm installation, allowScripts, OAuth, env/direnv, CI scopes, region proof
• api-tools.md — tools/search/info/schema/call, JSON shaping, safety annotations, skills and AGENTS installers
• analytics-workflows.md — schema-first trends, funnels, retention, paths, persons, dashboards, recordings
• hogql.md — exp query, validation, bounded recipes, system tables, shell quoting, privacy-safe output
• observability.md — errors, replays, logs, APM, LLM analytics, releases, missing-data diagnosis
• product-operations.md — flags, experiments, surveys, insights, cohorts, workflows, warehouse operations
• endpoints-schema-tasks.md — endpoints-as-YAML, typed SDK generation, tasks, experimental caveats
• symbolication-releases.md — web/Hermes/dSYM/ProGuard/native symbols and release metadata hygiene
• safety-data-handling.md — PII minimization, authorization boundaries, temporary data and cleanup
• troubleshooting.md — real failures observed against CLI 0.8.1 and exact recovery paths
• project-map.md — optional per-repo non-secret context and capability matrix
• investigation-playbooks.md — end-to-end metric, ingestion, audit, release, endpoint, and rollout workflows
• sources-versioning.md — source authority, official links, version drift, and upgrade re-validation

Install

Claude Code

/plugin marketplace add yigitkonur/plugin-posthog-cli
/plugin install posthog-cli@plugin-posthog-cli

Codex plugin

codex plugin marketplace add yigitkonur/plugin-posthog-cli
codex plugin add posthog-cli@plugin-posthog-cli

The same canonical skills/posthog/ directory powers both clients. Codex receives it through .codex-plugin/plugin.json; repository-local Codex discovery is also supported through the .agents/skills/posthog symlink. Invoke the installed plugin explicitly as $posthog-cli:posthog or select it from /skills; repository-local discovery also exposes $posthog. Prefer the namespaced form when OpenAI's official PostHog plugin is installed, since an unqualified $posthog can be ambiguous. Implicit selection remains enabled for matching PostHog CLI tasks.

Agent Skills CLI

npx -y skills add -y -g yigitkonur/plugin-posthog-cli/skills/posthog

Install the PostHog CLI

npm install -g @posthog/cli@latest
posthog-cli --version

The binary is named posthog-cli, not posthog.

Authenticate

Interactive:

posthog-cli login

For project-local and CI use, prefer explicit variables:

export POSTHOG_CLI_HOST='https://us.posthog.com'   # or https://eu.posthog.com
export POSTHOG_CLI_PROJECT_ID='12345'
export POSTHOG_CLI_API_KEY='phx_…'

Then prove the target:

posthog-cli api call --json project-get '{}' | jq '{id,name}'

For local multi-project work, put those exports in a gitignored, mode-600 .envrc and run direnv allow. Never commit the API key.

Why CLI instead of only the PostHog MCP plugin?

The 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.

Example asks that trigger the skill

• “Check our PostHog data and tell me what users did this week.”
• “Why did onboarding conversion drop?”
• “Run a HogQL query for top events by app version.”
• “Find session replays where this error happened.”
• “Audit whether our SDK is sending to the right region.”
• “List our active feature flags and blast radius.”
• “Turn this query into a PostHog endpoint YAML.”
• “Upload and verify Expo Hermes source maps.”
• “Why are PostHog stack frames still minified?”
• “Check whether $ai_generation is arriving.”

Built from runtime evidence

This 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.

That exercise found behavior absent or easy to miss in help text:

• npm global approve-scripts fails with EGLOBAL
• api run does not exist; the command is api call
• endpoint file variables can fail from CLI/server schema mismatch
• schema generation can omit ingested custom events
• sourcemap inject can create a release
• hermes clone can report success while only copying chunk_id
• workflow expressions can land literally as release versions
• CLI-derived git metadata can persist a CI checkout token in remote_url
• a wrong regional ingestion host can return HTTP 200 while the intended project remains empty

The plugin routes all of those directly to the relevant workflow rather than burying them in an errata file.

Optional local context

Create .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.

License

MIT. See LICENSE.