Posthog

PostHog CLI

Operate PostHog through the posthog-cli binary. Every command pattern and caveat in this skill was exercised against a live PostHog Cloud project with CLI 0.8.1. When local --help disagrees, trust the installed CLI, then update the relevant reference.

Why a ladder, not a data dump

PostHog exposes hundreds of API tools and potentially millions of events. Avoid loading the whole catalog or unbounded query output. Move through this ladder and stop as soon as the question is answered:

Rung 0  target      prove host + project + auth                         (cheap)
Rung 1  discover    search tools / read schema / inspect event taxonomy
Rung 2  query       typed query tool (trends, funnel, replay, errors)   (preferred)
Rung 3  SQL         HogQL only when typed tools cannot express the ask
Rung 4  mutate      dry-run / diff / confirm / verify                   (shared state)

Use api for product operations and typed analytics. Use exp query for ad hoc HogQL. Use artifact commands only for release symbolication. Keep raw output out of context: prefer --json | jq and select the fields needed to decide.

Start every session by proving the target

Never infer the region from ingestion SDK variables, a repository name, or an old dotenv file. PostHog can accept events at the wrong regional ingestion endpoint with HTTP 200 and still not place them in the intended project. Prove the management host and project independently:

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

Expected auth variables:

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

Prefer project-local .envrc + direnv over a global token when work spans multiple projects. Keep .envrc ignored and mode 600. posthog-cli login stores OAuth credentials in ~/.posthog/credentials.json; env vars override the ambiguity and make CI/project scoping explicit. Read references/auth-project-scoping.md before setup, region debugging, CI auth, or claiming that ingestion works.

Route by intent

User intent	First command	Load
Discover available operations	posthog-cli api search '<regex>'	references/api-tools.md
Product metric, funnel, paths, retention	api info query-…, then api call	references/analytics-workflows.md
Custom aggregation / entity search	exp query check, then exp query run	references/hogql.md
Event/person/property discovery	api call read-data-schema …	references/analytics-workflows.md
Session replay / errors / logs / LLM traces	matching query-* or list tool	references/observability.md
Feature flags / experiments / surveys	list/read tools, mutate only with approval	references/product-operations.md
Endpoint-as-code	exp endpoints …	references/endpoints-schema-tasks.md
Typed event schema generation	exp schema …	references/endpoints-schema-tasks.md
Web JS sourcemaps	sourcemap process	references/symbolication-releases.md
Expo / React Native Hermes maps	hermes upload	references/symbolication-releases.md
iOS native symbols	dsym upload	references/symbolication-releases.md
Android mappings	proguard upload	references/symbolication-releases.md
CLI flag / leaf-command lookup	<command> --help	references/cli-command-catalog.md
Something failed or looks empty	run the diagnostic ladder	references/troubleshooting.md
End-to-end investigation / audit	choose the outcome playbook	references/investigation-playbooks.md
Current docs or version drift	rank sources, re-validate	references/sources-versioning.md

API tool discovery is mandatory

The CLI bundles a changing catalog of hundreds of MCP-style tools. Do not guess tool names, input keys, or nested query schemas:

posthog-cli api search 'error|recording|funnel'
posthog-cli api info --json query-funnel
posthog-cli api schema query-funnel series
posthog-cli api call --json query-funnel '<validated JSON>' | jq '…'

Treat api info as operational documentation, not merely a JSON schema. Descriptions explain cost, defaults, tool choice, and query semantics. Drill into any field that says DO NOT GUESS. Read references/api-tools.md for the exact discovery ladder, output handling, tool safety annotations, and mutation behavior.

Query schema-first

Before querying analytics:

1. Discover events with read-data-schema.
2. Discover properties for the selected event/person/session.
3. Validate property values when filtering.
4. Use the matching typed query tool (query-trends, query-funnel, query-retention, query-stickiness, query-paths, query-lifecycle, replay/error/log/LLM query tools).
5. Fall back to HogQL only for joins, CTEs, entity search in system.*, window functions, or shapes unavailable to typed tools.

Validate HogQL before execution:

posthog-cli exp query check 'SELECT event, count() FROM events GROUP BY event'
posthog-cli exp query run 'SELECT event, count() AS c FROM events GROUP BY event ORDER BY c DESC LIMIT 25'

Always bound time and rows. Avoid emitting distinct IDs, emails, names, URLs with secrets, or full event-property blobs unless the task specifically requires them. Aggregate first.

Treat mutations as shared production state

Read operations may proceed. For creates/updates/deletes:

1. Inspect with api info <tool>.
2. Use api call --dry-run … when supported.
3. For endpoint YAML, use exp endpoints diff or push --dry-run.
4. Confirm the exact target IDs and intended outcome.
5. Use --confirm only after authorization for destructive tools.
6. Read back the entity or list after mutation.
7. Remove temporary smoke-test artifacts.

The CLI itself blocks tools marked destructive without --confirm, but not every write is classified destructive: create operations may execute without a prompt. Agent judgment remains required. Never create a probe event, annotation, endpoint, release, flag, survey, or experiment just to prove auth unless the user authorized that shared-state mutation. See references/safety-data-handling.md.

Symbolication is a release pipeline

Artifact commands do more than upload files. sourcemap inject can contact PostHog and create a release when release metadata is supplied. The CLI auto-derives git metadata, which can capture a credential-bearing checkout remote in CI. Always provide explicit release identity, sanitize the remote before upload, and verify the symbol set afterwards.

Use top-level dry-run syntax:

posthog-cli --dry-run hermes upload --directory dist

Dry-run short-circuits artifact processing and network access; it does not prove that files are valid, paired, or accepted by PostHog. For real verification, upload release artifacts in the actual release job, then list/download the resulting symbol set by ref. Read references/symbolication-releases.md before editing CI, Expo/EAS, Xcode, Gradle, or native symbol workflows.

Known 0.8.1 traps

• The npm package declares the binary as posthog-cli, not posthog.
• npm 11 may warn that @posthog/cli postinstall is not in allowScripts; global npm approve-scripts fails with EGLOBAL. Use npm user config if approval is required.
• Put global flags before the command (posthog-cli --dry-run hermes upload …).
• Prefer --dotenv-file; Node's npm wrapper intercepts the spelling --env-file.
• api call syntax is api call [--json] [--dry-run] [--confirm] <tool> '<json>'; there is no api run command.
• exp schema pull needs a TTY for language selection and may only generate definitions for formally defined events, not every ingested custom event.
• exp endpoints is experimental. On 0.8.1, file-run variables can be rejected server-side; validate the exact server behavior before designing parameterized endpoint automation.
• hermes clone has had metadata-transfer gaps; inspect the composed map instead of trusting the success message.
• --no-fail hides command failures from automation. Avoid it in CI and agent workflows.

The full friction-tested list and recovery paths live in references/troubleshooting.md.

Project-local context

If a repo uses PostHog frequently, optionally keep .claude/posthog-cli.local.md (ignored) with non-secret project facts: host, project ID, app surfaces, canonical north-star events, known test accounts, and which products actually receive data. Never place tokens there. A template and live-discovery checklist are in references/project-map.md.

Reference map

Load only what the current job needs:

• references/cli-command-catalog.md — complete 0.8.1 command tree and key flags.
• references/auth-project-scoping.md — install, npm allowScripts, login, direnv, CI scopes, host/project/ingestion-region proof.
• references/api-tools.md — tools/search/info/schema/call, JSON output, dry-run, confirm, skills and AGENTS installer.
• references/analytics-workflows.md — schema-first typed trends/funnels/retention/paths, taxonomy, persons, dashboards, recordings.
• references/hogql.md — exp query, bounded HogQL recipes, system-table/entity search, syntax validation and privacy-safe output.
• references/observability.md — errors, recordings, logs, releases, LLM traces, health investigations and evidence ladders.
• references/product-operations.md — flags, experiments, surveys, insights, dashboards, annotations, cohorts, workflows, mutation safeguards.
• references/endpoints-schema-tasks.md — endpoint YAML lifecycle, typed schema generator, task commands and experimental caveats.
• references/symbolication-releases.md — web/Hermes/dSYM/ProGuard/native symbols, release identity, CI metadata hygiene and round-trip verification.
• references/safety-data-handling.md — PII minimization, shared-state authorization, output shaping and cleanup.
• references/troubleshooting.md — errors observed hands-on and exact recovery paths.
• references/project-map.md — optional per-repo context template and capability matrix.
• references/investigation-playbooks.md — end-to-end playbooks for metric drops, ingestion, setup audits, release health, user journeys, endpoints, and flag rollouts.
• references/sources-versioning.md — source authority, official links, version-sensitive surfaces, and the upgrade re-validation procedure.