Skip to content

: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.

chore(hog): scaffold the hog cli and hand cli and hog to team-growth (#124303)

Rafael Audiberta0651f6c8a57
diff --git a/.github/scripts/trunk-impacted-targets.js b/.github/scripts/trunk-impacted-targets.js
index 96604288de77..a5e3dc42d4b1 100644
--- a/.github/scripts/trunk-impacted-targets.js
+++ b/.github/scripts/trunk-impacted-targets.js
@@ -841,6 +841,8 @@ const STANDALONE_TREES = new Map([
// the pnpm workspace). ci-cli.yml also builds it from services/mcp sources,
// so the two trees have to share a lane.
['cli', ['cli', 'svc:mcp']],
+ // The TypeScript successor to cli/. Nothing outside it builds or imports it.
+ ['hog', ['hog']],
// Go service with its own CI. ci-hoglang.yml ignores livestream/** explicitly,
// so its Hog implementation is not covered by the shared HogLang suite either.
['livestream', ['livestream']],
diff --git a/AGENTS.md b/AGENTS.md
index a3a750ccae60..10e762fca959 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -172,7 +172,7 @@ Each rule is tagged with what catches a violation.
- **Keep entrypoints thin.** `[review]` The runtime calls the entrypoint first: a DRF view, a management command `handle()`, a Celery task body, an HTTP handler, a Rust `main()`, a React component. An entrypoint reads the input, connects the dependencies, and formats the output. All other logic goes in a function the entrypoint calls, so a test can call it directly. If the area already has a place for that logic, use it rather than making a new one.
- **A product under `products/` is scaffolded, not hand-rolled.** `[lint: hogli product:lint --all]` Create one with `hogli product:bootstrap <name>`, because the scaffold emits a product that is isolated from its first commit. See "New products must be isolated" in [products/README.md](products/README.md) for the isolation rules, and [products/architecture.md](products/architecture.md) for facade and contract design.
-- **Code a single product owns belongs under `products/<product>/`** — backend, frontend, scripts, CLIs, services, packages, MCP tools, skills. `[review]` Reserve top-level `tools/`, `services/`, `packages/` and `cli/` for cross-product things. `product:lint` only scans `products/`, so a single-product feature parked in a top-level directory is invisible to it.
+- **Code a single product owns belongs under `products/<product>/`** — backend, frontend, scripts, CLIs, services, packages, MCP tools, skills. `[review]` Reserve top-level `tools/`, `services/`, `packages/`, `cli/` and `hog/` for cross-product things. `product:lint` only scans `products/`, so a single-product feature parked in a top-level directory is invisible to it.
### Tenancy and scoping
diff --git a/docs/internal/monorepo-layout.md b/docs/internal/monorepo-layout.md
index e147cd90a174..d06700628eb2 100644
--- a/docs/internal/monorepo-layout.md
+++ b/docs/internal/monorepo-layout.md
@@ -39,6 +39,9 @@ tools/ # Developer/CI tooling
hogli/ # Developer CLI framework (PyPI-publishable; uv workspace member)
hogli-commands/ # PostHog-specific hogli commands (consumed via hogli.yaml)
+cli/ # posthog-cli v0: the Rust CLI for symbol uploads and agent API tools, being replaced by hog/
+hog/ # hog v1: the TypeScript PostHog CLI, successor to cli/
+
devenv/ # Developer environment config (intent map, process model)
```
@@ -83,7 +86,7 @@ Most products are a Django app plus React scenes — and most already carry more
- `products/<product>/packages/<lib>/` — a library or CLI the product owns
- dev/CI/backfill scripts, benchmarks, audits, fixtures and dummy-data generators, a standalone console — same idea
-Top-level `services/`, `packages/`, `tools/`, and `cli/` are for things no single product owns. Keep package names (`@posthog/<name>`) independent of location — pnpm resolves by name, so relocating later is a path move with no import churn.
+Top-level `services/`, `packages/`, `tools/`, `cli/`, and `hog/` are for things no single product owns. Keep package names (`@posthog/<name>`) independent of location — pnpm resolves by name, so relocating later is a path move with no import churn.
Nest because tooling boundaries become path-scoped (`products/<product>/**` for CODEOWNERS, CI filters, lint) instead of hand-synced `<product>-*` prefixes. A prefix doing a folder's job is the signal to nest.
diff --git a/hog/.gitignore b/hog/.gitignore
new file mode 100644
index 000000000000..849ddff3b7ec
--- /dev/null
+++ b/hog/.gitignore
@@ -0,0 +1 @@
+dist/
diff --git a/hog/README.md b/hog/README.md
new file mode 100644
index 000000000000..becee42bf302
--- /dev/null
+++ b/hog/README.md
@@ -0,0 +1,25 @@
+# hog
+
+`hog` is the PostHog command line, version 1.
+It replaces `posthog-cli` (version 0, in `cli/`), which keeps working until `hog` covers everything it does.
+
+`hog` is written in TypeScript and compiles to a single binary with [Bun](https://bun.sh).
+It is not published yet.
+
+## Commands
+
+`hog` has no `exp` namespace.
+The commands `posthog-cli` keeps under `exp` (`query`, `endpoints`, `logs`, `tasks`, `schema`) are top-level commands in `hog`.
+Every command fails until it is implemented.
+It exits with code 1 and prints the `posthog-cli` command to run instead, with the same arguments.
+
+## Develop
+
+Install [Bun](https://bun.sh), then from the repo root:
+
+```bash
+pnpm --filter @posthog/hog hog --help # run hog from source
+pnpm --filter @posthog/hog unit # run the tests
+pnpm --filter @posthog/hog typecheck # check types
+pnpm --filter @posthog/hog compile # build dist/hog for this machine
+```
diff --git a/hog/package.json b/hog/package.json
new file mode 100644
index 000000000000..e425849b73cc
--- /dev/null
+++ b/hog/package.json
@@ -0,0 +1,20 @@
+{
+ "name": "@posthog/hog",
+ "version": "1.0.0-alpha.0",
+ "private": true,
+ "description": "hog, the PostHog command line. Successor to posthog-cli in cli/",
+ "bin": {
+ "hog": "./src/index.ts"
+ },
+ "type": "module",
+ "scripts": {
+ "hog": "bun src/index.ts",
+ "compile": "bun build --compile src/index.ts --outfile dist/hog",
+ "typecheck": "tsc --noEmit",
+ "unit": "bun test"
+ },
+ "devDependencies": {
+ "@types/bun": "1.3.14",
+ "typescript": "catalog:"
+ }
+}
diff --git a/hog/src/cli.test.ts b/hog/src/cli.test.ts
new file mode 100644
index 000000000000..f6d2470df096
--- /dev/null
+++ b/hog/src/cli.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test'
+
+import pkg from '../package.json' with { type: 'json' }
+import { run } from './cli'
+import { COMMANDS } from './commands'
+
+function capture(argv: readonly string[]): { code: number; stdout: string; stderr: string } {
+ let stdout = ''
+ let stderr = ''
+ const code = run(argv, {
+ stdout: (text) => (stdout += text),
+ stderr: (text) => (stderr += text),
+ })
+ return { code, stdout, stderr }
+}
+
+describe('hog', () => {
+ test.each([
+ ['no arguments prints help', [], 0, 'Usage: hog <command>', ''],
+ ['--version prints the version', ['--version'], 0, pkg.version, ''],
+ ['an unknown command fails', ['nope'], 1, '', 'Unknown command: nope'],
+ [
+ 'an unported command passes its arguments to posthog-cli, quoted',
+ ['query', 'run', "select 'a' from events"],
+ 1,
+ '',
+ `posthog-cli exp query run 'select '\\''a'\\'' from events'`,
+ ],
+ [
+ 'help for an unported command points to its posthog-cli help',
+ ['help', 'dsym', 'upload'],
+ 1,
+ '',
+ 'posthog-cli dsym upload --help',
+ ],
+ ] as const)('%s', (_name, argv, code, stdout, stderr) => {
+ const result = capture(argv)
+ expect(result.code).toBe(code)
+ expect(result.stdout).toContain(stdout)
+ expect(result.stderr).toContain(stderr)
+ })
+
+ test.each(COMMANDS.map((command) => [command.name, command.legacyCommand]))(
+ '%s fails and points to %s',
+ (name, legacyCommand) => {
+ const result = capture([name, '--some-flag'])
+ expect(result.code).toBe(1)
+ expect(result.stdout).toBe('')
+ expect(result.stderr).toContain(`${legacyCommand} --some-flag`)
+ }
+ )
+})
diff --git a/hog/src/cli.ts b/hog/src/cli.ts
new file mode 100644
index 000000000000..b16e69813dab
--- /dev/null
+++ b/hog/src/cli.ts
@@ -0,0 +1,58 @@
+import pkg from '../package.json' with { type: 'json' }
+import { COMMANDS } from './commands'
+
+export interface Output {
+ stdout: (text: string) => void
+ stderr: (text: string) => void
+}
+
+const HELP_FLAGS = new Set(['-h', '--help', 'help'])
+const VERSION_FLAGS = new Set(['-V', '--version'])
+const SHELL_SAFE_ARG = /^[\w@%+=:,./-]+$/
+
+export function shellQuote(arg: string): string {
+ return SHELL_SAFE_ARG.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`
+}
+
+export function helpText(): string {
+ const width = Math.max(...COMMANDS.map((command) => command.name.length)) + 2
+ const commandLines = COMMANDS.map((command) => ` ${command.name.padEnd(width)}${command.summary}`)
+ return [
+ `hog ${pkg.version}`,
+ 'The PostHog command line',
+ '',
+ 'Usage: hog <command> [options]',
+ '',
+ 'Commands:',
+ ...commandLines,
+ '',
+ 'Options:',
+ ' -h, --help Show this help',
+ ' -V, --version Show the version',
+ ].join('\n')
+}
+
+export function run(argv: readonly string[], output: Output): number {
+ const [first, ...rest] = argv
+ const [helpTarget, ...helpRest] = rest
+ if (first === undefined || (HELP_FLAGS.has(first) && helpTarget === undefined)) {
+ output.stdout(helpText())
+ return 0
+ }
+ if (VERSION_FLAGS.has(first)) {
+ output.stdout(pkg.version)
+ return 0
+ }
+
+ // `hog help <command>` asks for that command's own help, which only posthog-cli has today.
+ const name = first === 'help' && helpTarget !== undefined ? helpTarget : first
+ const args = first === 'help' && helpTarget !== undefined ? [...helpRest, '--help'] : rest
+ const command = COMMANDS.find((candidate) => candidate.name === name)
+ if (!command) {
+ output.stderr(`Unknown command: ${name}. Run \`hog --help\` to see the available commands.`)
+ return 1
+ }
+ const legacyInvocation = [command.legacyCommand, ...args.map(shellQuote)].join(' ')
+ output.stderr(`\`hog ${command.name}\` isn't available yet. Run this instead:\n ${legacyInvocation}`)
+ return 1
+}
diff --git a/hog/src/commands.ts b/hog/src/commands.ts
new file mode 100644
index 000000000000..77a26269bcad
--- /dev/null
+++ b/hog/src/commands.ts
@@ -0,0 +1,43 @@
+export interface CommandSpec {
+ name: string
+ summary: string
+ // The posthog-cli invocation that covers this command until hog implements it.
+ legacyCommand: string
+}
+
+export const COMMANDS: readonly CommandSpec[] = [
+ {
+ name: 'login',
+ summary: 'Log in to PostHog and store a personal API key on this machine',
+ legacyCommand: 'posthog-cli login',
+ },
+ { name: 'api', summary: 'Agent-first PostHog API tools', legacyCommand: 'posthog-cli api' },
+ { name: 'query', summary: 'Run and check SQL queries', legacyCommand: 'posthog-cli exp query' },
+ { name: 'endpoints', summary: 'Manage PostHog endpoints', legacyCommand: 'posthog-cli exp endpoints' },
+ {
+ name: 'logs',
+ summary: 'Import historical logs from another log store into PostHog',
+ legacyCommand: 'posthog-cli exp logs',
+ },
+ { name: 'tasks', summary: 'List, track and update PostHog tasks', legacyCommand: 'posthog-cli exp task' },
+ {
+ name: 'schema',
+ summary: 'Download event definitions and generate a typed SDK',
+ legacyCommand: 'posthog-cli exp schema',
+ },
+ {
+ name: 'sourcemap',
+ summary: 'Inject chunk IDs into bundles and upload their sourcemaps',
+ legacyCommand: 'posthog-cli sourcemap',
+ },
+ { name: 'hermes', summary: 'Upload Hermes sourcemaps to PostHog', legacyCommand: 'posthog-cli hermes' },
+ { name: 'dsym', summary: 'Upload Apple dSYM debug symbol files to PostHog', legacyCommand: 'posthog-cli dsym' },
+ { name: 'proguard', summary: 'Upload ProGuard mapping files to PostHog', legacyCommand: 'posthog-cli proguard' },
+ {
+ name: 'symbol-sets',
+ summary: 'Upload, download, and manage symbol sets',
+ legacyCommand: 'posthog-cli symbol-sets',
+ },
+ { name: 'release', summary: 'Look up the release a build belongs to', legacyCommand: 'posthog-cli release' },
+ { name: 'update', summary: 'Update hog to the latest version', legacyCommand: 'posthog-cli update' },
+]
diff --git a/hog/src/index.ts b/hog/src/index.ts
new file mode 100644
index 000000000000..2e651ae01499
--- /dev/null
+++ b/hog/src/index.ts
@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+import { run } from './cli'
+
+process.exitCode = run(process.argv.slice(2), {
+ stdout: (text) => {
+ process.stdout.write(`${text}\n`)
+ },
+ stderr: (text) => {
+ process.stderr.write(`${text}\n`)
+ },
+})
diff --git a/hog/tsconfig.json b/hog/tsconfig.json
new file mode 100644
index 000000000000..2113cfc00e2c
--- /dev/null
+++ b/hog/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "verbatimModuleSyntax": true,
+ "resolveJsonModule": true,
+ "skipLibCheck": true,
+ "noEmit": true,
+ "types": ["bun"]
+ },
+ "include": ["src"]
+}
diff --git a/owners.yaml b/owners.yaml
index 82a07ccfcc83..e64b67ed0183 100644
--- a/owners.yaml
+++ b/owners.yaml
@@ -87,7 +87,7 @@ rules:
owners: [team-devex, team-agent-infrastructure]
sensitive: true
- match: '/cli/'
- owners: team-error-tracking
+ owners: team-growth
- match: '/docs/onboarding/ai-observability/'
owners: team-ai-observability
- match: '/docs/published/handbook/engineering/developing-locally.md'
@@ -96,6 +96,8 @@ rules:
- '/frontend/src/lib/lemon-ui/'
- '/frontend/src/lib/ui/'
owners: platform-ux
+ - match: '/hog/'
+ owners: team-growth
- match: '/nodejs/tests/'
owners: team-ingestion
- match: '/packages/quill/'
@@ -194,4 +196,5 @@ rules:
- '/services/*'
- '/packages/*'
- '/cli/*'
+ - '/hog/*'
additions: team-devex
diff --git a/package.json b/package.json
index aeb2bff77601..f0b748c5e643 100644
--- a/package.json
+++ b/package.json
@@ -95,7 +95,7 @@
"bin/hogli lint:feature-flags:fix",
"bin/hogli format:js"
],
- "{playwright,frontend,products,common,ee,services,docs}/**/*.{js,jsx,mjs,mts,ts,tsx}": "bin/hogli format:js",
+ "{playwright,frontend,products,common,ee,services,docs,hog}/**/*.{js,jsx,mjs,mts,ts,tsx}": "bin/hogli format:js",
"products/desktop/**/*.{js,mjs,ts,tsx,json,jsonc,css}": "pnpm --dir products/desktop exec biome check --write --no-errors-on-unmatched --files-ignore-unknown=true",
"packages/agent/**/*.{js,mjs,mts,ts,tsx,json,jsonc}": "pnpm --dir packages/agent exec biome check --write --no-errors-on-unmatched --files-ignore-unknown=true",
"nodejs/**/*.{js,jsx,mjs,mts,ts,tsx}": "bin/hogli format:nodejs",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 66743f78277c..fa61e0dfa6d2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1518,6 +1518,15 @@ importers:
specifier: ^2.3.2
version: 2.3.3
+ hog:
+ devDependencies:
+ '@types/bun':
+ specifier: 1.3.14
+ version: 1.3.14
+ typescript:
+ specifier: 6.0.3
+ version: 6.0.3
+
nodejs:
dependencies:
'@amplitude/ua-parser-js':
@@ -13491,6 +13500,9 @@ packages:
resolution: {integrity: sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw==}
+
resolution: {integrity: sha512-758fRH7umIMk5qt5ELmRMff4mLDlN+xyYzC+dkPTdKwbSkJFvz6xwyScrytPU0QIBbRRwbiE8/BIg8bpajerNQ==}
@@ -15175,6 +15187,9 @@ packages:
resolution: {integrity: sha512-8f9ZJCUXyT1M35Jx7MkBgmBMo3oHTTBIPLiY9xyL0pl3T5RwcPEY8cUHr5LBNfu/fk6c2T4DJZuVM/8ZZT2D2A==}
engines: {node: '>=10.0.0'}
+ resolution: {integrity: sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ==}
+
resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
engines: {node: '>=18'}
@@ -33325,6 +33340,10 @@ snapshots:
'@types/connect': 3.4.38
'@types/node': 22.18.8
+ '@types/[email protected]':
+ dependencies:
+ bun-types: 1.3.14
+
dependencies:
'@types/node': 22.18.8
@@ -35389,6 +35408,10 @@ snapshots:
optional: true
+ dependencies:
+ '@types/node': 22.18.8
+
dependencies:
run-applescript: 7.1.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index e82250a0d7e1..4ebc5b8a3cb3 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -13,6 +13,7 @@ packages:
- packages/quill/apps/*
- packages/quill/packages/*
- frontend
+ - hog
- playwright
- nodejs
- nodejs/src/scripts