agent-posthog

PostHog analytics CLI for AI agents

Language: Go
Version: 0.1.1
License: MIT
Category: CLI Tool

A PostHog product analytics CLI designed for read-heavy investigation workflows where AI agents need compact structured output, actionable error hints, and no direct access to PostHog secrets.

Features

Keychain-first credentials — personal API keys are never printed back

Multi-profile support — profiles carry host plus default organization, project, and environment IDs

LLM-shaped output — lists and queries default to NDJSON, single resources to JSON

Structured errors — stderr JSON includes fixable_by: agent|human|retry

PostHog investigation workflows — organizations, projects, environments, event schema, HogQL, and feature flags

Mock server — mockposthog provides deterministic E2E fixtures

Agent onboarding — ships with a bundled agent-posthog skill

Single compiled Go binary — no runtime dependencies

Install

Homebrew

$ brew install shhac/tap/agent-posthog

AI Agent Skill

$ npx skills add shhac/agent-posthog

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-posthog/releases/latest/download/agent-posthog-darwin-arm64.tar.gz | tar xz

Go Install

$ go install github.com/shhac/agent-posthog/cmd/agent-posthog@latest

Build from Source

$ git clone https://github.com/shhac/agent-posthog.git && cd agent-posthog && make build

Getting Started

agent-posthog needs a PostHog personal API key before it can inspect analytics data. Store credentials in a named profile so agents can reference the profile without seeing the secret.

01 · Add a PostHog profile

$ agent-posthog auth add prod --form --host https://us.posthog.com

With --form, a native OS dialog asks for the API key and the CLI returns only a redacted receipt.

02 · Check credentials

$ agent-posthog auth check prod

03 · Set default scope

$ agent-posthog auth update prod --org <org-id> --project <project-id> --env <env-id> --default

Use orgs list, projects list, and environments list to discover IDs before setting defaults.

Usage

>_ List organizations

$ agent-posthog orgs list

>_ List projects

$ agent-posthog projects list --org <org-id>

>_ List environments

$ agent-posthog environments list --project <project-id>

>_ Search event schema

$ agent-posthog schema events list --search signup

>_ Run a HogQL query

$ agent-posthog query hogql "select event, count() from events group by event order by count() desc limit 20"

>_ Inspect a feature flag

$ agent-posthog flags get checkout-v2