Every PostHog resource in one CLI — with offline search, agent-native output, and cross-resource analytics no dashboard can do.
posthog-pp-cli syncs your flags, insights, experiments, persons, errors, and LLM traces to a local SQLite store. Query anything offline, run compound analytics across resources the UI keeps separate, and pipe results directly to agents or scripts.
Authentication
Uses your PostHog personal API key (phx_...). Set POSTHOG_API_KEY or run posthog-pp-cli auth set-token. Supports both US (app.posthog.com) and EU (eu.posthog.com) instances via POSTHOG_HOST.
Quick Start
# Connect to your PostHog instance with your personal API key
posthog-pp-cli auth set-token
# Sync flags, insights, experiments, persons, and errors to local store
posthog-pp-cli sync --full
# List all feature flags with rollout rules
posthog-pp-cli flags list --json
# Run HogQL to see your top events
posthog-pp-cli query run --sql "SELECT event, count() FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY count() DESC LIMIT 20"
# Find everything that references a flag before archiving
posthog-pp-cli flags blast-radius my-checkout-v2
Unique Features
These capabilities aren't available in any other tool for this API.
Flag safety
-
flags blast-radius — Find every insight, dashboard, experiment, and survey that references a flag before you archive or rename it.
Use before archiving or renaming a flag to prevent breaking dashboards and experiments silently.
posthog-pp-cli flags blast-radius --key my-checkout-v2 --json
-
flags rollout-health — Go/no-go confidence for a flag ramp — error rate and key metric movement correlated with flag exposure.
Use before ramping a flag to 100% to catch regressions that aren't visible in overall metrics.
posthog-pp-cli flags rollout-health --key new-checkout --window 24h --agent
-
flags stale — List flags that haven't been evaluated in N days — cleanup candidates before they accumulate.
Use in quarterly flag cleanup sprints to identify dead code paths safely.
posthog-pp-cli flags stale --days 30 --json
LLM observability
-
llm cost-attribution — Break down LLM spend by feature flag variant — see whether the expensive model variant pays for itself.
Use when evaluating whether to promote a more expensive LLM variant based on actual cost-per-conversion.
posthog-pp-cli llm cost-attribution --flag model-tier --agent
Local state that compounds
-
persons at-risk — Surface which users in a cohort are going quiet and recently hit errors — before they churn.
Use in weekly retention reviews to prioritize proactive outreach before churn events.
posthog-pp-cli persons at-risk --cohort paying-users --silent-days 14 --json
-
events property-drift — Catch tracking regressions — properties that silently disappeared from an event between two time windows.
Use after a deploy to catch silent schema changes that corrupt ongoing experiments and dashboards.
posthog-pp-cli events property-drift --event checkout_completed --agent
-
experiments pre-check — Know today whether an experiment will reach significance this sprint, or needs traffic adjustment now.
Use at the start of each sprint to surface experiments that need traffic changes before they run out of time.
posthog-pp-cli experiments pre-check --agent
-
dashboard health — Find broken dashboards before a stakeholder meeting does — stale data, deleted cohorts, archived flags.
Use before weekly business reviews to catch broken insight tiles that would embarrass the data team.
posthog-pp-cli dashboard health --stale-days 7 --agent
Usage
Run posthog-pp-cli --help for the full command reference and flag list.
Recipes — Novel Features
These compound commands exist nowhere else. Each wraps multiple API calls into a single actionable answer.
Before archiving a flag
# Find every insight, dashboard, experiment, and survey referencing a flag
posthog-pp-cli flags blast-radius my-flag --project 12345
# Go/no-go signal before ramping to 100%
posthog-pp-cli flags rollout-health my-flag --project 12345
Quarterly flag cleanup
posthog-pp-cli flags stale --project 12345 --days 60 --json
Before a stakeholder meeting
posthog-pp-cli dashboard health --project 12345
Sprint planning
posthog-pp-cli experiments pre-check --project 12345 --sprint-days 14
Retention review
posthog-pp-cli persons at-risk --project 12345 --silent-days 14 --json
After a deploy
posthog-pp-cli events property-drift '$pageview' --project 12345
LLM cost visibility
posthog-pp-cli llm cost-attribution --project 12345 --flag my-model-flag
Commands
code
Manage code
posthog-pp-cli code invites-check-access-retrieve - Check whether the authenticated user has access to PostHog Code.posthog-pp-cli code invites-redeem-create - Redeem a PostHog Code invite code to enable access.
environments
Manage environments
organizations
Manage organizations
posthog-pp-cli organizations create - Createposthog-pp-cli organizations destroy - Destroyposthog-pp-cli organizations list - Listposthog-pp-cli organizations partial-update - Partial updateposthog-pp-cli organizations retrieve - Retrieveposthog-pp-cli organizations update - Update
projects
Manage projects
public-hog-function-templates
Manage public hog function templates
posthog-pp-cli public-hog-function-templates list - List
user-home-settings
Manage user home settings
posthog-pp-cli user-home-settings partial-update - Update the authenticated user's pinned sidebar tabs and/or homepage for the current team. Pass @me as the UUID. Send tabs to replace the pinned tab list, homepage to set the home destination (any PostHog URL — dashboard, insight, search results, scene). Either field may be omitted to leave it unchanged; sending homepage: null or {} clears the homepage.posthog-pp-cli user-home-settings retrieve - Get the authenticated user's pinned sidebar tabs and configured homepage for the current team. Pass @me as the UUID.
users
Manage users
posthog-pp-cli users cancel-email-change-request-partial-update - Cancel email change request partial updateposthog-pp-cli users destroy - Destroyposthog-pp-cli users list - Listposthog-pp-cli users partial-update - Update one or more of the authenticated user's profile fields or settings.posthog-pp-cli users request-email-verification-create - Request email verification createposthog-pp-cli users retrieve - Retrieve a user's profile and settings. Pass @me as the UUID to fetch the authenticated user; non-staff callers may only access their own account.posthog-pp-cli users update - Replace the authenticated user's profile and settings. Pass @me as the UUID to update the authenticated user. Prefer the PATCH endpoint for partial updates — PUT requires every writable field to be provided.posthog-pp-cli users verify-email-create - Verify email create
Output Formats
# Human-readable table (default in terminal, JSON when piped)
posthog-pp-cli organizations list
# JSON for scripting and agents
posthog-pp-cli organizations list --json
# Filter to specific fields
posthog-pp-cli organizations list --json --select id,name,status
# Dry run — show the request without sending
posthog-pp-cli organizations list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
posthog-pp-cli organizations list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
posthog-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/posthog-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
POSTHOG_PERSONAL_APIKEY_AUTH | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
posthog-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $POSTHOG_PERSONAL_APIKEY_AUTH
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized — Run
posthog-pp-cli auth set-token and paste your phx_ personal API key (not the project token)
- Empty results after sync — Check your project ID:
posthog-pp-cli projects list — then set POSTHOG_PROJECT_ID
- EU instance not connecting — Set POSTHOG_HOST=https://eu.posthog.com and re-run sync
- Query rate limit (429) — PostHog limits analytics queries to 240/min. Add --delay 500 flag or reduce query frequency
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press