bosshogg 2026.5.3

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
• Why BossHogg over the PostHog MCP server?
• Built for coding agents
• What BossHogg does
• Safety
• Install
• Positioning
• Status & roadmap
• Documentation
• Credits
• License

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.

M2 — Org & project (v2026.4.1)

• bosshogg org — list, get, current, switch.
• bosshogg project — list, get, current, switch, reset-token.

M3 — Analytics backbone (v2026.4.2)

• bosshogg insight — list, get, refresh, create, update, delete (soft), tag, activity, share.
• bosshogg dashboard — list, get, refresh, create, update, delete (soft), share, plus tiles add and tiles remove.
• bosshogg cohort — list, get, create, update, delete (soft), members, add-person, remove-person, calculation-history, activity.

M4 — People & events (v2026.4.3)

• bosshogg person — list, get, delete (hard/GDPR), update-property, delete-property, activity, split.
• bosshogg group — list, find, property-definitions, property-values, related, activity, update-property, delete-property.
• bosshogg event — list (HogQL), get, values, tail (5s-poll loop).
• bosshogg action — list, get, create, update, delete (soft), references, tag.
• bosshogg annotation — list, get, create, update, delete (soft).

M5 — Taxonomy (v2026.4.4)

• bosshogg event-definition — list, get, update, delete, by-name, tag.
• bosshogg property-definition — list, get, update, delete, seen-together, tag.
• bosshogg endpoint — list, get, create, update, delete, run, materialize-preview, materialize-status, openapi.

M6 — Growth primitives (v2026.4.5)

• bosshogg experiment — list, get, create, update, delete, archive, duplicate, copy-to-project, create-exposure-cohort, launch, end, pause, resume, reset, ship-variant, recalculate-timeseries, results.
• bosshogg survey — list, get, create, update, delete, activity, duplicate, archive-response, stats, project-stats, responses-count, project-activity, summarize.
• bosshogg early-access — list, get, create, update, delete.
• bosshogg query ai-costs — per-model LLM cost aggregate from $ai_generation events (default 30d window).

M7 — CDP pipeline (v2026.4.6)

• bosshogg hog-function — list, get, create, update, delete (soft), enable, disable, invoke, logs, metrics, enable-backfills.
• bosshogg batch-export — list, get, create, update, delete, pause, unpause, plus nested backfills and runs.

M8 — Ops & debug (v2026.4.7)

• bosshogg session-recording — list, get (snapshot blob written to --out file, never stdout), update, delete.
• bosshogg error-tracking — nested fingerprints, assignment-rules, grouping-rules, issues (list, get, activity, activity-list, assign, cohort, merge, split, bulk), releases (list, get, by-hash), symbol-sets (list, get, download, start-upload, finish-upload, bulk-delete, bulk-start-upload, bulk-finish-upload), plus resolve-github / resolve-gitlab.
• bosshogg role — Enterprise RBAC, list/get/create/update/delete, plus member management.
• bosshogg capture — event / batch / identify via the public ingest endpoint (uses project token, gated on --yes).

M9 — v1.x candidates (v2026.4.6)

• bosshogg alert — list, get, create, update, delete. Insight-threshold monitors.
• bosshogg dashboard-template — list, get, create, use (instantiate a dashboard from a template).
• bosshogg session-recording-playlist — list, get, create, update, delete, recordings, add-recording, remove-recording.
• bosshogg insight-variable — list, get, create, update, delete. Templated HogQL variables.

M10 — Deep LLM analytics (v2026.4.8)

• bosshogg dataset — list, get, create, update, delete. Eval datasets at /api/projects/{proj}/datasets/.
• bosshogg dataset-item — list (with optional --dataset filter), get, create, update, delete. Input/output pairs for evaluation datasets.
• bosshogg evaluation — list, get, test-hog. test-hog runs Hog evaluation code against recent $ai_generation events and returns pass/fail results synchronously.
• bosshogg llm-analytics — nested group with 5 sub-resources:
  • models list — available LLM models for the configured provider.
  • evaluation-summary — AI-powered summary of evaluation results (pass/fail patterns + recommendations).
  • evaluation-reports — CRUD + generate (async trigger) + runs (history). 7 verbs.
  • provider-keys — list, get, validate (read + validate only; write paths deferred).
  • review-queue list — LLM analytics review queue items.

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.