:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
hog
hog is the PostHog command line, version 1. Read README.md for what it does and how to run it.
Layout
| Path | Holds |
|---|---|
src/commands/ |
One file per command. index.ts is the tree of every command; legacy.ts holds the ones posthog-cli still owns |
src/core/ |
The shared parts every command uses: command definitions, context and global options, output, agent detection, errors, runtime, the manifest |
src/posthog/ |
The PostHog API client, the pagination helpers every list uses, and credentials |
src/error-tracking/ |
Symbol upload: discovery, artifact types under kinds/, the container and content hash, releases, git, the upload protocol, and run.ts, the inject and upload steps the commands share |
src/endpoints/ |
The endpoint YAML files, how they compare with PostHog, and the push and pull plans |
test/parity/ |
Goldens recorded from posthog-cli and the tests that hold hog to them. Read its README before changing anything that reaches an upload |
src/cli.ts |
Turns the command tree into a commander program, runs it, and maps errors to exit codes |
src/testing.ts |
runHog and a fake runtime, so tests run the real CLI without a process or a network |
Import from another folder with @/, which tsconfig.json maps to src/, as in import { defineCommand } from '@/core/command'. Use ./ only inside the same folder.
Add a command
- Write
src/commands/<group>/<name>.tswithdefineCommand. Put it in adefineGroupwhen it has siblings. - Add it to the tree in
src/commands/index.ts, and remove itsdefineLegacyentry fromsrc/commands/legacy.tsif posthog-cli has one. A legacy entry can sit inside a group, so a group can be half ported. - Add cases to
src/commands/<group>/<group>.test.tswithrunHog.
export default defineCommand({
description: 'List the feature flags in your project',
args: { search: { description: 'Only show flags whose key contains this text', optional: true } },
options: {
limit: {
type: 'string',
placeholder: 'count',
parse: parseLimit,
description: 'How many flags to show, up to 1000',
},
offset: { type: 'string', placeholder: 'count', parse: parseOffset, description: 'How many flags to skip' },
},
scopes: ['feature_flag:read'],
examples: ['hog flags list checkout'],
async run({ args, options, ctx }) {
const query = new URLSearchParams({
search: args.search ?? '',
limit: String(options.limit ?? 100),
offset: String(options.offset ?? 0),
})
const page = await getPage(await ctx.posthog(), `feature_flags/?${query}`, Flag)
return { flags: page.results, nextOffset: nextOffset(page) }
},
human({ result, out }) {
out.table(
['key', 'active'],
result.flags.map((flag) => [flag.key, flag.active])
)
if (result.nextOffset !== null) {
out.line(`Run ${out.style(`hog flags list --offset ${result.nextOffset}`, 'bold')} for the next page.`)
}
},
agent({ result, out }) {
out.json(result)
},
})
Rules
runreturns data and never prints.humandecides what a person at a terminal sees, andagentdecides what agents, pipes and-o jsonsee. Without them, people get indented JSON and agents get one line of JSON.- Agent output is JSON only, on stdout, with no color and no prose. Prefer
out.jsonLinesfor rows a command reads in one go, like query results, so an agent can stream them. A paged list prints one JSON object, so it can carry the next offset. - A command never reads a whole PostHog list. A list command reads one page per run with
getPagefromsrc/posthog/pagination.ts. It takes--limitand the option that picks a page in that endpoint's DRF paginator, such as--offset. Its human output names the command for the next page, and its agent output has the next offset as a field. A command that needs particular items from a list usesfindNamed, which stops when it has them. Only a command whose purpose is the whole list, likehog endpoints pull --all, usesreadAll. Both stop atMAX_PAGES. out.tablecolors each column by kind (number, date, boolean, JSON) and fits the terminal width. Pass akindwhen the API declares column types, ashog query rundoes with ClickHouse types. Otherwise the kind comes from the values.- A failure throws a
HogErrorwith a stablecodeand ahintthat names the next step.cli.tsprints it as text or as JSON on stderr. Do not catch errors to print them yourself. - Ask questions only through
ctx.prompts. It is undefined for agents, pipes and-o json, so a command that needs an answer must take it as an option there, or fail with a hint that names the option. Never block an agent on a person: split the work into a call that returns at once and a call that finishes it, likehog auth loginandhog auth login --wait. A command that waits for a person to approve something in a browser usesrunApprovalandresumeApprovalfromsrc/core/approval.ts, so every such command starts, waits and resumes the same way. exitCodeis for results that are not failures but that a script must branch on, likehog query checkfinding errors.--rawis global: it prints the result ofrunas JSON and skips both views. A command whose result is a trimmed view of a PostHog answer, likehog query run, keeps the whole answer in it and returns that fromraw. Do not add per-command--rawor--debugflags; return enough data fromruninstead.- An argument with
stdin: truereads stdin when the caller passes-, and fails when it is empty.hog commandstells agents which arguments accept it. - Data that enters hog, such as flags, env vars, files, keychain items and answers from PostHog, is parsed into a typed value at the boundary with a zod schema. It is not checked and then passed on as a plain string. A branded value, such as a
Host, aProjectIdor a token kind, comes only from its factory, such asparseHostorparseProjectId. Semgrep blocksJSON.parseoutsidesrc/core/json.tsand a cast to a brand outside the module that defines it (.semgrep/rules/devex/hog-typed-boundaries.yaml). - Commands reach the outside world only through
ctx(ctx.posthog(),ctx.runtime), so tests can fake it. Do not readprocessor callfetchdirectly. - Import heavy dependencies inside
runwithawait import(). Every command module loads on every call, so a top-level import of a large library slows down all commands. - Declare
scopes.hog commandslists them for agents, and a 403 names them in its hint. hog error-trackingmust upload the same bytes, content hashes and requests as posthog-cli, or re-uploads fail withcontent_hash_mismatch. A change to anything that reaches an upload keepstest/parity/green, and a new artifact type or flag adds parity scenarios recorded from posthog-cli.- Code under
src/error-tracking/reads build output withnode:fsdirectly, because it walks real folders. Its tests use temporary folders instead ofctx.runtimefiles. - Every string a person reads follows
/writing-user-facing-copy: sentence case, no em dashes.