:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
#!/usr/bin/env node
import { createExecTool, formatInputValidationError, repairArgumentNesting } from '@/tools/exec'
import type { Context, Tool, ZodObjectAny } from '@/tools/types'
import { buildAgentHelp } from './agent-help'
import { installAgentsMdSnippet } from './agents-md'
import { takeOption } from './args'
import type { CliConfig } from './config'
import { resolveCliConfig, requireApiKey } from './config'
import { buildCliContext, flushAnalytics } from './context'
import { installSkill, listSkills } from './skills'
import { trackCliToolCall } from './tool-call-properties'
import { getCliTools } from './tools'
const COMMAND_REFERENCE = `CLI-style command string. Supported commands:
tools
search <regex_pattern>
info [--json] <tool_name>
schema <tool_name> [field_path]
call [--json] [--confirm] <tool_name> [json_input]`
interface BuiltExec {
context: Context
execTool: Tool<ZodObjectAny>
tools: Tool<ZodObjectAny>[]
}
interface BuiltStaticExec {
execTool: Tool<ZodObjectAny>
tools: Tool<ZodObjectAny>[]
}
function usage(): string {
return `PostHog agent CLI
Usage:
posthog-cli api --agent-help
posthog-cli api tools
posthog-cli api search <regex>
posthog-cli api info [--json] <tool>
posthog-cli api schema <tool> [field.path]
posthog-cli api call [--json] [--dry-run] [--confirm] <tool> ['<json>']
posthog-cli api skill list [--json]
posthog-cli api skill install [--force] <skill-id>
posthog-cli api agents-md install [--path AGENTS.md]
Call targets: --project-id <id> and --organization-id <id> override environment and login defaults.
Targets apply to this invocation. Repeat them on each call or set per-process environment variables.
Destructive tools require --confirm when executed. Use --dry-run before mutations.
Agents: run \`posthog-cli api --agent-help\` and load the output into context before anything else.`
}
function takeFlag(args: string[], flag: string): boolean {
const index = args.indexOf(flag)
if (index === -1) {
return false
}
args.splice(index, 1)
return true
}
function printResult(result: unknown): void {
if (typeof result === 'string') {
process.stdout.write(result.endsWith('\n') ? result : `${result}\n`)
return
}
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
}
function buildStaticExec(): BuiltStaticExec {
const tools = getCliTools()
const execTool = createExecTool(
tools,
undefined,
'Execute a PostHog CLI command',
COMMAND_REFERENCE,
'posthog-cli',
undefined,
[],
{ requireDestructiveConfirmation: true }
)
return { execTool, tools }
}
async function buildExec(config: CliConfig = resolveCliConfig()): Promise<BuiltExec> {
const context = await buildCliContext(config)
const aiConsentGiven = await context.stateManager.getAiConsentGiven()
const tools = getCliTools({ aiConsentGiven })
const execTool = createExecTool(
tools,
context,
'Execute a PostHog CLI command',
COMMAND_REFERENCE,
'posthog-cli',
(toolName, properties) => trackCliToolCall(context, toolName, properties),
[],
{ requireDestructiveConfirmation: true }
)
return { context, execTool, tools }
}
function buildAgentHelpForStaticCatalog(): string {
return buildAgentHelp(getCliTools())
}
async function runStaticExecCommand(command: string): Promise<void> {
const { execTool } = buildStaticExec()
const result = await execTool.handler(undefined as unknown as Context, { command })
printResult(result)
}
async function runExecCommand(command: string, config: CliConfig): Promise<void> {
if (command.startsWith('call ')) {
requireApiKey(config)
}
const { execTool, context } = await buildExec(config)
const result = await execTool.handler(context, { command })
printResult(result)
}
async function runDryCall(args: string[]): Promise<void> {
const forceJson = takeFlag(args, '--json')
const confirmed = takeFlag(args, '--confirm')
const toolName = args.shift()
const jsonBody = args.length > 0 ? args.join(' ') : '{}'
if (!toolName) {
throw new Error('Usage: posthog-cli api call --dry-run [--json] [--confirm] <tool> <json>')
}
const { tools } = buildStaticExec()
const tool = tools.find((candidate) => candidate.name === toolName)
if (!tool) {
throw new Error(`Unknown tool: "${toolName}". Run "posthog-cli api search <term>".`)
}
let parsed: Record<string, unknown>
try {
parsed = jsonBody ? (JSON.parse(jsonBody) as Record<string, unknown>) : {}
} catch (error) {
const detail = error instanceof Error ? error.message : String(error)
throw new Error(`Invalid JSON input: ${detail}`)
}
// The same rewrap the MCP paths apply, so a dry run reports what a real call would do.
const firstPass = tool.schema.safeParse(parsed, { reportInput: true })
const rewrapped = firstPass.success ? undefined : repairArgumentNesting(firstPass.error, parsed, tool.schema)
const validation = rewrapped ? tool.schema.safeParse(rewrapped, { reportInput: true }) : firstPass
printResult({
dryRun: true,
tool: tool.name,
title: tool.title,
annotations: tool.annotations,
outputFormat: forceJson ? 'json' : 'text',
destructiveConfirmationRequired: tool.annotations.destructiveHint && !confirmed,
valid: validation.success,
...(validation.success
? { input: validation.data }
: { error: formatInputValidationError(tool.name, validation.error, parsed, tool.schema) }),
})
}
async function runSkillCommand(args: string[]): Promise<void> {
const subcommand = args.shift()
switch (subcommand) {
case 'list': {
const json = takeFlag(args, '--json')
const skills = await listSkills()
if (json) {
printResult(skills)
return
}
for (const skill of skills) {
process.stdout.write(`${skill.id}\t${skill.name}\n`)
}
return
}
case 'install': {
const force = takeFlag(args, '--force')
const skillId = args.shift()
if (!skillId) {
throw new Error('Usage: posthog-cli api skill install [--force] <skill-id>')
}
printResult(await installSkill(skillId, { force }))
return
}
default:
throw new Error('Usage: posthog-cli api skill list|install')
}
}
async function runAgentsMdCommand(args: string[]): Promise<void> {
const subcommand = args.shift()
if (subcommand !== 'install') {
throw new Error('Usage: posthog-cli api agents-md install [--path AGENTS.md]')
}
const filePath = takeOption(args, '--path')
const installedPath = await installAgentsMdSnippet(filePath ? { filePath } : {})
printResult({ installed: true, path: installedPath })
}
async function main(): Promise<void> {
const args = process.argv.slice(2)
const command = args.shift()
if (!command || command === 'help' || command === '--help' || command === '-h') {
process.stdout.write(`${usage()}\n`)
return
}
if (command === 'agent-help' || command === '--agent-help') {
process.stdout.write(`${buildAgentHelpForStaticCatalog()}\n`)
return
}
switch (command) {
case 'tools':
await runStaticExecCommand('tools')
return
case 'search':
await runStaticExecCommand(`search ${args.join(' ')}`)
return
case 'info': {
const json = takeFlag(args, '--json')
const toolName = args.shift()
if (!toolName) {
throw new Error('Usage: posthog-cli api info [--json] <tool>')
}
await runStaticExecCommand(`info ${json ? '--json ' : ''}${toolName}`)
return
}
case 'schema': {
const toolName = args.shift()
if (!toolName) {
throw new Error('Usage: posthog-cli api schema <tool> [field.path]')
}
await runStaticExecCommand(`schema ${toolName}${args[0] ? ` ${args[0]}` : ''}`)
return
}
case 'call': {
const config = resolveCliConfig(args)
const dryRun = takeFlag(args, '--dry-run')
if (dryRun) {
await runDryCall(args)
return
}
const json = takeFlag(args, '--json')
const confirmed = takeFlag(args, '--confirm')
const toolName = args.shift()
const jsonBody = args.length > 0 ? args.join(' ') : '{}'
if (!toolName) {
throw new Error('Usage: posthog-cli api call [--json] [--dry-run] [--confirm] <tool> [json]')
}
await runExecCommand(
`call ${json ? '--json ' : ''}${confirmed ? '--confirm ' : ''}${toolName} ${jsonBody}`,
config
)
return
}
case 'skill':
await runSkillCommand(args)
return
case 'agents-md':
await runAgentsMdCommand(args)
return
default:
throw new Error(`Unknown command "${command}".\n\n${usage()}`)
}
}
main().catch(async (error: unknown) => {
const message = error instanceof Error ? error.message : String(error)
process.stderr.write(`Error: ${message}\n`)
// process.exit() kills in-flight requests, which silently dropped every
// errored $mcp_tool_call event; flush analytics before exiting non-zero.
await flushAnalytics()
process.exit(1)
})