Posthog CLI

Manage PostHog product analytics from the terminal. Use when the user asks about PostHog analytics, feature flags, experiments, surveys, dashboards, insights...

Security Scan

The skill is internally consistent: it documents a community PostHog CLI, asks for only the PostHog credentials/config you'd expect, and is instruction-only (no hidden installs or unrelated requirements).

Purpose & Capability

Name/description match the commands and capabilities in SKILL.md and references/commands.md. The env vars and host/credential patterns mentioned are appropriate for a PostHog CLI.

Instruction Scope

Runtime instructions are limited to installing and using the posthog CLI, authenticating to PostHog, selecting projects, running queries, and using the raw API escape hatch. The instructions do not direct the agent to read unrelated system files or exfiltrate data to third-party endpoints. It does note config stored in the user home directory (expected for a CLI).

Install Mechanism

This is an instruction-only skill (no platform install spec). SKILL.md recommends installing via pip (pip install phog-cli) which is a common mechanism but carries normal supply-chain risk for third-party PyPI packages — the skill itself does not automatically install anything on the user's system.

Credentials

Environment variables the docs mention (POSTHOG_API_KEY, POSTHOG_HOST, POSTHOG_PROJECT_ID) are directly relevant to accessing PostHog. There are no unrelated secrets or broad credential requests.

Persistence & Privilege

The skill does not request permanent platform presence (always is false) and does not instruct modification of other skills or global agent configuration. It mentions storing CLI config under the user home directory which is typical for a CLI.

Assessment

This skill appears to be what it says: documentation for a community PostHog CLI. Before installing or using it, verify the pip package and upstream repository (the SKILL.md lists a GitHub repo) and prefer a pinned version. Use a minimally scoped API key for automation, store credentials with proper file permissions, and avoid using highly privileged account keys. Be cautious when using --yes in scripts (it suppresses confirmations) and with --json output if you plan to persist or transmit results that may contain PII; review the CLI's config file location (~/.config or similar) to ensure it does not leak keys to other processes. If you need stronger assurance, review the package source on GitHub (or the PyPI release) before pip installing.

PostHog CLI (phog-cli)

A community-built CLI for PostHog product analytics. Not affiliated with PostHog Inc.

Installation

pip install phog-cli

The CLI command is posthog. Verify with posthog --version.

Authentication

Check if already authenticated, then login if needed:

posthog auth status
posthog auth login          # auto-detects US/EU cloud

For self-hosted: posthog auth login --host https://posthog.company.com

For non-interactive/CI use, set environment variables instead:

export POSTHOG_API_KEY="phx_..."
export POSTHOG_HOST="https://us.posthog.com"
export POSTHOG_PROJECT_ID="12345"

Project Selection

Most commands need an active project:

posthog project list
posthog project switch <project-id>
posthog project current

Global Flags

Use with ANY command:

• --json / -j — Machine-readable JSON output. Always use this when parsing output programmatically.
• --yes / -y — Skip confirmation prompts. Always use this for non-interactive automation.
• --help — Show help for any command.

Quick Reference

Command	What it does
posthog activity summary	Full product health report (WAU, events, traffic, pages, browsers)
posthog activity users	Active users over time (daily/weekly/monthly)
posthog activity events	Top events by volume
posthog flag list	List feature flags
posthog flag create --key KEY --name NAME	Create a feature flag
posthog experiment list	List A/B experiments
posthog experiment results ID	View experiment results
posthog survey list	List surveys
posthog dashboard list	List dashboards
posthog insight list	List saved insights
posthog insight query ID	Execute a saved insight's query
posthog error list	List error tracking issues
posthog log query	Query logs
posthog query run --hogql "SQL"	Run a HogQL query
posthog query generate "question"	Generate HogQL from natural language
posthog search persons --search "email"	Search persons
posthog api get /path/	Raw API escape hatch

For detailed command options, see references/commands.md.

Common Workflows

Product Health Check

posthog --json activity summary --date-from -30d

Returns WAU trends, all custom events with unique user counts, weekly trend breakdowns, traffic sources, top pages, and browser stats in a single call.

Custom Analytics with HogQL

HogQL is a SQL-like language for querying PostHog data.

# Count distinct users for a specific event
posthog query run --hogql "SELECT count(distinct person_id) FROM events WHERE event = 'purchase' AND timestamp > now() - interval 30 day"

# Weekly trends
posthog query run --hogql "SELECT toStartOfWeek(timestamp) as week, count() as c FROM events WHERE event = 'signup' AND timestamp > now() - interval 90 day GROUP BY week ORDER BY week"

# Traffic sources
posthog query run --hogql "SELECT properties.\$referring_domain as source, count(distinct person_id) as users FROM events WHERE event = '\$pageview' AND timestamp > now() - interval 30 day AND properties.\$referring_domain IS NOT NULL AND properties.\$referring_domain != '' GROUP BY source ORDER BY users DESC LIMIT 10"

# Funnel conversion
posthog query run --hogql "SELECT count(distinct person_id) as started, countIf(distinct person_id, person_id IN (SELECT distinct person_id FROM events WHERE event = 'purchase' AND timestamp > now() - interval 30 day)) as converted FROM events WHERE event = 'add_to_cart' AND timestamp > now() - interval 30 day"

HogQL essentials:

• Events table: events — columns: event, timestamp, person_id, properties
• Access properties: properties.$current_url, properties.$browser, properties.$referring_domain
• System events are $-prefixed: $pageview, $pageleave, $autocapture, $set
• Custom events have no prefix: purchase, signup, file_upload
• Time: now(), toStartOfWeek(timestamp), toStartOfMonth(timestamp)
• Distinct users: count(distinct person_id)

Feature Flag Rollout

posthog flag create --key new-feature --name "New Feature" --rollout-percentage 10
posthog flag update <id> --rollout-percentage 50
posthog flag update <id> --rollout-percentage 100

Run an Experiment

posthog experiment create --name "CTA Test" --feature-flag-key cta-test
posthog experiment update <id> --launch
posthog experiment results <id> --refresh
posthog experiment update <id> --end

Raw API Escape Hatch

For anything the CLI doesn't cover:

posthog api get /path/
posthog api post /path/ --data '{"key": "value"}'
posthog api patch /path/ --data '{"key": "value"}'
posthog api delete /path/

Error Handling

• API error 401 — Invalid credentials. Run posthog auth login.
• API error 404 — Resource not found or wrong endpoint path.
• No active project — Run posthog project list then posthog project switch <id>.
• All errors exit with code 1 and print to stderr.

Notes

• This is a community-built CLI (pip install phog-cli), not an official PostHog product.
• PostHog has US (us.posthog.com) and EU (eu.posthog.com) cloud regions — the CLI auto-detects on login.
• Config stored at ~/.config/posthog-cli/config.json (600 permissions).
• Environment variables override config: POSTHOG_API_KEY, POSTHOG_HOST, POSTHOG_PROJECT_ID.