The agent-first PostHog CLI.
PostHog power, right in your prompt.

Raw data → dashboard → live survey. One prompt.

Query events with HogQL, manage feature flags, inspect persons and cohorts, debug insights, and operate 31 PostHog resources from your terminal — or from Claude Code, Cursor, and other coding agents. Ships a Claude Code skill that loads at ~200 idle tokens instead of the ~44,000 tokens the PostHog MCP server costs every agent session.

Quickstart

brew install aaronkwhite/tap/bosshogg   # or: cargo install bosshogg
bosshogg configure                       # interactive: host, API key, default project
bosshogg doctor                          # verify setup — all checks green?
bosshogg flag list --active --json | jq '.[0]'

Output:

{
  "id": 12345,
  "key": "checkout-redesign",
  "active": true,
  "rollout_percentage": 25,
  "filters": { "groups": [] }
}

Tip — add a bh shortcut. Symlink is friendliest to subshells and agent loops (which often don't load your shell config):

ln -s "$(command -v bosshogg)" /usr/local/bin/bh   # or anywhere on PATH
# alternative (shells only): echo 'alias bh=bosshogg' >> ~/.zshrc

Then bh flag list, bh query run "SELECT …", etc.

Why BossHogg over the PostHog MCP server?

The PostHog MCP server is excellent for wizard-driven flows and chart rendering in the web UI. For agent loops, the token overhead is the tradeoff:

The idle-token figure for the PostHog MCP server comes from independent benchmarks (including the Scalekit gh-vs-GitHub-MCP 32x benchmark for equivalent surfaces). BossHogg's ~200-token target is based on the skill frontmatter size; actual measurement should be performed before each release.

Built for coding agents

BossHogg ships with a Claude Code skill at .claude/skills/bosshogg/. Instead of loading a 44,000-token tool surface into every session, your agent loads ~200 tokens of frontmatter and pulls reference docs on demand.

> Use bosshogg to find the top 5 events by volume in the last 7 days

The agent calls:

bh query run "SELECT event, count() FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY count() DESC LIMIT 5" --json

And returns the structured result. No web UI hop. No browser. No idle context tax.

MCPs and CLIs are not competitors — they serve different jobs. MCP is great for rich, hosted, chart-rendering workflows. BossHogg is for terminal ops, CI scripts, and the tight agent loops where you want a small, predictable command surface.

What BossHogg does

All 31 GA PostHog resources + 1 nested group (Personal API Key-accessible):

M1 — Core (v2026.4.0)

• HogQL first. bosshogg query run "SELECT ..." — sync or async, auto-LIMIT 100 for safety, file/stdin input, table or JSON output.
• Feature flag management, CRUD-deep. bosshogg flag list / get / create / update / delete — list, toggle, rollout, inspect filters & payloads.
• Agent utilities. bosshogg doctor (preflight health check), bosshogg schema hogql (grounds models on your schema), bosshogg auth token (escape hatch for curl).
• Multi-project, multi-region contexts. US, EU, and self-hosted in one kubectl-style config.

Agent-native output throughout. --json everywhere, stable schemas validated in CI, structured errors {error, code, message, hint, retry_with}, deterministic exit codes (10 auth / 20 not-found / 30 bad-request / 40 rate-limit / 50 upstream / 60 schema-drift / 61 feature-not-available / 70 internal / 71 config).

Cloud and self-hosted. Works against PostHog Cloud (US, EU) out of the box. Self-hosted PostHog is a first-class target: arbitrary host URLs, optional plaintext http:// for internal networks (per-context opt-in via --allow-http or BOSSHOGG_ALLOW_HTTP=1), subpath-aware routing, and bosshogg doctor probes the instance version so you know up front when a Cloud-only paid feature will error cleanly with 61 FEATURE_NOT_AVAILABLE. Self-hosted contexts auto-disable the anonymous self-tracking telemetry — privacy is the whole point.

Safety

Security and data-safety properties baked in from day one:

• HTTPS-only by default. reqwest is configured with .https_only(true) for every Cloud context. Self-hosted users opt into plaintext http:// per-context via --allow-http, the BOSSHOGG_ALLOW_HTTP=1 env var, or by confirming the prompt in bosshogg configure. Every plaintext request emits a tracing::warn! so unsafe deployments are visible in logs.
• Auth redaction. Authorization: headers are stripped from --debug output. Error bodies are truncated to 200 chars. No tokens or PII leak to logs.
• Soft-delete routing. Resources that PostHog soft-deletes (flags, insights, dashboards, cohorts, actions, annotations, hog-functions) are routed through the correct soft-delete path. Hard-delete resources (persons, event-definitions, etc.) are routed correctly and gated on --yes or interactive TTY confirmation.
• HogQL auto-LIMIT. bosshogg query run auto-injects LIMIT 100 when the query has no LIMIT clause. Bypass with --no-limit intentionally. Injection is logged in --debug.
• Snapshot never-stdout. Session recording snapshot blobs are suppressed from stdout by default; use --out <file> to write the full blob.
• --yes gating on destructive ops. Hard deletes and bosshogg capture (which writes to real production data) require --yes or interactive confirmation. No accidental bulk deletions.
• Config file at 0600. ~/.config/bosshogg/config.toml is written with mode(0o600). The configure command probes /api/users/@me/ before persisting the key — failed auth never writes secrets to disk.

Install

Homebrew (macOS / Linux, from v2026.4.0):

brew install aaronkwhite/tap/bosshogg

crates.io:

cargo install bosshogg

GitHub Releases — prebuilt tarballs for x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin are attached to each tag.

From source:

git clone https://github.com/aaronkwhite/bosshogg-cli && cd bosshogg
cargo install --path .

Self-hosted PostHog

bosshogg works against PostHog Cloud (US, EU) and self-hosted instances. Pick the line that matches your setup:

# PostHog Cloud (US is the default — drop --host for US)
bosshogg login --host https://eu.posthog.com

# Self-hosted on https
bosshogg login --host https://posthog.your-domain.com

# Self-hosted on plaintext http (lab / intranet / behind a corp VPN)
bosshogg login --host http://posthog.internal --allow-http

bosshogg login runs PostHog's browser device-flow. If your instance predates /api/cli-auth/device-code/, it'll bail out and tell you to use bosshogg configure to paste a personal API key instead.

A few things to know about self-hosted mode:

• bosshogg doctor runs an instance_version probe (/api/environments/?limit=1, added in PostHog 1.43, mid-2024). Older instances get a warning rather than a hard fail.
• Reverse proxies at a subpath work — pass --host https://analytics.mycorp.com/posthog/ and requests land at /posthog/api/....
• Cloud-only paid features (subscriptions, advanced paths, SSO/RBAC, some batch-export specifics) return exit code 61 FEATURE_NOT_AVAILABLE instead of a confusing 404, with a hint pointing at bosshogg doctor.
• The anonymous usage telemetry that's on by default for Cloud users auto-disables on self-hosted contexts — nothing leaves your network. Confirm with bosshogg config analytics status.
• BOSSHOGG_ALLOW_HTTP=1 is the env-var equivalent of --allow-http if you're scripting in CI. Cloud contexts always require https regardless.

Full setup notes (CI env vars, scope-by-error troubleshooting, region tagging) are in the skill reference.

Positioning

BossHogg is complementary to, not a replacement for, PostHog's first-party tools:

Status & roadmap

v2026.4.10 — 31 GA PostHog resources covered (+ llm-analytics nested group).

v1.0 (v2026.4.0) — M1 through M10 complete.

• 31 GA PostHog resources + 1 nested group (llm-analytics) implemented across milestones M1–M10 (Personal API Key-accessible only).
• ~508 tests (unit + integration via wiremock, JSON contract validation, HogQL smoke tests).
• Claude Code skill with eval set (≥90% pass rate gate on Opus for release).
• Homebrew tap formula. crates.io publication. Prebuilt tarballs for 4 targets.
• Cross-product playbooks: safe rollout, debug a user, conversion drop, ship an event, LLM debug, incident notebook, GDPR deletion.

v1.1 (planned):

• bosshogg auth login — browser-based OAuth token flow.
• bosshogg mcp --stdio — same binary, stdio MCP transport, exposing every bosshogg subcommand as an MCP tool.
• Persistent name→ID cache (XDG cache dir) — in-memory only in v1.
• Keyring integration — plaintext TOML at 0600 is v1; OS keychain v1.1.
• Typed HogQL result rendering — date-column formatting, right-aligned numbers.
• hog-function Hog source editing via $EDITOR.

Documentation

Start with docs/README.md.

• Vision & positioning
• V1 scope
• Capability surface
• Architecture
• JSON & error conventions
• Agent-first design
• Naming decisions
• PostHog API notes
• Glossary
• Development
• Ecosystem integration

Raw research artifacts (API catalog, competitive landscape, schema drafts) live in research/.

Credits

Modeled after the lin CLI playbook — a Rust CLI for Linear's GraphQL API. Thanks to PostHog for an API that's genuinely pleasant to wrap.

License

MIT

PostHog is a registered trademark of PostHog, Inc. BossHogg is an independent community tool and is not affiliated with, endorsed by, or sponsored by PostHog, Inc.