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.

feat(hog): manage endpoints as YAML files with hog endpoints (#125523)

Rafael Audiberte0871caf862b
diff --git a/hog/AGENTS.md b/hog/AGENTS.md
index 642f6bef1b25..917d31b397db 100644
--- a/hog/AGENTS.md
+++ b/hog/AGENTS.md
@@ -10,6 +10,7 @@
| `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 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 |
diff --git a/hog/README.md b/hog/README.md
index 10965651a85d..2094867cc807 100644
--- a/hog/README.md
+++ b/hog/README.md
@@ -29,6 +29,9 @@ The commands `posthog-cli` keeps under `exp` (`query`, `endpoints`, `logs`, `tas
| `hog error-tracking release` | Finds or creates the release for this build. `-o text` prints just its ID. |
| `hog error-tracking download <id/ref>` | Downloads a symbol set from PostHog and unpacks it. |
| `hog error-tracking extract <file>` | Unpacks a symbol set file. |
+| `hog endpoints list`, `get`, `open` | List your endpoints, show one, or open it in PostHog. |
+| `hog endpoints run [name]` | Runs an endpoint, or the query in a local file with `--file`. `--var name=value` sets variables. |
+| `hog endpoints pull`, `diff`, `push` | Keep endpoints as YAML files: pull them, see how they differ, and push changes. `diff` exits with code 1 on drift. |
| `hog schema pull` | Generates a typed SDK (TypeScript, Go or Python) from your event definitions, and records it in `posthog.json`. |
| `hog schema status` | Checks each generated SDK against PostHog. Exits with code 1 when one is missing or out of date. |
| `hog config check`, `hog config schema` | Check `posthog.json` against its schema, or print the schema. |
@@ -42,7 +45,6 @@ hog replaces posthog-cli once everything below is done.
First, the commands that make hog a complete CLI:
- [ ] `hog api skill` and `hog api agents-md`, which install PostHog agent skills and the AGENTS.md snippet.
-- [ ] `hog endpoints`: `list`, `get`, `open`, `run`, `push`, `pull` and `diff`.
Then, once the commands above work:
@@ -87,6 +89,7 @@ Point `$schema` at the published schema to get validation in your editor:
}
```
+`endpoints.dir` names the folder of endpoint files, so `hog endpoints pull`, `diff` and `push` work without a path.
`hog schema pull` keeps its entries under `languages` in the snake case posthog-cli uses, so either CLI can regenerate an SDK the other set up.
posthog-cli rewrites `posthog.json` with only `languages` when it pulls, so it drops the other settings. Restore them from version control after running it.
diff --git a/hog/package.json b/hog/package.json
index 6ecaaf68a51a..b648e1f550ac 100644
--- a/hog/package.json
+++ b/hog/package.json
@@ -20,7 +20,9 @@
"@posthog/mcp": "workspace:*",
"cli-table3": "0.6.5",
"commander": "15.0.0",
+ "diff": "8.0.4",
"pako": "2.1.0",
+ "yaml": "2.9.0",
"zod": "^4.3.6"
},
"devDependencies": {
diff --git a/hog/posthog.schema.json b/hog/posthog.schema.json
index 0ed10faf91d5..0f279d6e76d1 100644
--- a/hog/posthog.schema.json
+++ b/hog/posthog.schema.json
@@ -65,6 +65,18 @@
"additionalProperties": false,
"description": "Settings for `hog error-tracking`."
},
+ "endpoints": {
+ "description": "Settings for `hog endpoints`.",
+ "type": "object",
+ "properties": {
+ "dir": {
+ "description": "The folder of endpoint YAML files, relative to posthog.json. `hog endpoints pull` writes there, and `push` and `diff` read it when no path is passed.",
+ "type": "string",
+ "minLength": 1
+ }
+ },
+ "additionalProperties": false
+ },
"languages": {
"description": "The typed SDKs `hog schema pull` generates, by language. posthog-cli reads the same entries.",
"type": "object",
diff --git a/hog/src/cli.test.ts b/hog/src/cli.test.ts
index 30184bc753b7..d9db0b1c97ae 100644
--- a/hog/src/cli.test.ts
+++ b/hog/src/cli.test.ts
@@ -46,8 +46,8 @@ describe('hog', () => {
],
[
'an --output that the legacy command owns',
- ['endpoints', 'pull', 'example', '--output', './queries'],
- 'posthog-cli exp endpoints pull example --output ./queries',
+ ['logs', 'import', '--output', './logs'],
+ 'posthog-cli exp logs import --output ./logs',
],
])('%s points to posthog-cli', async (_name, argv, invocation) => {
const result = await runHog(argv)
@@ -115,6 +115,13 @@ describe('hog', () => {
'error-tracking release',
'error-tracking download',
'error-tracking extract',
+ 'endpoints list',
+ 'endpoints get',
+ 'endpoints open',
+ 'endpoints run',
+ 'endpoints push',
+ 'endpoints pull',
+ 'endpoints diff',
'schema pull',
'schema status',
'config check',
diff --git a/hog/src/cli.ts b/hog/src/cli.ts
index a2e4e06b1278..4a50d70ea274 100644
--- a/hog/src/cli.ts
+++ b/hog/src/cli.ts
@@ -28,6 +28,9 @@ const LEGACY_HELP_GROUP = 'Not ported yet (each one prints the posthog-cli comma
function toOption(name: string, spec: OptionSpec): Option {
const option = new Option(optionFlags(name, spec), spec.description)
+ if (spec.type === 'string' && spec.multiple) {
+ option.argParser((value: string, previous: string[] | undefined) => [...(previous ?? []), value])
+ }
return spec.type === 'string' && spec.choices ? option.choices(spec.choices) : option
}
diff --git a/hog/src/commands/endpoints/diff.ts b/hog/src/commands/endpoints/diff.ts
new file mode 100644
index 000000000000..a494c0a2fa3d
--- /dev/null
+++ b/hog/src/commands/endpoints/diff.ts
@@ -0,0 +1,56 @@
+import { defineCommand } from '@/core/command'
+import { listEndpoints } from '@/endpoints/api'
+import { readEndpointFiles } from '@/endpoints/files'
+import { planPush } from '@/endpoints/plan'
+
+import { pushPlanLines } from './push'
+import { endpointPaths, problemLines, SCOPES_READ, type Styler } from './shared'
+
+const inSync = (item: { action: string; reason?: string }): boolean =>
+ item.action === 'skip' && item.reason === 'No changes'
+
+export default defineCommand({
+ description: 'Show how local endpoint files differ from PostHog',
+ args: {
+ paths: {
+ description: 'Endpoint files, folders of them, or glob patterns. Defaults to endpoints.dir in posthog.json',
+ variadic: true,
+ optional: true,
+ },
+ },
+ options: {
+ verbose: { type: 'boolean', description: 'List the endpoints that match PostHog too' },
+ },
+ scopes: SCOPES_READ,
+ notes: 'Exits with code 1 when a file differs from PostHog or is invalid, like `git diff --exit-code`, so CI can catch drift. `hog endpoints push` applies the changes.',
+ examples: ['hog endpoints diff endpoints/', 'hog endpoints diff'],
+
+ async run({ args, ctx }) {
+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, await endpointPaths(ctx, args.paths))
+ const remotes = endpoints.length > 0 ? await listEndpoints(await ctx.posthog()) : []
+ // Variable types live on the project, so a diff only compares which variables each query uses.
+ const plan = planPush(endpoints, remotes, []).map(({ file: _file, ...item }) => item)
+ return { plan, problems }
+ },
+
+ human({ result, out, options }) {
+ const style: Styler = (text, ...styles) => out.style(text, ...styles)
+ problemLines(result.problems, style).forEach((line) => out.line(line))
+ const shown = options.verbose ? result.plan : result.plan.filter((item) => !inSync(item))
+ pushPlanLines(shown, style).forEach((line) => out.line(line))
+ const count = (test: (item: (typeof result.plan)[number]) => boolean): number => result.plan.filter(test).length
+ const parts = [
+ `${count((item) => item.action === 'create')} new`,
+ `${count((item) => item.action === 'update')} changed`,
+ `${count(inSync)} unchanged`,
+ `${count((item) => item.action === 'skip' && !inSync(item)) + result.problems.length} invalid`,
+ ]
+ out.line(out.style(parts.join(', '), 'dim'))
+ },
+
+ agent({ result, out }) {
+ out.json(result)
+ },
+
+ exitCode: (result) => (result.problems.length > 0 || !result.plan.every(inSync) ? 1 : 0),
+})
diff --git a/hog/src/commands/endpoints/endpoints.test.ts b/hog/src/commands/endpoints/endpoints.test.ts
new file mode 100644
index 000000000000..e24a49a5f3a4
--- /dev/null
+++ b/hog/src/commands/endpoints/endpoints.test.ts
@@ -0,0 +1,358 @@
+import { describe, expect, test } from 'bun:test'
+
+import { runHog, TEST_CREDENTIALS } from '@/testing'
+
+import { pushPlanLines } from './push'
+
+const AGENT = { ...TEST_CREDENTIALS, CLAUDECODE: '1' }
+const BASE = 'https://ph.example.com/api/environments/7/'
+
+const endpoint = (
+ name: string,
+ query: Record<string, unknown>,
+ extra: Record<string, unknown> = {}
+): Record<string, unknown> => ({
+ id: `id-${name}`,
+ name,
+ description: '',
+ query,
+ is_active: true,
+ is_materialized: false,
+ created_at: '2026-01-01T00:00:00Z',
+ updated_at: '2026-01-01T00:00:00Z',
+ ui_url: `https://ph.example.com/project/7/endpoints/${name}`,
+ ...extra,
+})
+
+// A trends endpoint as PostHog returns it: nulls for unset fields, variables keyed by ID, and a
+// refresh interval kept after materialization was turned off.
+const TRENDS = endpoint(
+ 'weekly',
+ {
+ kind: 'TrendsQuery',
+ interval: 'week',
+ series: [{ kind: 'EventsNode', event: 'signed_up', math: null }],
+ tags: null,
+ },
+ { data_freshness_seconds: 86400, description: 'Weekly signups' }
+)
+const HOGQL = endpoint('by-type', {
+ kind: 'HogQLQuery',
+ query: 'SELECT count()\r\nFROM events\r\nWHERE event = {variables.event_type}',
+ variables: { 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' } },
+})
+const VARIABLES = [{ id: 'var-1', name: 'event_type', code_name: 'event_type', type: 'String' }]
+
+function server(endpoints: unknown[], extra: (url: string, body: unknown) => unknown = () => undefined) {
+ return (url: string, body: unknown) => {
+ const reply = extra(url, body)
+ if (reply) {
+ return reply as { status: number; body: unknown }
+ }
+ if (url === `${BASE}endpoints/`) {
+ return { status: 200, body: { results: endpoints } }
+ }
+ if (url === `${BASE}insight_variables/`) {
+ return { status: 200, body: { results: VARIABLES } }
+ }
+ return { status: 404, body: { detail: 'Not found.' } }
+ }
+}
+
+const PULLED_WEEKLY =
+ 'name: weekly\ndescription: Weekly signups\nquery_definition:\n kind: TrendsQuery\n interval: week\n series:\n - kind: EventsNode\n event: signed_up\n'
+
+const PULLED_BY_TYPE = `# by-type.yaml
+name: by-type
+query: |-
+ SELECT count()
+ FROM events
+ WHERE event = {variables.event_type}
+variables:
+ - name: event_type
+ type: String
+ default: $pageview
+`
+
+describe('hog endpoints', () => {
+ test('list follows pages until PostHog has no more', async () => {
+ const result = await runHog(['endpoints', 'list'], {
+ env: AGENT,
+ respond: (url) =>
+ url === `${BASE}endpoints/`
+ ? { status: 200, body: { results: [TRENDS], next: `${BASE}endpoints/?offset=1` } }
+ : { status: 200, body: { results: [HOGQL], next: null } },
+ })
+ expect(
+ result.stdout
+ .trim()
+ .split('\n')
+ .map((line) => JSON.parse(line).name)
+ ).toEqual(['weekly', 'by-type'])
+ })
+
+ test('pull writes short files with the project variable types, and updates a file in place', async () => {
+ const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {
+ env: AGENT,
+ files: {
+ '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),
+ '/work/endpoints/signups.yaml': 'name: weekly\nquery_definition:\n kind: TrendsQuery\n',
+ },
+ respond: server([TRENDS, HOGQL]),
+ })
+ expect(result.exitCode).toBe(0)
+ expect(result.files['/work/endpoints/by-type.yaml']).toBe(PULLED_BY_TYPE)
+ expect(result.files['/work/endpoints/signups.yaml']).toBe(`# signups.yaml\n${PULLED_WEEKLY}`)
+ expect(result.files['/work/endpoints/weekly.yaml']).toBeUndefined()
+ })
+
+ test('pull takes variable types from the values when the key cannot read project variables', async () => {
+ const result = await runHog(['endpoints', 'pull', 'by-type', '--yes'], {
+ env: AGENT,
+ respond: server([HOGQL], (url) =>
+ url === `${BASE}insight_variables/` ? { status: 403, body: { detail: 'Forbidden' } } : undefined
+ ),
+ })
+
+ expect(result.exitCode).toBe(0)
+ expect(result.files['/work/by-type.yaml']).toBe(PULLED_BY_TYPE.replace('type: String', 'type: string'))
+ })
+
+ test.each([
+ [
+ 'a file that defines another endpoint',
+ { '/work/weekly.yaml': 'name: by-type\nquery: SELECT 1\n' },
+ { '/work/weekly.yaml': PULLED_BY_TYPE.replace('# by-type.yaml', '# weekly.yaml') },
+ ],
+ [
+ 'a file hog cannot read',
+ { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },
+ { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },
+ ],
+ ])('pull never overwrites %s with another endpoint', async (_name, files, expected) => {
+ const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {
+ env: AGENT,
+ files,
+ respond: server([TRENDS, HOGQL]),
+ })
+ expect(result.exitCode).toBe(1)
+ expect(result.files).toMatchObject(expected)
+ expect(result.json().problems).toEqual([expect.objectContaining({ path: 'weekly.yaml' })])
+ })
+
+ test.each([
+ ['files that match PostHog', { 'by-type.yaml': PULLED_BY_TYPE }, 0, []],
+ [
+ 'a changed query',
+ { 'by-type.yaml': PULLED_BY_TYPE.replace('count()', 'count(*)') },
+ 1,
+ [{ name: 'by-type', action: 'update', fields: ['query'] }],
+ ],
+ [
+ // The file posthog-cli writes, with the lowercase type it infers from the default.
+ 'a posthog-cli file',
+ { 'by-type.yaml': PULLED_BY_TYPE.replace('type: String', 'type: string') },
+ 0,
+ [],
+ ],
+ [
+ // PostHog keeps the refresh interval of an endpoint that is no longer materialized.
+ 'materialization turned off on both sides',
+ { 'weekly.yaml': `${PULLED_WEEKLY}materialization:\n enabled: false\n schedule: 1hour\n` },
+ 0,
+ [],
+ ],
+ [
+ 'a changed default',
+ { 'by-type.yaml': PULLED_BY_TYPE.replace('default: $pageview', 'default: $autocapture') },
+ 1,
+ [{ name: 'by-type', action: 'update', fields: ['defaults'] }],
+ ],
+ ['a file with a typo', { 'by-type.yaml': `${PULLED_BY_TYPE}descripton: oops\n` }, 1, []],
+ ])('diff with %s', async (_name, files, exitCode, changed) => {
+ const result = await runHog(['endpoints', 'diff'], {
+ env: AGENT,
+ files: {
+ '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),
+ ...Object.fromEntries(Object.entries(files).map(([name, text]) => [`/work/endpoints/${name}`, text])),
+ },
+ respond: server([TRENDS, HOGQL]),
+ })
+ expect(result.exitCode).toBe(exitCode)
+ const plan = result.json().plan as { name: string; action: string; changes: { field: string }[] }[]
+ expect(
+ plan
+ .filter((item) => item.action !== 'skip')
+ .map((item) => ({ name: item.name, action: item.action, fields: item.changes.map((c) => c.field) }))
+ ).toEqual(changed)
+ })
+
+ test('pull escapes terminal control characters in the PostHog side of a preview', async () => {
+ const edited = { ...TRENDS, description: '\u001b]52;c;eA==\u0007Weekly signups' }
+
+ const result = await runHog(['endpoints', 'pull', 'weekly', '--dry-run'], {
+ stdoutIsTTY: true,
+ env: { ...TEST_CREDENTIALS, NO_COLOR: '1' },
+ files: { '/work/weekly.yaml': PULLED_WEEKLY },
+ respond: server([edited]),
+ })
+
+ expect(result.stdout).toContain('\\x1b]52;c;eA==\\x07Weekly signups')
+ expect(result.stdout).not.toContain('\u001b')
+ })
+
+ test('push previews escape variable names and rejection reasons from PostHog', () => {
+ const name = '\u001b]52;c;eA==\u0007x'
+ const item = {
+ name: 'weekly',
+ path: 'weekly.yaml',
+ action: 'skip' as const,
+ reason: `${name} is used by the query`,
+ changes: [],
+ variables: [
+ { name, change: 'remove' as const },
+ { name, change: 'retype' as const, type: 'String', from: 'Number' },
+ ],
+ }
+
+ const lines = pushPlanLines([item], (text) => text).join('\n')
+
+ expect(lines).toContain('\\x1b]52;c;eA==\\x07x')
+ expect(lines).not.toContain('\u001b')
+ })
+
+ test('push asks agents for --yes before it changes anything', async () => {
+ const result = await runHog(['endpoints', 'push', 'new.yaml'], {
+ env: AGENT,
+ files: { '/work/new.yaml': 'name: new\nquery: SELECT 1\n' },
+ respond: server([]),
+ })
+ expect(result.error().code).toBe('confirmation_required')
+ expect(result.requests.filter((request) => request.method !== 'GET')).toEqual([])
+ })
+
+ test('push creates the variables a file needs, then the endpoint, and skips files PostHog would reject', async () => {
+ const result = await runHog(['endpoints', 'push', 'endpoints', '--yes'], {
+ env: AGENT,
+ files: {
+ '/work/endpoints/a.yaml': [
+ 'name: by-country',
+ 'query: SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',
+ 'variables:',
+ ' - name: country',
+ // posthog-cli writes lowercase types, and PostHog only accepts its own names.
+ ' type: string',
+ ' default: US',
+ ' - name: regions',
+ ' type: array',
+ ' default: [eu, us]',
+ 'materialization:',
+ ' enabled: true',
+ ' schedule: 1hour',
+ ].join('\n'),
+ '/work/endpoints/b.yaml':
+ 'name: unused\nquery: SELECT 1\nvariables:\n - name: extra\n type: String\n',
+ },
+ respond: server([], (url, body) =>
+ url === `${BASE}insight_variables/` && body
+ ? {
+ status: 201,
+ body:
+ (body as { code_name: string }).code_name === 'country'
+ ? { id: 'var-2', name: 'country', code_name: 'country', type: 'String' }
+ : {
+ id: 'var-3',
+ name: 'regions',
+ code_name: 'regions',
+ type: 'List',
+ is_multi: true,
+ },
+ }
+ : url === `${BASE}endpoints/` && body
+ ? { status: 201, body: { ...endpoint('by-country', {}), ui_url: 'https://ph.example.com/e' } }
+ : undefined
+ ),
+ })
+ expect(result.exitCode).toBe(1)
+ expect(result.requests.filter((request) => request.method === 'POST').map((request) => request.body)).toEqual([
+ { name: 'country', code_name: 'country', type: 'String', default_value: 'US' },
+ // An array default makes a multiple-selection list, or PostHog keeps only its first value.
+ { name: 'regions', code_name: 'regions', type: 'List', default_value: ['eu', 'us'], is_multi: true },
+ {
+ name: 'by-country',
+ description: '',
+ query: {
+ kind: 'HogQLQuery',
+ query: 'SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',
+ variables: {
+ 'var-2': { variableId: 'var-2', code_name: 'country', value: 'US' },
+ 'var-3': { variableId: 'var-3', code_name: 'regions', value: ['eu', 'us'] },
+ },
+ },
+ is_materialized: true,
+ data_freshness_seconds: 3600,
+ },
+ ])
+ expect(result.json()).toMatchObject({
+ outcomes: [{ name: 'by-country', status: 'created' }],
+ plan: [{}, { name: 'unused', action: 'skip', invalid: true, reason: expect.stringContaining('extra') }],
+ })
+ })
+
+ test.each([
+ ['neither a name nor --file', ['endpoints', 'run'], 'usage_error'],
+ ['a name and --file', ['endpoints', 'run', 'x', '--file', 'x.yaml'], 'usage_error'],
+ ['a variable without a value', ['endpoints', 'run', 'x', '--var', 'country'], 'invalid_variable'],
+ ])('run refuses %s', async (_name, argv, code) => {
+ const result = await runHog(argv, { env: AGENT })
+ expect(result.exitCode).toBe(2)
+ expect(result.error().code).toBe(code)
+ })
+
+ test('run passes every --var to the endpoint', async () => {
+ const result = await runHog(['endpoints', 'run', 'by-type', '--var', 'a=1', '--var', 'b=x=y'], {
+ env: AGENT,
+ respond: () => ({ status: 200, body: { columns: ['total'], results: [[3]] } }),
+ })
+ expect(result.requests[0]).toMatchObject({
+ url: `${BASE}endpoints/by-type/run/`,
+ body: { variables: { a: '1', b: 'x=y' } },
+ })
+ expect(result.stdout).toBe('[3]\n')
+ })
+
+ test('run --file puts variables in the query with their project IDs, and falls back to the file defaults', async () => {
+ const result = await runHog(['endpoints', 'run', '--file', 'by-type.yaml', '--var', 'limit=5'], {
+ env: AGENT,
+ files: {
+ '/work/by-type.yaml': `${PULLED_BY_TYPE.replace('count()', 'count() LIMIT {variables.limit}')} - name: limit\n type: Number\n`,
+ },
+ respond: server([], (url) =>
+ url === `${BASE}insight_variables/`
+ ? {
+ status: 200,
+ body: {
+ results: [
+ ...VARIABLES,
+ { id: 'var-9', name: 'limit', code_name: 'limit', type: 'Number' },
+ ],
+ },
+ }
+ : url === `${BASE}query/`
+ ? { status: 200, body: { columns: ['n'], results: [[1]] } }
+ : undefined
+ ),
+ })
+ expect(result.exitCode).toBe(0)
+ expect(result.requests.at(-1)!.body).toMatchObject({
+ query: {
+ kind: 'HogQLQuery',
+ variables: {
+ 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' },
+ 'var-9': { variableId: 'var-9', code_name: 'limit', value: '5' },
+ },
+ },
+ })
+ expect(result.requests.at(-1)!.body).not.toHaveProperty('variables')
+ })
+})
diff --git a/hog/src/commands/endpoints/get.ts b/hog/src/commands/endpoints/get.ts
new file mode 100644
index 000000000000..4f67509efe19
--- /dev/null
+++ b/hog/src/commands/endpoints/get.ts
@@ -0,0 +1,59 @@
+import { defineCommand } from '@/core/command'
+import { escapeControls } from '@/core/output'
+import { getEndpoint } from '@/endpoints/api'
+
+import { materializationLabel, SCOPES_READ } from './shared'
+
+export default defineCommand({
+ description: 'Show an endpoint: its URLs, query, versions and materialization',
+ args: { name: { description: 'The endpoint name' } },
+ scopes: SCOPES_READ,
+ examples: ['hog endpoints get daily-signups'],
+
+ async run({ args, ctx }) {
+ return getEndpoint(await ctx.posthog(), args.name)
+ },
+
+ human({ result: endpoint, out }) {
+ const field = (label: string, value: string): void =>
+ out.line(` ${out.style(label.padEnd(12), 'bold')}${value}`)
+ // Anyone in the project can edit this text, so escape sequences in it must not reach the terminal.
+ const text = escapeControls
+ if (endpoint.ui_url) {
+ field('View', out.style(text(endpoint.ui_url), 'cyan'))
+ }
+ if (endpoint.url) {
+ field('Run', out.style(text(endpoint.url), 'cyan'))
+ }
+ field('Name', text(endpoint.name))
+ field('Status', endpoint.is_active ? out.style('active', 'green') : out.style('inactive', 'red'))
+ if (endpoint.description) {
+ field('Description', text(endpoint.description))
+ }
+ field('Version', `${endpoint.current_version ?? 1} (${endpoint.versions_count ?? 1} total)`)
+ field('Refresh', materializationLabel(endpoint))
+ const materialization = endpoint.materialization
+ if (endpoint.is_materialized && materialization) {
+ if (materialization.status) {
+ field('Last run', text(materialization.status.toLowerCase()))
+ }
+ if (materialization.last_materialized_at) {
+ field('Last done', text(materialization.last_materialized_at))
+ }
+ if (materialization.error) {
+ field('Error', out.style(text(materialization.error), 'red'))
+ }
+ } else if (materialization && materialization.can_materialize === false && materialization.reason) {
+ field('', out.style(text(materialization.reason), 'dim'))
+ }
+ field('Created', text(endpoint.created_at))
+ field('Updated', text(endpoint.updated_at))
+ out.line()
+ out.line(` ${out.style('Query', 'bold')}`)
+ const query =
+ typeof endpoint.query.query === 'string' ? endpoint.query.query : JSON.stringify(endpoint.query, null, 2)
+ for (const line of query.split('\n')) {
+ out.line(` ${out.style(text(line), 'dim')}`)
+ }
+ },
+})
diff --git a/hog/src/commands/endpoints/index.ts b/hog/src/commands/endpoints/index.ts
new file mode 100644
index 000000000000..824097c677eb
--- /dev/null
+++ b/hog/src/commands/endpoints/index.ts
@@ -0,0 +1,14 @@
+import { defineGroup } from '@/core/command'
+
+import diff from './diff'
+import get from './get'
+import list from './list'
+import open from './open'
+import pull from './pull'
+import push from './push'
+import run from './run'
+
+export default defineGroup({
+ description: 'Manage PostHog endpoints as YAML files: pull, diff, push and run them',
+ commands: { list, get, open, run, push, pull, diff },
+})
diff --git a/hog/src/commands/endpoints/list.ts b/hog/src/commands/endpoints/list.ts
new file mode 100644
index 000000000000..4fd30514e13b
--- /dev/null
+++ b/hog/src/commands/endpoints/list.ts
@@ -0,0 +1,38 @@
+import { defineCommand } from '@/core/command'
+import { plural } from '@/core/text'
+import { listEndpoints } from '@/endpoints/api'
+
+import { materializationLabel, SCOPES_READ, summary } from './shared'
+
+export default defineCommand({
+ description: 'List the endpoints in your project',
+ scopes: SCOPES_READ,
+ examples: ['hog endpoints list'],
+
+ async run({ ctx }) {
+ const api = await ctx.posthog()
+ return { projectId: (await ctx.credentials()).projectId, endpoints: await listEndpoints(api) }
+ },
+
+ human({ result, out }) {
+ if (result.endpoints.length === 0) {
+ out.line(`No endpoints in project ${result.projectId} yet.`)
+ out.line(`Create one from a YAML file with ${out.style('hog endpoints push my-endpoint.yaml', 'bold')}.`)
+ return
+ }
+ out.table(
+ ['name', 'refresh', 'active', 'description'],
+ result.endpoints.map((endpoint) => [
+ endpoint.name,
+ materializationLabel(endpoint),
+ endpoint.is_active,
+ endpoint.description ?? '',
+ ])
+ )
+ out.line(out.style(`${plural(result.endpoints.length, 'endpoint')} in project ${result.projectId}`, 'dim'))
+ },
+
+ agent({ result, out }) {
+ out.jsonLines(result.endpoints.map(summary))
+ },
+})
diff --git a/hog/src/commands/endpoints/open.ts b/hog/src/commands/endpoints/open.ts
new file mode 100644
index 000000000000..e871451dd5ca
--- /dev/null
+++ b/hog/src/commands/endpoints/open.ts
@@ -0,0 +1,26 @@
+import { defineCommand } from '@/core/command'
+import { HogError } from '@/core/errors'
+import { getEndpoint } from '@/endpoints/api'
+
+import { SCOPES_READ } from './shared'
+
+export default defineCommand({
+ description: 'Open an endpoint in PostHog in your browser',
+ args: { name: { description: 'The endpoint name' } },
+ scopes: SCOPES_READ,
+ notes: 'Agents get the link instead of a browser window.',
+ examples: ['hog endpoints open daily-signups'],
+
+ async run({ args, ctx }) {
+ const endpoint = await getEndpoint(await ctx.posthog(), args.name)
+ if (!endpoint.ui_url) {
+ throw new HogError('no_ui_url', `PostHog didn't return a link for ${args.name}.`)
+ }
+ const opened = ctx.mode.agent === undefined && (await ctx.runtime.openUrl(endpoint.ui_url))
+ return { name: endpoint.name, url: endpoint.ui_url, opened }
+ },
+
+ human({ result, out }) {
+ out.line(result.opened ? `Opened ${result.url}` : `Open ${result.url}`)
+ },
+})
diff --git a/hog/src/commands/endpoints/pull.ts b/hog/src/commands/endpoints/pull.ts
new file mode 100644
index 000000000000..b4ae8f37b16d
--- /dev/null
+++ b/hog/src/commands/endpoints/pull.ts
@@ -0,0 +1,199 @@
+import { basename, join, relative } from 'node:path'
+import { stringify } from 'yaml'
+
+import { defineCommand } from '@/core/command'
+import { EXIT_USAGE, HogError } from '@/core/errors'
+import { Output } from '@/core/output'
+import { absolutePath } from '@/core/paths'
+import { plural } from '@/core/text'
+import { listEndpoints, listInsightVariables } from '@/endpoints/api'
+import { readEndpointFiles, type FileProblem } from '@/endpoints/files'
+import { fileFromEndpoint, remoteVariableNames } from '@/endpoints/model'
+import { planPull, type PullItem } from '@/endpoints/plan'
+import { ApiError, type PostHogApi } from '@/posthog/api'
+
+import { actionLabel, changeLines, CONFIRM_OPTIONS, confirm, indent, SCOPES_READ, type Styler } from './shared'
+
+type PlannedItem = Omit<PullItem, 'endpoint'>
+
+interface PullResult {
+ status: 'written' | 'preview' | 'cancelled' | 'nothing_to_do'
+ plan: PlannedItem[]
+ written: string[]
+ problems: FileProblem[]
+}
+
+const isYamlFile = (path: string): boolean => /\.ya?ml$/i.test(path)
+
+function pullPlanLines(plan: PlannedItem[], style: Styler): string[] {
+ return plan
+ .filter((item) => item.action !== 'skip')
+ .flatMap((item) => [
+ `${actionLabel(item.action, style)} ${style(item.path, 'bold')}`,
+ ...indent(item.changes.flatMap((change) => changeLines(change, 'pull', style))),
+ ])
+}
+
+// posthog-cli pulls with only endpoint:read. A key that can't read the project's variables gets
+// each type from the variable's value instead, as posthog-cli does.
+async function variableTypes(api: PostHogApi): Promise<Map<string, string>> {
+ try {
+ return new Map((await listInsightVariables(api)).map((variable) => [variable.code_name, variable.type]))
+ } catch (error) {
+ if (error instanceof ApiError && error.status === 403) {
+ return new Map()
+ }
+ throw error
+ }
+}
+
+export function endpointYaml(path: string, item: PullItem, types: ReadonlyMap<string, string>): string {
+ const body = stringify(fileFromEndpoint(item.endpoint, types), { lineWidth: 0, blockQuote: 'literal' })
+ return `# ${basename(path)}\n${body}`
+}
+
+export default defineCommand({
+ description: 'Write PostHog endpoints to local YAML files',
+ args: { names: { description: 'The endpoints to pull', variadic: true, optional: true } },
+ options: {
+ all: { type: 'boolean', description: 'Pull every endpoint in the project' },
+ to: {
+ type: 'string',
+ placeholder: 'path',
+ description:
+ 'A folder, or a .yaml file when pulling one endpoint. Defaults to endpoints.dir in posthog.json, then .',
+ },
+ ...CONFIRM_OPTIONS,
+ },
+ scopes: SCOPES_READ,
+ notes: 'An endpoint a local file already defines updates that file. Others go to <folder>/<name>.yaml. hog shows the changes and asks before it writes; agents and scripts pass --yes. Exits with code 1 when an endpoint is missing or a file is left alone.',
+ examples: [
+ 'hog endpoints pull daily-signups',
+ 'hog endpoints pull --all --to endpoints/',
+ 'hog endpoints pull --all --yes',
+ ],
+
+ async run({ args, options, ctx }): Promise<PullResult> {
+ if (!options.all && args.names.length === 0) {
+ throw new HogError(
+ 'usage_error',
+ 'Pass the endpoints to pull, or --all.',
+ 'Run `hog endpoints list` to see the names.',
+ EXIT_USAGE
+ )
+ }
+ const loaded = await ctx.config()
+ const configured = loaded?.config.endpoints?.dir
+ const target =
+ options.to !== undefined
+ ? absolutePath(ctx.runtime.cwd(), options.to)
+ : loaded && configured
+ ? absolutePath(loaded.root, configured)
+ : ctx.runtime.cwd()
+ const fileTarget = isYamlFile(target)
+
+ const remotes = await listEndpoints(await ctx.posthog())
+ const problems: FileProblem[] = []
+ let selected = remotes
+ if (!options.all) {
+ const known = new Set(remotes.map((endpoint) => endpoint.name))
+ const missing = args.names.filter((name) => !known.has(name))
+ if (missing.length === args.names.length) {
+ throw new HogError(
+ 'endpoint_not_found',
+ `PostHog has no endpoint named ${missing.join(', ')}.`,
+ 'Run `hog endpoints list` to see the names.'
+ )
+ }
+ problems.push(...missing.map((name) => ({ path: name, message: 'PostHog has no endpoint with this name' })))
+ selected = remotes.filter((endpoint) => args.names.includes(endpoint.name))
+ }
+ if (fileTarget && selected.length > 1) {
+ throw new HogError(
+ 'usage_error',
+ `--to names one file, but there are ${plural(selected.length, 'endpoint')} to pull.`,
+ 'Pass a folder, or pull one endpoint at a time.',
+ EXIT_USAGE
+ )
+ }
+
+ const scan = fileTarget
+ ? (await ctx.runtime.exists(target))
+ ? [target]
+ : []
+ : (await ctx.runtime.isDirectory(target))
+ ? [target]
+ : []
+ const { endpoints: locals, problems: unreadable } = await readEndpointFiles(ctx.runtime, scan)
+ const cwd = ctx.runtime.cwd()
+ const claimed = new Set(locals.map((local) => absolutePath(cwd, local.path)))
+ const broken = new Map(unreadable.map((problem) => [absolutePath(cwd, problem.path), problem.message]))
+ const written = new Set<string>()
+ // Never write a file twice, replace a file that defines another endpoint, or overwrite one hog can't read.
+ const items = planPull(selected, locals, (name) => (fileTarget ? target : join(target, `${name}.yaml`))).map(
+ (planned): PullItem => {
+ const item = { ...planned, path: absolutePath(cwd, planned.path) }
+ const blocked = written.has(item.path)
+ ? 'Another endpoint pulled to the same file'
+ : item.action === 'create' && broken.has(item.path)
+ ? `The file exists but hog can't read it (${broken.get(item.path)}), so hog leaves it alone`
+ : item.action === 'create' && claimed.has(item.path)
+ ? 'The file defines another endpoint'
+ : undefined
+ if (blocked) {
+ problems.push({ path: relative(cwd, item.path) || item.path, message: `${item.name}: ${blocked}` })
+ return { ...item, action: 'skip', reason: blocked }
+ }
+ if (item.action !== 'skip') {
+ written.add(item.path)
+ }
+ return item
+ }
+ )
+ const shown = (path: string): string => relative(ctx.runtime.cwd(), path) || path
+ const plan = items.map(({ endpoint: _endpoint, ...item }) => ({ ...item, path: shown(item.path) }))
+ const pending = items.filter((item) => item.action !== 'skip')
+ if (pending.length === 0) {
+ return { status: 'nothing_to_do', plan, written: [], problems }
+ }
+ if (options.dryRun) {
+ return { status: 'preview', plan, written: [], problems }
+ }
+ const style: Styler = (text, ...styles) => new Output(ctx.runtime, ctx.mode).style(text, ...styles)
+ if (!(await confirm(ctx, options, pullPlanLines(plan, style), `Write ${plural(pending.length, 'file')}?`))) {
+ return { status: 'cancelled', plan, written: [], problems }
+ }
+ const types = pending.some((item) => remoteVariableNames(item.endpoint).length > 0)
+ ? await variableTypes(await ctx.posthog())
+ : new Map<string, string>()
+ for (const item of pending) {
+ await ctx.runtime.writeFile(item.path, endpointYaml(item.path, item, types))
+ }
+ return { status: 'written', plan, written: pending.map((item) => shown(item.path)), problems }
+ },
+
+ human({ result, out }) {
+ const style: Styler = (text, ...styles) => out.style(text, ...styles)
+ for (const problem of result.problems) {
+ out.line(`${out.style('Skipped', 'yellow', 'bold')} ${problem.path}: ${problem.message}`)
+ }
+ if (result.status === 'written') {
+ result.written.forEach((path) => out.line(`${out.style('Wrote', 'green', 'bold')} ${path}`))
+ out.line(out.style(`${plural(result.written.length, 'file')} written`, 'dim'))
+ return
+ }
+ pullPlanLines(result.plan, style).forEach((line) => out.line(line))
+ const messages = {
+ preview: 'Dry run: no files written.',
+ cancelled: 'Cancelled: no files written.',
+ nothing_to_do: 'The local files already match PostHog.',
+ }
+ out.line(out.style(messages[result.status], 'dim'))
+ },
+
+ agent({ result, out }) {
+ out.json(result)
+ },
+
+ exitCode: (result) => (result.problems.length > 0 ? 1 : 0),
+})
diff --git a/hog/src/commands/endpoints/push.ts b/hog/src/commands/endpoints/push.ts
new file mode 100644
index 000000000000..7c5982913e2c
--- /dev/null
+++ b/hog/src/commands/endpoints/push.ts
@@ -0,0 +1,130 @@
+import { defineCommand } from '@/core/command'
+import { escapeControls, Output } from '@/core/output'
+import { plural } from '@/core/text'
+import { listEndpoints, listInsightVariables } from '@/endpoints/api'
+import { readEndpointFiles, type FileProblem } from '@/endpoints/files'
+import type { InsightVariable } from '@/endpoints/model'
+import { applyPush, planPush, type PushItem, type PushOutcome } from '@/endpoints/plan'
+
+import {
+ actionLabel,
+ changeLines,
+ CONFIRM_OPTIONS,
+ confirm,
+ endpointPaths,
+ indent,
+ problemLines,
+ SCOPES_WRITE,
+ variableLines,
+ type Styler,
+} from './shared'
+
+type PlannedItem = Omit<PushItem, 'file'>
+
+interface PushResult {
+ status: 'applied' | 'preview' | 'cancelled' | 'nothing_to_do'
+ plan: PlannedItem[]
+ outcomes: PushOutcome[]
+ problems: FileProblem[]
+}
+
+export function pushPlanLines(plan: PlannedItem[], style: Styler): string[] {
+ return plan.flatMap((item) => [
+ `${actionLabel(item.action, style)} ${style(item.name, 'bold')} ${style(item.path, 'dim')}`,
+ ...indent(
+ item.reason && item.action === 'skip' && item.reason !== 'No changes'
+ ? [style(escapeControls(item.reason), 'yellow')]
+ : []
+ ),
+ ...indent(item.changes.flatMap((change) => changeLines(change, 'push', style))),
+ ...indent(variableLines(item.variables, style)),
+ ])
+}
+
+export default defineCommand({
+ description: 'Create or update PostHog endpoints from local YAML files',
+ args: {
+ paths: {
+ description: 'Endpoint files, folders of them, or glob patterns. Defaults to endpoints.dir in posthog.json',
+ variadic: true,
+ optional: true,
+ },
+ },
+ options: CONFIRM_OPTIONS,
+ scopes: SCOPES_WRITE,
+ notes: 'hog shows the changes and asks before it makes them. Agents and scripts pass --yes. hog creates the insight variables a file uses that the project lacks. Exits with code 1 when a file is invalid, PostHog would reject it, or an endpoint fails to save.',
+ examples: [
+ 'hog endpoints push endpoints/',
+ 'hog endpoints push daily-signups.yaml --dry-run',
+ 'hog endpoints push --yes',
+ ],
+
+ async run({ args, options, ctx }): Promise<PushResult> {
+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, await endpointPaths(ctx, args.paths))
+ if (endpoints.length === 0) {
+ return { status: 'nothing_to_do', plan: [], outcomes: [], problems }
+ }
+ const api = await ctx.posthog()
+ const usesVariables = endpoints.some((local) => (local.file.variables ?? []).length > 0)
+ const [remotes, variables] = await Promise.all([
+ listEndpoints(api),
+ usesVariables ? listInsightVariables(api) : Promise.resolve([] as InsightVariable[]),
+ ])
+ const items = planPush(endpoints, remotes, variables)
+ const plan = items.map(({ file: _file, ...item }) => item)
+ const pending = plan.filter((item) => item.action !== 'skip')
+ if (pending.length === 0) {
+ return { status: 'nothing_to_do', plan, outcomes: [], problems }
+ }
+ if (options.dryRun) {
+ return { status: 'preview', plan, outcomes: [], problems }
+ }
+ const style = (text: string, ...styles: Parameters<Styler>[1][]): string =>
+ new Output(ctx.runtime, ctx.mode).style(text, ...styles)
+ const question = `Push ${plural(pending.length, 'endpoint')} to PostHog?`
+ if (!(await confirm(ctx, options, pushPlanLines(pending, style), question))) {
+ return { status: 'cancelled', plan, outcomes: [], problems }
+ }
+ return { status: 'applied', plan, outcomes: await applyPush(api, items, variables), problems }
+ },
+
+ human({ result, out }) {
+ const style: Styler = (text, ...styles) => out.style(text, ...styles)
+ problemLines(result.problems, style).forEach((line) => out.line(line))
+ if (result.status === 'applied') {
+ for (const outcome of result.outcomes) {
+ if (outcome.status === 'failed') {
+ out.line(
+ `${out.style('Failed', 'red', 'bold')} ${outcome.name}: ${escapeControls(outcome.error ?? '')}`
+ )
+ } else {
+ const verb = outcome.status === 'created' ? 'Created' : 'Updated'
+ out.line(
+ `${out.style(verb, 'green', 'bold')} ${outcome.name} ${out.style(outcome.uiUrl ?? '', 'dim')}`
+ )
+ }
+ }
+ const saved = result.outcomes.filter((outcome) => outcome.status !== 'failed').length
+ out.line(out.style(`${plural(saved, 'endpoint')} pushed`, 'dim'))
+ return
+ }
+ pushPlanLines(result.plan, style).forEach((line) => out.line(line))
+ const messages = {
+ preview: 'Dry run: nothing changed in PostHog.',
+ cancelled: 'Cancelled: nothing changed in PostHog.',
+ nothing_to_do: 'Nothing to push.',
+ }
+ out.line(out.style(messages[result.status], 'dim'))
+ },
+
+ agent({ result, out }) {
+ out.json(result)
+ },
+
+ exitCode: (result) =>
+ result.problems.length > 0 ||
+ result.plan.some((item) => item.invalid) ||
+ result.outcomes.some((outcome) => outcome.status === 'failed')
+ ? 1
+ : 0,
+})
diff --git a/hog/src/commands/endpoints/run.ts b/hog/src/commands/endpoints/run.ts
new file mode 100644
index 000000000000..b2fe3b1e6bb6
--- /dev/null
+++ b/hog/src/commands/endpoints/run.ts
@@ -0,0 +1,145 @@
+import { defineCommand } from '@/core/command'
+import { EXIT_USAGE, HogError } from '@/core/errors'
+import { plural } from '@/core/text'
+import { listInsightVariables } from '@/endpoints/api'
+import { readEndpointFiles } from '@/endpoints/files'
+import { ApiError, type PostHogApi } from '@/posthog/api'
+
+interface RunResponse {
+ columns?: string[] | null
+ results?: unknown[] | null
+ hasMore?: boolean | null
+}
+
+// HogQL finds a variable by its project ID, so a file's variables must exist in the project. A
+// value left out uses the variable's default.
+async function queryVariables(api: PostHogApi, values: Map<string, unknown>): Promise<Record<string, unknown>> {
+ const known = new Map((await listInsightVariables(api)).map((variable) => [variable.code_name, variable]))
+ const missing = [...values.keys()].filter((name) => !known.has(name))
+ if (missing.length > 0) {
+ throw new HogError(
+ 'unknown_variable',
+ `The project has no variable named ${missing.join(', ')}.`,
+ '`hog endpoints push` creates the variables a file defines.'
+ )
+ }
+ return Object.fromEntries(
+ [...values].map(([name, value]) => {
+ const { id } = known.get(name)!
+ const entry = { variableId: id, code_name: name, ...(value === undefined ? {} : { value }) }
+ // Without `isNull`, PostHog replaces a null value with the project's default.
+ return [id, value === null ? { ...entry, isNull: true } : entry]
+ })
+ )
+}
+
+function parseVariables(pairs: readonly string[]): Record<string, string> {
+ return Object.fromEntries(
+ pairs.map((pair) => {
+ const separator = pair.indexOf('=')
+ if (separator <= 0) {
+ throw new HogError(
+ 'invalid_variable',
+ `--var ${pair} isn't name=value.`,
+ 'Pass each variable as --var name=value.',
+ EXIT_USAGE
+ )
+ }
+ return [pair.slice(0, separator), pair.slice(separator + 1)]
+ })
+ )
+}
+
+export default defineCommand({
+ description: 'Run an endpoint, or the query in a local endpoint file, and print the results',
+ args: { name: { description: 'The endpoint to run', optional: true } },
+ options: {
+ file: {
+ type: 'string',
+ short: 'f',
+ placeholder: 'path',
+ description: 'Run the query in this endpoint file without creating the endpoint',
+ },
+ var: {
+ type: 'string',
+ short: 'v',
+ placeholder: 'name=value',
+ multiple: true,
+ description: 'A variable value for the query. Repeat it for each variable',
+ },
+ },
+ scopes: ['endpoint:read', 'query:read', 'insight_variable:read'],
+ notes: 'Prints a table in a terminal, and one JSON array per row for agents and pipes. --raw prints the full response.',
+ examples: [
+ 'hog endpoints run daily-signups',
+ 'hog endpoints run events-by-type --var event_type=$pageview',
+ 'hog endpoints run --file endpoints/daily-signups.yaml',
+ ],
+
+ async run({ args, options, ctx }): Promise<RunResponse> {
+ if ((args.name === undefined) === (options.file === undefined)) {
+ throw new HogError(
+ 'usage_error',
+ 'Pass an endpoint name or --file, but not both.',
+ 'Run `hog endpoints list` to see the endpoint names.',
+ EXIT_USAGE
+ )
+ }
+ const variables = parseVariables(options.var ?? [])
+ const withVariables = Object.keys(variables).length > 0 ? { variables } : {}
+ const api = await ctx.posthog()
+
+ if (options.file !== undefined) {
+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, [options.file])
+ const [local] = endpoints
+ if (!local) {
+ const [problem] = problems
+ throw new HogError(
+ 'invalid_endpoint_file',
+ `${problem?.path ?? options.file}: ${problem?.message ?? 'not an endpoint file'}`
+ )
+ }
+ const query: Record<string, unknown> = local.file.query_definition ?? {
+ kind: 'HogQLQuery',
+ query: local.file.query,
+ }
+ const values = new Map<string, unknown>()
+ for (const variable of local.file.variables ?? []) {
+ values.set(variable.name, variable.default)
+ }
+ for (const [name, value] of Object.entries(variables)) {
+ values.set(name, value)
+ }
+ if (values.size > 0) {
+ query.variables = await queryVariables(api, values)
+ }
+ return api.post<RunResponse>('query/', { query, name: 'endpoints_cli', refresh: 'blocking' })
+ }
+
+ try {
+ return await api.post<RunResponse>(`endpoints/${encodeURIComponent(args.name!)}/run/`, withVariables)
+ } catch (error) {
+ if (error instanceof ApiError && error.status === 404) {
+ throw error.withHint(
+ `Check that ${args.name} is in \`hog endpoints list\` and active. Inactive endpoints don't run.`
+ )
+ }
+ throw error
+ }
+ },
+
+ human({ result, out }) {
+ const rows = (result.results ?? []) as unknown[][]
+ if (result.columns && rows.every(Array.isArray)) {
+ out.table(result.columns, rows)
+ const count = plural(rows.length, 'row')
+ out.line(out.style(result.hasMore ? `${count}, more available` : count, 'dim'))
+ return
+ }
+ out.json(result.results ?? result)
+ },
+
+ agent({ result, out }) {
+ out.jsonLines(result.results ?? [])
+ },
+})
diff --git a/hog/src/commands/endpoints/shared.ts b/hog/src/commands/endpoints/shared.ts
new file mode 100644
index 000000000000..fcf8e0af0c08
--- /dev/null
+++ b/hog/src/commands/endpoints/shared.ts
@@ -0,0 +1,151 @@
+import { diffLines } from 'diff'
+
+import type { Context } from '@/core/context'
+import { EXIT_USAGE, HogError } from '@/core/errors'
+import { escapeControls, type Style } from '@/core/output'
+import { absolutePath } from '@/core/paths'
+import type { Change } from '@/endpoints/changes'
+import type { FileProblem } from '@/endpoints/files'
+import { SCHEDULE_LABELS, scheduleFor, type Endpoint } from '@/endpoints/model'
+import type { VariableChange } from '@/endpoints/plan'
+
+export type Styler = (text: string, ...styles: Style[]) => string
+
+export const SCOPES_READ = ['endpoint:read'] as const
+export const SCOPES_WRITE = [
+ 'endpoint:read',
+ 'endpoint:write',
+ 'insight_variable:read',
+ 'insight_variable:write',
+] as const
+
+export const CONFIRM_OPTIONS = {
+ dryRun: { type: 'boolean', description: 'Show the changes without making them' },
+ yes: { type: 'boolean', short: 'y', description: 'Make the changes without asking. Agents and scripts need it' },
+} as const
+
+export function summary(endpoint: Endpoint): Record<string, unknown> {
+ return {
+ name: endpoint.name,
+ description: endpoint.description ?? '',
+ active: endpoint.is_active,
+ materialized: endpoint.is_materialized,
+ schedule: endpoint.is_materialized ? (scheduleFor(endpoint.data_freshness_seconds) ?? null) : null,
+ url: endpoint.url ?? null,
+ uiUrl: endpoint.ui_url ?? null,
+ }
+}
+
+export function materializationLabel(endpoint: Endpoint): string {
+ if (!endpoint.is_materialized) {
+ return 'on demand'
+ }
+ const schedule = scheduleFor(endpoint.data_freshness_seconds)
+ return `materialized, ${schedule ? SCHEDULE_LABELS[schedule] : 'scheduled'}`
+}
+
+// The paths a push or diff reads: the arguments, or `endpoints.dir` from posthog.json.
+export async function endpointPaths(ctx: Context, paths: readonly string[]): Promise<string[]> {
+ if (paths.length > 0) {
+ return [...paths]
+ }
+ const loaded = await ctx.config()
+ const dir = loaded?.config.endpoints?.dir
+ if (loaded && dir) {
+ return [absolutePath(loaded.root, dir)]
+ }
+ throw new HogError(
+ 'paths_required',
+ 'Pass the endpoint files or folders to read.',
+ 'Or set endpoints.dir in posthog.json to the folder that holds them.',
+ EXIT_USAGE
+ )
+}
+
+// Asks a person before changes happen. Agents and scripts can't answer, so they pass --yes.
+export async function confirm(
+ ctx: Context,
+ options: { yes?: boolean },
+ preview: string[],
+ question: string
+): Promise<boolean> {
+ if (options.yes) {
+ return true
+ }
+ if (!ctx.prompts) {
+ throw new HogError(
+ 'confirmation_required',
+ 'hog needs a confirmation before it makes these changes.',
+ 'Pass --yes to make them, or --dry-run to only see them.'
+ )
+ }
+ ctx.prompts.note(preview.join('\n'), 'Changes')
+ return ctx.prompts.confirm(question)
+}
+
+const LABELS: Record<Change['field'], string> = {
+ description: 'Description',
+ query: 'Query',
+ materialization: 'Materialization',
+ schedule: 'Schedule',
+ variables: 'Variables',
+ defaults: 'Defaults',
+}
+
+// `from` is the side that changes: PostHog for a push, the file for a pull. Anyone in the project
+// can edit the PostHog side, so escape sequences in it must not reach the terminal.
+export function changeLines(change: Change, direction: 'push' | 'pull', style: Styler): string[] {
+ const [from, to] = direction === 'push' ? [change.remote, change.local] : [change.local, change.remote]
+ if (change.field !== 'query') {
+ return [`${LABELS[change.field]}: ${escapeControls(from) || '(none)'} → ${escapeControls(to) || '(none)'}`]
+ }
+ const lines = [`${LABELS.query}:`]
+ for (const part of diffLines(from.endsWith('\n') ? from : `${from}\n`, to.endsWith('\n') ? to : `${to}\n`)) {
+ const sign = part.added ? '+' : part.removed ? '-' : ' '
+ const color: Style = part.added ? 'green' : part.removed ? 'red' : 'dim'
+ for (const line of part.value.replace(/\n$/, '').split('\n')) {
+ lines.push(style(` ${sign} ${escapeControls(line)}`, color))
+ }
+ }
+ return lines
+}
+
+export function variableLines(changes: VariableChange[], style: Styler): string[] {
+ if (changes.length === 0) {
+ return []
+ }
+ return [
+ 'Variables:',
+ ...changes.map((change) => {
+ // A name can come from the endpoint in PostHog, which another member can edit.
+ const name = escapeControls(change.name)
+ if (change.change === 'add') {
+ return style(` + ${name} (${escapeControls(change.type ?? '')})`, 'green')
+ }
+ if (change.change === 'retype') {
+ return style(
+ ` ~ ${name} (${escapeControls(change.from ?? '')} → ${escapeControls(change.type ?? '')})`,
+ 'yellow'
+ )
+ }
+ return style(` - ${name}`, 'red')
+ }),
+ ]
+}
+
+export function actionLabel(action: 'create' | 'update' | 'skip', style: Styler): string {
+ const labels = {
+ create: style('create', 'green', 'bold'),
+ update: style('update', 'yellow', 'bold'),
+ skip: style('skip ', 'dim'),
+ }
+ return labels[action]
+}
+
+export function problemLines(problems: FileProblem[], style: Styler): string[] {
+ return problems.map((problem) => `${style('Skipped', 'yellow', 'bold')} ${problem.path}: ${problem.message}`)
+}
+
+export function indent(lines: string[], by = ' '): string[] {
+ return lines.map((line) => `${by}${line}`)
+}
diff --git a/hog/src/commands/index.ts b/hog/src/commands/index.ts
index 72a8155c179b..daf260593667 100644
--- a/hog/src/commands/index.ts
+++ b/hog/src/commands/index.ts
@@ -4,6 +4,7 @@ import api from './api'
import auth from './auth'
import commands from './commands'
import config from './config'
+import endpoints from './endpoints'
import errorTracking from './error-tracking'
import { LEGACY_COMMANDS } from './legacy'
import query from './query'
@@ -14,6 +15,7 @@ export const COMMANDS: CommandTree = {
query,
api,
'error-tracking': errorTracking,
+ endpoints,
schema,
config,
commands,
diff --git a/hog/src/commands/legacy.ts b/hog/src/commands/legacy.ts
index 3af0e3e1ede0..8393383729b6 100644
--- a/hog/src/commands/legacy.ts
+++ b/hog/src/commands/legacy.ts
@@ -1,7 +1,6 @@
import { defineLegacy, type CommandTree } from '@/core/command'
export const LEGACY_COMMANDS: CommandTree = {
- endpoints: defineLegacy({ description: 'Manage PostHog endpoints', use: 'posthog-cli exp endpoints' }),
logs: defineLegacy({
description: 'Import historical logs from another log store into PostHog',
use: 'posthog-cli exp logs',
diff --git a/hog/src/commands/schema/pull.ts b/hog/src/commands/schema/pull.ts
index 3606d7bb44ba..253819dbfbc1 100644
--- a/hog/src/commands/schema/pull.ts
+++ b/hog/src/commands/schema/pull.ts
@@ -1,19 +1,10 @@
import { defineCommand } from '@/core/command'
import { updateConfig, type SchemaLanguage } from '@/core/config'
import { EXIT_USAGE, HogError } from '@/core/errors'
+import { absolutePath, storedPath } from '@/core/paths'
import { plural } from '@/core/text'
-import {
- absolutePath,
- chosenFile,
- configRoot,
- fetchDefinitions,
- isLanguage,
- LANGUAGE_INFO,
- LANGUAGES,
- storedPath,
- type Language,
-} from './shared'
+import { chosenFile, configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO, LANGUAGES, type Language } from './shared'
interface PulledLanguage {
language: Language
diff --git a/hog/src/commands/schema/shared.ts b/hog/src/commands/schema/shared.ts
index f75c46887e42..8bda0d10d3a0 100644
--- a/hog/src/commands/schema/shared.ts
+++ b/hog/src/commands/schema/shared.ts
@@ -1,7 +1,8 @@
-import { isAbsolute, join, relative, resolve } from 'node:path'
+import { join } from 'node:path'
import type { LoadedConfig } from '@/core/config'
import type { Context } from '@/core/context'
+import { absolutePath } from '@/core/paths'
export const LANGUAGES = ['typescript', 'golang', 'python'] as const
export type Language = (typeof LANGUAGES)[number]
@@ -62,16 +63,6 @@ export function configRoot(ctx: Context, loaded: LoadedConfig | undefined): stri
return loaded?.root ?? ctx.runtime.cwd()
}
-export function absolutePath(root: string, path: string): string {
- return isAbsolute(path) ? path : resolve(root, path)
-}
-
-// A sibling folder stays relative, as posthog-cli stored it, so the file works in any checkout.
-export function storedPath(root: string, path: string): string {
- const rel = relative(root, path)
- return isAbsolute(rel) ? path : rel
-}
-
// Resolves a path the caller typed. A folder, or a path that ends with a slash, gets the
// language's default file name.
export async function chosenFile(ctx: Context, path: string, language: Language): Promise<string> {
diff --git a/hog/src/commands/schema/status.ts b/hog/src/commands/schema/status.ts
index f921f9bc094a..abc9b4c73af1 100644
--- a/hog/src/commands/schema/status.ts
+++ b/hog/src/commands/schema/status.ts
@@ -1,7 +1,8 @@
import { defineCommand } from '@/core/command'
+import { absolutePath } from '@/core/paths'
import { plural } from '@/core/text'
-import { absolutePath, configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO } from './shared'
+import { configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO } from './shared'
interface LanguageStatus {
language: string
diff --git a/hog/src/core/command.ts b/hog/src/core/command.ts
index 44b30b639e51..dd36f97e9b07 100644
--- a/hog/src/core/command.ts
+++ b/hog/src/core/command.ts
@@ -20,6 +20,8 @@ export type OptionSpec =
// The name shown in help, as in `--host <url>`. Defaults to the option name.
placeholder?: string
choices?: readonly string[]
+ // The option can repeat, as in `--var a=1 --var b=2`, and its value is a list.
+ multiple?: boolean
}
type ArgumentValues<Args> = {
@@ -33,7 +35,9 @@ type ArgumentValues<Args> = {
export type OptionValues<Options> = {
[Name in keyof Options]: Options[Name] extends { type: 'boolean' }
? boolean | undefined
- : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined
+ : Options[Name] extends { multiple: true }
+ ? string[] | undefined
+ : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined
}
interface CommandInput<Args, Options> {
diff --git a/hog/src/core/config.ts b/hog/src/core/config.ts
index 7d032654d99d..4d70d36d2c9d 100644
--- a/hog/src/core/config.ts
+++ b/hog/src/core/config.ts
@@ -64,6 +64,18 @@ export const PostHogConfig = z
.strictObject({
$schema: z.string().optional().describe('The JSON schema for this file.'),
errorTracking: ErrorTracking.optional(),
+ endpoints: z
+ .strictObject({
+ dir: z
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ 'The folder of endpoint YAML files, relative to posthog.json. `hog endpoints pull` writes there, and `push` and `diff` read it when no path is passed.'
+ ),
+ })
+ .optional()
+ .describe('Settings for `hog endpoints`.'),
languages: z
.record(z.string(), SchemaLanguage)
.optional()
diff --git a/hog/src/core/manifest.ts b/hog/src/core/manifest.ts
index e89c977b1293..a9df11756cca 100644
--- a/hog/src/core/manifest.ts
+++ b/hog/src/core/manifest.ts
@@ -7,6 +7,7 @@ interface OptionEntry {
description: string
takesValue: boolean
choices?: readonly string[]
+ repeatable?: boolean
}
export interface ManifestEntry {
@@ -27,6 +28,7 @@ function describeOptions(options: Readonly<Record<string, OptionSpec>>): OptionE
description: spec.description,
takesValue: spec.type === 'string',
choices: spec.type === 'string' ? spec.choices : undefined,
+ repeatable: spec.type === 'string' && spec.multiple === true ? true : undefined,
}))
}
diff --git a/hog/src/core/paths.ts b/hog/src/core/paths.ts
new file mode 100644
index 000000000000..cb8ef7343f36
--- /dev/null
+++ b/hog/src/core/paths.ts
@@ -0,0 +1,12 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+export function absolutePath(root: string, path: string): string {
+ return isAbsolute(path) ? path : resolve(root, path)
+}
+
+// The path to store in posthog.json, relative to its folder. A sibling folder stays relative, as
+// posthog-cli stored it, so the file works in any checkout.
+export function storedPath(root: string, path: string): string {
+ const rel = relative(root, path)
+ return isAbsolute(rel) ? path : rel
+}
diff --git a/hog/src/core/prompts.ts b/hog/src/core/prompts.ts
index 75e72d589b9f..d965885a916b 100644
--- a/hog/src/core/prompts.ts
+++ b/hog/src/core/prompts.ts
@@ -25,6 +25,7 @@ export interface Prompts {
): Promise<Value>
text(message: string, options?: { initialValue?: string; validate?: Validate }): Promise<string>
password(message: string, options?: { validate?: Validate }): Promise<string>
+ confirm(message: string, options?: { initialValue?: boolean }): Promise<boolean>
note(message: string, title: string): void
spinner(message: string): Spinner
}
@@ -68,6 +69,9 @@ export function clackPrompts(): Prompts {
await clack.password({ message, validate: validate ? (value) => validate(value ?? '') : undefined })
)
},
+ async confirm(message, options = {}) {
+ return answer(await clack.confirm({ message, initialValue: options.initialValue ?? true }))
+ },
note(message, title) {
clack.note(message, title)
},
diff --git a/hog/src/core/runtime.ts b/hog/src/core/runtime.ts
index b230812760b0..261541eb5360 100644
--- a/hog/src/core/runtime.ts
+++ b/hog/src/core/runtime.ts
@@ -1,5 +1,5 @@
import { randomUUID } from 'node:crypto'
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { access, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
import { homedir } from 'node:os'
import { dirname } from 'node:path'
@@ -28,6 +28,10 @@ export interface Runtime {
exists: (path: string) => Promise<boolean>
readFile: (path: string) => Promise<string>
isDirectory: (path: string) => Promise<boolean>
+ // The names of the files directly in a folder, sorted. Folders inside it are left out.
+ listFiles: (folder: string) => Promise<string[]>
+ // The files under `cwd` that match a glob pattern, as paths relative to it, sorted.
+ glob: (pattern: string, cwd: string) => Promise<string[]>
// Writes a project file, such as a generated SDK, and creates the folders above it.
writeFile: (path: string, contents: string) => Promise<void>
writePrivateFile: (path: string, contents: string) => Promise<void>
@@ -89,6 +93,15 @@ export function processRuntime(): Runtime {
(stats) => stats.isDirectory(),
() => false
),
+ listFiles: async (folder) => {
+ const entries = await readdir(folder, { withFileTypes: true })
+ return entries
+ .filter((entry) => entry.isFile())
+ .map((entry) => entry.name)
+ .sort()
+ },
+ glob: async (pattern, cwd) =>
+ (await Array.fromAsync(new Bun.Glob(pattern).scan({ cwd, onlyFiles: true }))).sort(),
writeFile: async (path, contents) => {
await mkdir(dirname(path), { recursive: true })
await writeFile(path, contents)
diff --git a/hog/src/endpoints/api.ts b/hog/src/endpoints/api.ts
new file mode 100644
index 000000000000..b4ca0daf20e1
--- /dev/null
+++ b/hog/src/endpoints/api.ts
@@ -0,0 +1,47 @@
+import type { PostHogApi } from '@/posthog/api'
+
+import type { Endpoint, InsightVariable } from './model'
+
+interface Page<T> {
+ results: T[]
+ next?: string | null
+}
+
+// Follows `next` links, so a project with more endpoints than one page holds still gets all of them.
+async function all<T>(api: PostHogApi, path: string): Promise<T[]> {
+ const results: T[] = []
+ let next: string | null | undefined = path
+ while (next) {
+ const page: Page<T> = await api.get<Page<T>>(next)
+ results.push(...page.results)
+ next = page.next ? new URL(page.next).pathname + new URL(page.next).search : undefined
+ }
+ return results
+}
+
+export function listEndpoints(api: PostHogApi): Promise<Endpoint[]> {
+ return all<Endpoint>(api, 'endpoints/')
+}
+
+export function getEndpoint(api: PostHogApi, name: string): Promise<Endpoint> {
+ return api.get<Endpoint>(`endpoints/${encodeURIComponent(name)}/`)
+}
+
+export function listInsightVariables(api: PostHogApi): Promise<InsightVariable[]> {
+ return all<InsightVariable>(api, 'insight_variables/')
+}
+
+export function createInsightVariable(
+ api: PostHogApi,
+ variable: { code_name: string; type: string; default_value?: unknown; is_multi?: boolean }
+): Promise<InsightVariable> {
+ return api.post<InsightVariable>('insight_variables/', { name: variable.code_name, ...variable })
+}
+
+export function createEndpoint(api: PostHogApi, body: Record<string, unknown>): Promise<Endpoint> {
+ return api.post<Endpoint>('endpoints/', body)
+}
+
+export function updateEndpoint(api: PostHogApi, name: string, body: Record<string, unknown>): Promise<Endpoint> {
+ return api.patch<Endpoint>(`endpoints/${encodeURIComponent(name)}/`, body)
+}
diff --git a/hog/src/endpoints/changes.ts b/hog/src/endpoints/changes.ts
new file mode 100644
index 000000000000..61d4acab2d7d
--- /dev/null
+++ b/hog/src/endpoints/changes.ts
@@ -0,0 +1,100 @@
+import {
+ isPlainHogql,
+ remoteVariableNames,
+ remoteVariableValues,
+ scheduleFor,
+ withoutNulls,
+ type Endpoint,
+ type EndpointFile,
+} from './model'
+
+export type ChangeField = 'description' | 'query' | 'materialization' | 'schedule' | 'variables' | 'defaults'
+
+// One field that differs between a local file and PostHog. Push reads it from remote to local,
+// pull from local to remote.
+export interface Change {
+ field: ChangeField
+ local: string
+ remote: string
+}
+
+function sortKeys(value: unknown): unknown {
+ if (Array.isArray(value)) {
+ return value.map(sortKeys)
+ }
+ if (value !== null && typeof value === 'object') {
+ return Object.fromEntries(
+ Object.keys(value)
+ .sort()
+ .map((key) => [key, sortKeys((value as Record<string, unknown>)[key])])
+ )
+ }
+ return value
+}
+
+// PostHog stores variables inside the query, under IDs a file never names, so they're compared on their own.
+function comparableQuery(query: Record<string, unknown>): string {
+ if (isPlainHogql(query) && typeof query.query === 'string') {
+ return query.query.replace(/\r\n?/g, '\n')
+ }
+ const { variables: _variables, ...rest } = query
+ return JSON.stringify(sortKeys(withoutNulls(rest)), null, 2)
+}
+
+export function localQuery(file: EndpointFile): string {
+ return file.query?.replace(/\r\n?/g, '\n') ?? comparableQuery(file.query_definition ?? {})
+}
+
+export function remoteQuery(endpoint: Endpoint): string {
+ return comparableQuery(endpoint.query)
+}
+
+const sameSet = (a: string[], b: string[]): boolean =>
+ a.length === b.length && [...a].sort().every((value, index) => value === [...b].sort()[index])
+
+export function compare(file: EndpointFile, endpoint: Endpoint): Change[] {
+ const changes: Change[] = []
+ const add = (field: ChangeField, local: string, remote: string): void => {
+ if (local !== remote) {
+ changes.push({ field, local, remote })
+ }
+ }
+ add('description', file.description ?? '', endpoint.description ?? '')
+ add('query', localQuery(file), remoteQuery(endpoint))
+ add(
+ 'materialization',
+ file.materialization?.enabled ? 'enabled' : 'disabled',
+ endpoint.is_materialized ? 'enabled' : 'disabled'
+ )
+ // PostHog keeps the refresh interval after materialization is turned off, so it only counts while on.
+ const remoteSchedule = endpoint.is_materialized ? scheduleFor(endpoint.data_freshness_seconds) : undefined
+ const localSchedule = file.materialization?.enabled ? file.materialization.schedule : undefined
+ // A push without a schedule keeps the one PostHog has, so a file that names none matches any.
+ if (localSchedule !== undefined) {
+ add('schedule', localSchedule, remoteSchedule ?? '')
+ }
+ const localVariables = (file.variables ?? []).map((variable) => variable.name)
+ const remoteVariables = remoteVariableNames(endpoint)
+ if (!sameSet(localVariables, remoteVariables)) {
+ changes.push({ field: 'variables', local: localVariables.join(', '), remote: remoteVariables.join(', ') })
+ }
+ // A variable without a default in the file takes the project's, so only the defaults a file sets count.
+ const remoteValues = remoteVariableValues(endpoint)
+ const show = (value: unknown): string => JSON.stringify(sortKeys(value ?? null))
+ const changedDefaults = (file.variables ?? []).filter(
+ (variable) =>
+ variable.default !== undefined &&
+ remoteValues.has(variable.name) &&
+ show(variable.default) !== show(remoteValues.get(variable.name))
+ )
+ if (changedDefaults.length > 0) {
+ changes.push({
+ field: 'defaults',
+ local: changedDefaults.map((variable) => `${variable.name}=${show(variable.default)}`).join(', '),
+ remote: changedDefaults
+ .map((variable) => `${variable.name}=${show(remoteValues.get(variable.name))}`)
+ .join(', '),
+ })
+ }
+ return changes
+}
diff --git a/hog/src/endpoints/files.ts b/hog/src/endpoints/files.ts
new file mode 100644
index 000000000000..ff6b804f3c28
--- /dev/null
+++ b/hog/src/endpoints/files.ts
@@ -0,0 +1,66 @@
+import { relative } from 'node:path'
+import { parse } from 'yaml'
+
+import { absolutePath } from '@/core/paths'
+import type { Runtime } from '@/core/runtime'
+
+import { EndpointFile } from './model'
+
+export interface LocalEndpoint {
+ path: string
+ file: EndpointFile
+}
+
+export interface FileProblem {
+ path: string
+ message: string
+}
+
+const isYaml = (name: string): boolean => /\.ya?ml$/i.test(name)
+
+// Reads the endpoint files in the given files, folders (not recursive) and glob patterns. A file
+// that doesn't parse is a problem to report, not a reason to stop the others.
+export async function readEndpointFiles(
+ runtime: Runtime,
+ paths: readonly string[]
+): Promise<{ endpoints: LocalEndpoint[]; problems: FileProblem[] }> {
+ const cwd = runtime.cwd()
+ const found: string[] = []
+ const problems: FileProblem[] = []
+ for (const path of paths) {
+ const absolute = absolutePath(cwd, path)
+ if (await runtime.isDirectory(absolute)) {
+ const names = (await runtime.listFiles(absolute)).filter(isYaml)
+ found.push(...names.map((name) => `${absolute.replace(/\/$/, '')}/${name}`))
+ } else if (await runtime.exists(absolute)) {
+ found.push(absolute)
+ } else {
+ const matches = await runtime.glob(path, cwd)
+ if (matches.length === 0) {
+ problems.push({ path, message: 'No such file or folder' })
+ }
+ found.push(...matches.map((match) => absolutePath(cwd, match)))
+ }
+ }
+
+ const endpoints: LocalEndpoint[] = []
+ for (const absolute of new Set(found)) {
+ const path = relative(cwd, absolute) || absolute
+ let raw: unknown
+ try {
+ raw = parse(await runtime.readFile(absolute))
+ } catch (error) {
+ problems.push({ path, message: `Not valid YAML: ${error instanceof Error ? error.message : error}` })
+ continue
+ }
+ const parsed = EndpointFile.safeParse(raw)
+ if (parsed.success) {
+ endpoints.push({ path, file: parsed.data })
+ } else {
+ const [issue] = parsed.error.issues
+ const where = issue?.path.length ? `${issue.path.join('.')}: ` : ''
+ problems.push({ path, message: `${where}${issue?.message ?? 'not an endpoint file'}` })
+ }
+ }
+ return { endpoints, problems }
+}
diff --git a/hog/src/endpoints/model.ts b/hog/src/endpoints/model.ts
new file mode 100644
index 000000000000..2e9eee95975e
--- /dev/null
+++ b/hog/src/endpoints/model.ts
@@ -0,0 +1,260 @@
+import { z } from 'zod'
+
+// The materialization schedules PostHog accepts, as posthog-cli writes them, with their refresh interval.
+export const SCHEDULES = {
+ '15min': 900,
+ '30min': 1800,
+ '1hour': 3600,
+ '6hour': 21600,
+ '12hour': 43200,
+ '24hour': 86400,
+ '7day': 604800,
+} as const
+
+export type Schedule = keyof typeof SCHEDULES
+
+export const SCHEDULE_LABELS: Record<Schedule, string> = {
+ '15min': 'every 15 min',
+ '30min': 'every 30 min',
+ '1hour': 'hourly',
+ '6hour': 'every 6 hours',
+ '12hour': 'every 12 hours',
+ '24hour': 'daily',
+ '7day': 'weekly',
+}
+
+export function scheduleFor(seconds: number | null | undefined): Schedule | undefined {
+ return (Object.keys(SCHEDULES) as Schedule[]).find((schedule) => SCHEDULES[schedule] === seconds)
+}
+
+// The same fields and names as the files posthog-cli writes, so either CLI reads the other's files.
+export const EndpointFile = z
+ .strictObject({
+ name: z.string().min(1, 'name is required'),
+ description: z.string().optional(),
+ query: z.string().optional(),
+ query_definition: z.record(z.string(), z.unknown()).optional(),
+ variables: z
+ .array(
+ z.strictObject({
+ name: z.string().min(1),
+ type: z.string().min(1),
+ default: z.unknown().optional(),
+ })
+ )
+ .optional(),
+ materialization: z
+ .strictObject({
+ enabled: z.boolean().default(false),
+ schedule: z
+ .enum(Object.keys(SCHEDULES) as [Schedule, ...Schedule[]], {
+ error: `schedule must be one of ${Object.keys(SCHEDULES).join(', ')}`,
+ })
+ .optional(),
+ })
+ .optional(),
+ })
+ .refine((file) => file.query !== undefined || file.query_definition !== undefined, {
+ message: 'the file needs a query or a query_definition',
+ })
+
+export type EndpointFile = z.infer<typeof EndpointFile>
+export type EndpointVariable = NonNullable<EndpointFile['variables']>[number]
+
+export interface MaterializationStatus {
+ status?: string | null
+ can_materialize?: boolean
+ last_materialized_at?: string | null
+ error?: string | null
+ reason?: string | null
+}
+
+export interface Endpoint {
+ id: string
+ name: string
+ description?: string | null
+ query: Record<string, unknown>
+ is_active: boolean
+ data_freshness_seconds?: number | null
+ endpoint_path?: string
+ url?: string | null
+ ui_url?: string | null
+ created_at: string
+ updated_at: string
+ is_materialized: boolean
+ current_version?: number
+ versions_count?: number
+ materialization?: MaterializationStatus | null
+}
+
+export interface InsightVariable {
+ id: string
+ name: string
+ code_name: string
+ type: string
+ default_value?: unknown
+}
+
+const VARIABLE_REFERENCE = /\{variables\.([a-zA-Z_][a-zA-Z0-9_]*)\}/g
+
+// The HogQL text of a file: the `query` string, or the `query` field of a HogQL query definition.
+export function hogqlOf(file: EndpointFile): string {
+ const fromDefinition = file.query_definition?.query
+ return file.query ?? (typeof fromDefinition === 'string' ? fromDefinition : '')
+}
+
+export function variableReferences(query: string): string[] {
+ return [...new Set(Array.from(query.matchAll(VARIABLE_REFERENCE), (match) => match[1]!))]
+}
+
+export function remoteHogql(endpoint: Endpoint): string {
+ return typeof endpoint.query.query === 'string' ? endpoint.query.query : ''
+}
+
+// A variable's value on the endpoint, by code name.
+export function remoteVariableValues(endpoint: Endpoint): Map<string, unknown> {
+ const variables = (endpoint.query.variables ?? {}) as Record<string, { code_name?: unknown; value?: unknown }>
+ return new Map(
+ Object.values(variables)
+ .filter((variable) => typeof variable.code_name === 'string')
+ .map((variable) => [variable.code_name as string, variable.value])
+ )
+}
+
+// posthog-cli writes the lowercase type it infers from a default. PostHog only accepts its own type names.
+const API_VARIABLE_TYPES: Record<string, string> = {
+ string: 'String',
+ integer: 'Number',
+ number: 'Number',
+ boolean: 'Boolean',
+ array: 'List',
+ list: 'List',
+ date: 'Date',
+}
+
+export function apiVariableType(type: string): string {
+ return API_VARIABLE_TYPES[type.toLowerCase()] ?? type
+}
+
+// A HogQL query can hold settings besides its text, such as `connectionId` or `filters`. A file
+// keeps only the text when there are none, so that a push never drops them.
+export function isPlainHogql(query: Record<string, unknown>): boolean {
+ return (
+ query.kind === 'HogQLQuery' &&
+ typeof query.query === 'string' &&
+ Object.entries(query).every(
+ ([key, value]) =>
+ ['kind', 'query', 'variables'].includes(key) ||
+ value === null ||
+ (typeof value === 'object' && Object.keys(value).length === 0)
+ )
+ )
+}
+
+export function remoteVariableNames(endpoint: Endpoint | undefined): string[] {
+ const variables = endpoint?.query.variables
+ if (!variables || typeof variables !== 'object') {
+ return []
+ }
+ return Object.values(variables as Record<string, { code_name?: unknown }>)
+ .map((variable) => variable.code_name)
+ .filter((name): name is string => typeof name === 'string')
+}
+
+function inferType(value: unknown): string {
+ if (typeof value === 'number') {
+ return Number.isInteger(value) ? 'integer' : 'number'
+ }
+ if (typeof value === 'boolean') {
+ return 'boolean'
+ }
+ if (Array.isArray(value)) {
+ return 'array'
+ }
+ return value !== null && typeof value === 'object' ? 'object' : 'string'
+}
+
+// Query definitions come back with every optional field set to null. Dropping them keeps pulled
+// files short, and PostHog fills the same defaults back in on push.
+export function withoutNulls(value: unknown): unknown {
+ if (Array.isArray(value)) {
+ return value.map(withoutNulls)
+ }
+ if (value !== null && typeof value === 'object') {
+ return Object.fromEntries(
+ Object.entries(value)
+ .filter(([, child]) => child !== null)
+ .map(([key, child]) => [key, withoutNulls(child)])
+ )
+ }
+ return value
+}
+
+// `types` maps a variable's code name to its type in the project. Without it, the type comes from the default value.
+export function fileFromEndpoint(endpoint: Endpoint, types: ReadonlyMap<string, string> = new Map()): EndpointFile {
+ const file: EndpointFile = { name: endpoint.name }
+ if (endpoint.description) {
+ file.description = endpoint.description
+ }
+ if (isPlainHogql(endpoint.query) && typeof endpoint.query.query === 'string') {
+ file.query = endpoint.query.query.replace(/\r\n?/g, '\n')
+ } else {
+ const { variables: _variables, ...definition } = endpoint.query
+ file.query_definition = withoutNulls(definition) as Record<string, unknown>
+ }
+ const variables = Object.values((endpoint.query.variables ?? {}) as Record<string, Record<string, unknown>>)
+ .filter((variable) => typeof variable.code_name === 'string')
+ .map((variable) => ({
+ name: variable.code_name as string,
+ type: types.get(variable.code_name as string) ?? inferType(variable.value),
+ ...(variable.value !== undefined ? { default: variable.value } : {}),
+ }))
+ if (variables.length > 0) {
+ file.variables = variables
+ }
+ if (endpoint.is_materialized) {
+ const schedule = scheduleFor(endpoint.data_freshness_seconds)
+ file.materialization = { enabled: true, ...(schedule ? { schedule } : {}) }
+ }
+ return file
+}
+
+export type ResolvedVariables = Map<string, InsightVariable>
+
+// The request body for creating or updating the endpoint a file describes.
+export function requestBody(file: EndpointFile, resolved: ResolvedVariables): Record<string, unknown> {
+ const query: Record<string, unknown> = file.query_definition
+ ? { ...file.query_definition }
+ : { kind: 'HogQLQuery', query: file.query }
+ const variables = Object.fromEntries(
+ (file.variables ?? []).flatMap((variable) => {
+ const resolvedVariable = resolved.get(variable.name)
+ if (!resolvedVariable) {
+ return []
+ }
+ const entry: Record<string, unknown> = {
+ variableId: resolvedVariable.id,
+ code_name: resolvedVariable.code_name,
+ }
+ if (variable.default !== undefined) {
+ entry.value = variable.default
+ // Without `isNull`, PostHog replaces a null value with the project's default.
+ if (variable.default === null) {
+ entry.isNull = true
+ }
+ }
+ return [[resolvedVariable.id, entry]]
+ })
+ )
+ if (Object.keys(variables).length > 0) {
+ query.variables = variables
+ }
+ // PostHog keeps the description when the field is missing, so a file without one sends it empty.
+ const body: Record<string, unknown> = { name: file.name, description: file.description ?? '', query }
+ // A file without materialization turns it off, or the endpoint would differ from the file forever.
+ body.is_materialized = file.materialization?.enabled ?? false
+ if (file.materialization?.schedule) {
+ body.data_freshness_seconds = SCHEDULES[file.materialization.schedule]
+ }
+ return body
+}
diff --git a/hog/src/endpoints/plan.ts b/hog/src/endpoints/plan.ts
new file mode 100644
index 000000000000..78eb79008a33
--- /dev/null
+++ b/hog/src/endpoints/plan.ts
@@ -0,0 +1,188 @@
+import type { PostHogApi } from '@/posthog/api'
+
+import { createEndpoint, createInsightVariable, updateEndpoint } from './api'
+import { compare, type Change } from './changes'
+import type { LocalEndpoint } from './files'
+import {
+ apiVariableType,
+ hogqlOf,
+ remoteVariableNames,
+ requestBody,
+ variableReferences,
+ type Endpoint,
+ type EndpointFile,
+ type InsightVariable,
+ type ResolvedVariables,
+} from './model'
+
+export interface VariableChange {
+ name: string
+ change: 'add' | 'remove' | 'retype'
+ type?: string
+ from?: string
+}
+
+export interface PushItem {
+ name: string
+ path: string
+ action: 'create' | 'update' | 'skip'
+ reason?: string
+ // PostHog would reject the file, so the push fails.
+ invalid?: boolean
+ changes: Change[]
+ variables: VariableChange[]
+ file: EndpointFile
+}
+
+function variableChanges(
+ file: EndpointFile,
+ remoteNames: string[],
+ existing: Map<string, InsightVariable>
+): VariableChange[] {
+ const changes: VariableChange[] = []
+ for (const variable of file.variables ?? []) {
+ const known = existing.get(variable.name)
+ if (!remoteNames.includes(variable.name)) {
+ changes.push({ name: variable.name, change: 'add', type: variable.type })
+ } else if (known && known.type !== apiVariableType(variable.type)) {
+ changes.push({ name: variable.name, change: 'retype', type: variable.type, from: known.type })
+ }
+ }
+ const localNames = new Set((file.variables ?? []).map((variable) => variable.name))
+ for (const name of remoteNames.filter((remote) => !localNames.has(remote))) {
+ changes.push({ name, change: 'remove' })
+ }
+ return changes
+}
+
+// Why PostHog would reject the file, checked before anything is sent.
+function rejection(file: EndpointFile, remoteNames: string[]): string | undefined {
+ const references = variableReferences(hogqlOf(file))
+ const localNames = (file.variables ?? []).map((variable) => variable.name)
+ const removedButUsed = remoteNames.filter((name) => !localNames.includes(name) && references.includes(name))
+ if (removedButUsed.length > 0) {
+ return `The query still uses removed variables: ${removedButUsed.join(', ')}`
+ }
+ const unused = localNames.filter((name) => !references.includes(name))
+ if (unused.length > 0) {
+ return `The query doesn't use these variables, so remove them from the file: ${unused.join(', ')}`
+ }
+ return undefined
+}
+
+export function planPush(locals: LocalEndpoint[], remotes: Endpoint[], variables: InsightVariable[]): PushItem[] {
+ const remoteByName = new Map(remotes.map((endpoint) => [endpoint.name, endpoint]))
+ const existing = new Map(variables.map((variable) => [variable.code_name, variable]))
+ const seen = new Map<string, string>()
+ return locals.map(({ path, file }): PushItem => {
+ const remote = remoteByName.get(file.name)
+ const remoteNames = remoteVariableNames(remote)
+ const base = { name: file.name, path, file, changes: [], variables: [] }
+ const duplicate = seen.get(file.name)
+ if (duplicate) {
+ return { ...base, action: 'skip', invalid: true, reason: `${duplicate} defines the same endpoint` }
+ }
+ seen.set(file.name, path)
+ const reason = rejection(file, remoteNames)
+ if (reason) {
+ return { ...base, action: 'skip', invalid: true, reason }
+ }
+ const variableDiff = variableChanges(file, remoteNames, existing)
+ if (!remote) {
+ return { ...base, action: 'create', variables: variableDiff }
+ }
+ const changes = compare(file, remote)
+ // PostHog keeps a variable's type when an endpoint changes, so a type change alone is nothing to push.
+ const retyped = variableDiff.filter((change) => change.change === 'retype')
+ if (changes.length === 0 && variableDiff.length === retyped.length) {
+ const reason = retyped.length
+ ? `No changes hog can push. Change the type of ${retyped.map((change) => change.name).join(', ')} in PostHog`
+ : 'No changes'
+ return { ...base, action: 'skip', reason, variables: retyped }
+ }
+ return { ...base, action: 'update', changes, variables: variableDiff }
+ })
+}
+
+export interface PushOutcome {
+ name: string
+ path: string
+ status: 'created' | 'updated' | 'failed'
+ uiUrl?: string | null
+ error?: string
+}
+
+// Creates the variables a file adds that the project doesn't have yet, then the endpoint. A
+// failure stops only its own endpoint.
+export async function applyPush(
+ api: PostHogApi,
+ items: PushItem[],
+ variables: InsightVariable[]
+): Promise<PushOutcome[]> {
+ const known = new Map(variables.map((variable) => [variable.code_name, variable]))
+ const outcomes: PushOutcome[] = []
+ for (const item of items) {
+ if (item.action === 'skip') {
+ continue
+ }
+ try {
+ const resolved: ResolvedVariables = new Map()
+ for (const variable of item.file.variables ?? []) {
+ let insightVariable = known.get(variable.name)
+ if (!insightVariable) {
+ insightVariable = await createInsightVariable(api, {
+ code_name: variable.name,
+ type: apiVariableType(variable.type),
+ ...(variable.default !== undefined ? { default_value: variable.default } : {}),
+ // A single-selection list keeps only the first value of an array default.
+ ...(Array.isArray(variable.default) ? { is_multi: true } : {}),
+ })
+ known.set(variable.name, insightVariable)
+ }
+ resolved.set(variable.name, insightVariable)
+ }
+ const body = requestBody(item.file, resolved)
+ const saved =
+ item.action === 'create' ? await createEndpoint(api, body) : await updateEndpoint(api, item.name, body)
+ outcomes.push({
+ name: item.name,
+ path: item.path,
+ status: item.action === 'create' ? 'created' : 'updated',
+ uiUrl: saved.ui_url,
+ })
+ } catch (error) {
+ outcomes.push({
+ name: item.name,
+ path: item.path,
+ status: 'failed',
+ error: error instanceof Error ? error.message : String(error),
+ })
+ }
+ }
+ return outcomes
+}
+
+export interface PullItem {
+ name: string
+ path: string
+ action: 'create' | 'update' | 'skip'
+ reason?: string
+ changes: Change[]
+ endpoint: Endpoint
+}
+
+// An endpoint a local file already defines updates that file in place. Any other goes to
+// `<folder>/<name>.yaml`, or to `file` when the target is a single YAML file.
+export function planPull(remotes: Endpoint[], locals: LocalEndpoint[], pathFor: (name: string) => string): PullItem[] {
+ const localByName = new Map(locals.map((local) => [local.file.name, local]))
+ return remotes.map((endpoint): PullItem => {
+ const local = localByName.get(endpoint.name)
+ if (!local) {
+ return { name: endpoint.name, path: pathFor(endpoint.name), action: 'create', changes: [], endpoint }
+ }
+ const changes = compare(local.file, endpoint)
+ return changes.length === 0
+ ? { name: endpoint.name, path: local.path, action: 'skip', reason: 'No changes', changes, endpoint }
+ : { name: endpoint.name, path: local.path, action: 'update', changes, endpoint }
+ })
+}
diff --git a/hog/src/testing.ts b/hog/src/testing.ts
index a45e7c27a63f..d23762a2259e 100644
--- a/hog/src/testing.ts
+++ b/hog/src/testing.ts
@@ -45,6 +45,7 @@ function fakePrompts(answers: string[]): Prompts {
select: (message) => next(message) as never,
text: (message) => next(message),
password: (message) => next(message),
+ confirm: async (message) => (await next(message)) === 'yes',
note: () => {},
spinner: () => ({ stop: () => {}, error: () => {} }),
}
@@ -103,6 +104,21 @@ export function fakeRuntime(options: FakeRuntimeOptions = {}): FakeRuntime {
options.useDisk
? existsSync(path) && statSync(path).isDirectory()
: Object.keys(files).some((file) => file.startsWith(`${path.replace(/\/$/, '')}/`)),
+ listFiles: async (folder) => {
+ const prefix = `${folder.replace(/\/$/, '')}/`
+ return Object.keys(files)
+ .filter((file) => file.startsWith(prefix) && !file.slice(prefix.length).includes('/'))
+ .map((file) => file.slice(prefix.length))
+ .sort()
+ },
+ glob: async (pattern, cwd) => {
+ const prefix = `${cwd.replace(/\/$/, '')}/`
+ const glob = new Bun.Glob(pattern)
+ return Object.keys(files)
+ .filter((file) => file.startsWith(prefix) && glob.match(file.slice(prefix.length)))
+ .map((file) => file.slice(prefix.length))
+ .sort()
+ },
writeFile: async (path, contents) => {
files[path] = contents
},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e3493e0f684e..3382f85e2a30 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1532,9 +1532,15 @@ importers:
commander:
specifier: 15.0.0
version: 15.0.0
+ diff:
+ specifier: 8.0.4
+ version: 8.0.4
pako:
specifier: 2.1.0
version: 2.1.0
+ yaml:
+ specifier: 2.9.0
+ version: 2.9.0
zod:
specifier: ^4.3.6
version: 4.3.6