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.

26.8 KB
Raw Blame
import { z } from 'zod'

import { ApiRequest } from 'lib/api'
import { uuid } from 'lib/utils/dom'
import { teamLogic } from 'scenes/teamLogic'

import { performQuery } from '~/queries/query'
import type { HogQLQuery, HogQLQueryResponse } from '~/queries/schema/schema-general'

import { dashboardsList, dashboardsRetrieve } from 'products/dashboards/frontend/generated/api'
import { featureFlagsList, featureFlagsRetrieve } from 'products/feature_flags/frontend/generated/api'
import {
    mcpServerInstallationsAvailableToolsRetrieve,
    mcpServerInstallationsCallToolCreate,
} from 'products/mcp_store/frontend/generated/api'
import {
    notebooksCreate,
    notebooksList,
    notebooksPartialUpdate,
    notebooksRetrieve,
} from 'products/notebooks/frontend/generated/api'
import { NotebooksPartialUpdateBody } from 'products/notebooks/frontend/generated/api.zod'
import { insightsList, insightsRetrieve } from 'products/product_analytics/frontend/generated/api'

import { markdownNode, PosthogFilesystem, terminalFilename } from './posthogFilesystem'
import { RUN_HELP, TerminalCommandContext, TerminalCommands } from './terminalCommands'
import { HOGQL_FLAGS, HOGQL_HELP, terminalHogqlQuery } from './terminalHogql'
import { parseRemovalArguments, RM_SCRIPT } from './terminalRemove'
import { terminalQueryTable } from './terminalSql'

interface Command {
    name: string
    description: string
    inputSchema: Record<string, unknown>
    readOnly: boolean
    reference?: { parameter: string; type: string }
    invoke: (args: Record<string, unknown>) => Promise<unknown>
}

const aliases: Record<string, string> = {
    'notebook-list': 'notebooks-list',
    'notebook-get': 'notebooks-retrieve',
    'notebook-create': 'notebooks-create-markdown',
    'notebook-update': 'notebooks-partial-update',
    'notebook-delete': 'notebooks-destroy',
}

const help = `ph: PostHog commands

ph tools [search]                 List project commands and connected MCP tools
ph help <command>                Show arguments and whether a command writes data
ph <command> [ID or file]         Run a command
ph <command> --key value         Set a named argument
ph <command> --json '{...}'       Supply a JSON arguments object
ph <command> --json @args.json    Read arguments from a Linux file
ph <command> --json -            Read arguments from stdin
ph refresh                       Reload the project tree and connected tool catalog
run <file.sql>                    Run SQL and print a Markdown table
run --help                       Show SQL export formats and examples
hogql [options] ["SQL"]           Run SQL from an argument, stdin, or an interactive prompt
hogql --help                      Show query options and output formats
ph open [path]                   Open a project file or folder in PostHog (defaults to .)

Examples:
  ph notebooks-list --limit 10 | jq .results
  ph notebook-get '/posthog/files/Research/Notes.md'
  ph notebook-create --title 'Notes' --markdown @/tmp/notes.md
  ph notebook-delete <short-id>
  ph help notebook-delete

An @file value reads its contents. Built-in IDs can be paths under /posthog/files
or /posthog/api. JSON results go to stdout; errors go to stderr with a nonzero exit.
Connected tools use server/tool names from ph tools and their existing MCP permissions.
The built-in commands cover notebooks and reading insights, dashboards, and feature flags.
Tool schemas are files under /posthog/tools. Run ph refresh after creating or deleting objects.
Tab completes ph commands and --arguments, including connected MCP tools.
`

function command<T extends z.ZodType>(
    name: string,
    description: string,
    schema: T,
    invoke: (args: z.infer<T>) => Promise<unknown>,
    options: Pick<Command, 'readOnly' | 'reference'> = { readOnly: true }
): Command {
    return {
        name,
        description,
        inputSchema: z.toJSONSchema(schema),
        ...options,
        invoke: async (args) => invoke(schema.parse(args)),
    }
}

function object(value: unknown): Record<string, unknown> {
    return value !== null && typeof value === 'object' && !Array.isArray(value)
        ? (value as Record<string, unknown>)
        : {}
}

// Notebook search reads text_content, and the API keeps the stored value when an update omits it,
// so a content change has to carry the matching text the way every other writer does.
function notebookUpdate<T extends { content?: unknown; text_content?: string | null }>(body: T): T {
    if (body.content === undefined || body.text_content !== undefined) {
        return body
    }
    const node = markdownNode(body.content)
    if (!node) {
        throw new Error('Include text_content when updating content that is not a markdown notebook.')
    }
    return { ...body, text_content: node.attrs.markdown }
}

const jsonTypes = ['number', 'integer', 'boolean', 'object', 'array']

// Connected MCP servers write their own schemas, so a property can state its type through a
// reference, a composed branch, or a type array instead of a plain `type`.
function schemaTypes(property: unknown, root: Record<string, unknown>, depth = 0): Set<string> {
    const types = new Set<string>()
    const node = object(property)
    if (depth > 8) {
        return types
    }
    const pointer = typeof node.$ref === 'string' ? /^#\/(\$defs|definitions)\/([^/]+)$/.exec(node.$ref) : null
    if (pointer) {
        const name = pointer[2].replaceAll('~1', '/').replaceAll('~0', '~')
        for (const type of schemaTypes(object(root[pointer[1]])[name], root, depth + 1)) {
            types.add(type)
        }
    }
    for (const type of Array.isArray(node.type) ? node.type : [node.type]) {
        if (typeof type === 'string' && type !== 'null') {
            types.add(type)
        }
    }
    for (const key of ['anyOf', 'oneOf', 'allOf']) {
        for (const branch of Array.isArray(node[key]) ? (node[key] as unknown[]) : []) {
            for (const type of schemaTypes(branch, root, depth + 1)) {
                types.add(type)
            }
        }
    }
    return types
}

export class PosthogCommands {
    private readonly commands = new Map<string, Command>()
    private readonly toolDirectory
    private connectedLoaded = false

    constructor(
        private projectId: string,
        private signal: AbortSignal,
        private filesystem: PosthogFilesystem,
        private navigate: (url: string) => void
    ) {
        this.toolDirectory = filesystem.directory('tools', filesystem.root)
        const options = { signal }
        const pagination = z
            .object({
                limit: z.number().int().positive().optional(),
                offset: z.number().int().nonnegative().optional(),
            })
            .strict()
        const shortId = z
            .object({
                short_id: z
                    .string()
                    .regex(/^[\p{L}\p{N}]{1,12}(?![\s\S])/u, 'Use a notebook ID with up to 12 letters or numbers.'),
            })
            .strict()
        const insightId = z
            .object({
                short_id: z
                    .string()
                    .regex(/^(?:[A-Za-z0-9]{1,12}|[0-9]+)(?![\s\S])/, 'Use an insight short ID or numeric ID.'),
            })
            .strict()
        const id = z.object({ id: z.number().int().positive() }).strict()
        const notebook = { parameter: 'short_id', type: 'notebook' }
        const builtins = [
            command(
                'notebooks-list',
                'List notebooks in this project.',
                pagination.extend({ search: z.string().optional() }),
                (args) => notebooksList(projectId, args, options)
            ),
            command(
                'notebooks-retrieve',
                'Read a notebook by short ID or filesystem path.',
                shortId,
                ({ short_id }) => notebooksRetrieve(projectId, short_id, options),
                { readOnly: true, reference: notebook }
            ),
            command(
                'notebooks-destroy',
                'Delete a notebook from PostHog.',
                shortId,
                async ({ short_id }) => {
                    await notebooksPartialUpdate(projectId, short_id, { deleted: true }, options)
                    return { deleted: short_id }
                },
                { readOnly: false, reference: notebook }
            ),
            command(
                'notebooks-partial-update',
                'Update a notebook. Include version when changing its contents.',
                NotebooksPartialUpdateBody.extend(shortId.shape).strict(),
                ({ short_id, ...body }) => notebooksPartialUpdate(projectId, short_id, notebookUpdate(body), options),
                { readOnly: false, reference: notebook }
            ),
            command(
                'notebooks-create-markdown',
                'Create a markdown notebook. Its title becomes the first heading.',
                z.object({ title: z.string().min(1).max(256), markdown: z.string().optional() }).strict(),
                async ({ title, markdown }) => {
                    const text = `# ${title}${markdown?.trim() ? `\n\n${markdown.trim()}` : ''}`
                    return notebooksCreate(
                        projectId,
                        {
                            title,
                            content: {
                                type: 'doc',
                                content: [
                                    {
                                        type: 'ph-markdown-notebook',
                                        attrs: { nodeId: 'markdown-notebook-v2', markdown: text },
                                    },
                                ],
                            },
                            text_content: text,
                        },
                        options
                    )
                },
                { readOnly: false }
            ),
            command('insights-list', 'List insights in this project.', pagination, (args) =>
                insightsList(projectId, args, options)
            ),
            command(
                'insight-get',
                'Read an insight by short ID or filesystem path.',
                insightId,
                ({ short_id }) => insightsRetrieve(projectId, short_id, undefined, options),
                { readOnly: true, reference: { parameter: 'short_id', type: 'insight' } }
            ),
            command('dashboards-get-all', 'List dashboards in this project.', pagination, (args) =>
                dashboardsList(projectId, args, options)
            ),
            command(
                'dashboard-get',
                'Read a dashboard by ID or filesystem path.',
                id,
                ({ id }) => dashboardsRetrieve(projectId, id, undefined, options),
                { readOnly: true, reference: { parameter: 'id', type: 'dashboard' } }
            ),
            command('feature-flag-get-all', 'List feature flags in this project.', pagination, (args) =>
                featureFlagsList(projectId, args, options)
            ),
            command(
                'feature-flag-get-definition',
                'Read a feature flag by ID or filesystem path.',
                id,
                ({ id }) => featureFlagsRetrieve(projectId, id, options),
                { readOnly: true, reference: { parameter: 'id', type: 'feature_flag' } }
            ),
        ]
        for (const tool of builtins) {
            this.register(tool)
        }
        new TerminalCommands(filesystem, (argv, cwd, context) => this.execute(argv, cwd, context))
        filesystem.text('rm', filesystem.directory('bin', filesystem.root), RM_SCRIPT)
    }

    private register(tool: Command): void {
        this.commands.set(tool.name, tool)
        const { invoke: _, ...description } = tool
        this.filesystem.text(
            `${terminalFilename(tool.name)}.json`,
            this.toolDirectory,
            JSON.stringify(description, null, 2)
        )
    }

    private async loadConnected(): Promise<void> {
        if (this.connectedLoaded) {
            return
        }
        const { servers } = await mcpServerInstallationsAvailableToolsRetrieve(this.projectId, { signal: this.signal })
        for (const server of servers) {
            const namespace =
                servers.filter((candidate) => candidate.slug === server.slug).length > 1
                    ? `${server.slug}@${server.installation_id}`
                    : server.slug
            for (const tool of server.tools) {
                this.register({
                    name: `${namespace}/${tool.name}`,
                    description: `${tool.description}${tool.approval_state === 'needs_approval' ? '\nNeeds approval in Settings → MCP servers.' : ''}`,
                    inputSchema: tool.input_schema,
                    // Upstream MCP annotations are advisory, so readOnlyHint cannot prove that a
                    // connected tool only reads. Report every connected tool as a writer until the
                    // gateway returns its own classification.
                    readOnly: false,
                    invoke: async (args) => {
                        const result = await mcpServerInstallationsCallToolCreate(
                            this.projectId,
                            server.installation_id,
                            { tool_name: tool.name, arguments: args },
                            { signal: this.signal }
                        )
                        if (result.is_error) {
                            throw new Error(JSON.stringify(result.content))
                        }
                        return result.structured_content ?? result.content
                    },
                })
            }
        }
        this.connectedLoaded = true
    }

    private async parseArguments(tool: Command, argv: string[], cwd: string): Promise<Record<string, unknown>> {
        const args: Record<string, unknown> = Object.create(null)
        const properties = object(tool.inputSchema.properties)
        for (let index = 0; index < argv.length; index++) {
            const argument = argv[index]
            if (argument === '--json') {
                const value: unknown = JSON.parse(argv[++index] ?? '')
                if (!value || typeof value !== 'object' || Array.isArray(value)) {
                    throw new Error('--json requires a JSON object.')
                }
                Object.assign(args, value)
            } else if (argument.startsWith('--')) {
                const equals = argument.indexOf('=')
                const rawName = argument.slice(2, equals < 0 ? undefined : equals)
                const name = rawName in properties ? rawName : rawName.replaceAll('-', '_')
                if (!(name in properties)) {
                    throw new Error(`Unknown argument --${rawName}. Run ph help ${tool.name}.`)
                }
                const types = schemaTypes(properties[name], tool.inputSchema)
                const flag = types.size > 0 && [...types].every((type) => type === 'boolean')
                const value =
                    equals >= 0
                        ? argument.slice(equals + 1)
                        : flag && (!argv[index + 1] || argv[index + 1].startsWith('--'))
                          ? 'true'
                          : argv[++index]
                if (value === undefined) {
                    throw new Error(`Missing value for --${rawName}.`)
                }
                args[name] = value
            } else if (tool.reference && args[tool.reference.parameter] === undefined) {
                args[tool.reference.parameter] = argument
            } else {
                throw new Error(`Unexpected argument ${argument}. Run ph help ${tool.name}.`)
            }
        }
        if (tool.reference && typeof args[tool.reference.parameter] === 'string') {
            await this.filesystem.loadReference(args[tool.reference.parameter] as string, cwd)
            args[tool.reference.parameter] = this.filesystem.resolveReference(
                args[tool.reference.parameter] as string,
                cwd,
                tool.reference.type
            )
        }
        for (const [name, value] of Object.entries(args)) {
            const types = [...schemaTypes(properties[name], tool.inputSchema)]
            // A property that also accepts a string keeps the text it was given.
            if (typeof value === 'string' && types.length > 0 && types.every((type) => jsonTypes.includes(type))) {
                try {
                    args[name] = JSON.parse(value)
                } catch {
                    throw new Error(`Invalid ${types.join(' or ')} value for --${name}.`)
                }
            }
        }
        return args
    }

    private async executeQuery(query: HogQLQuery, context: TerminalCommandContext): Promise<HogQLQueryResponse> {
        if (this.signal.aborted || context.signal?.aborted) {
            throw new DOMException('Query cancelled', 'AbortError')
        }
        const controller = new AbortController()
        const queryId = uuid()
        const cancel = (): void => {
            if (controller.signal.aborted) {
                return
            }
            controller.abort()
            // Aborting the HTTP request does not stop the ClickHouse query.
            void new ApiRequest()
                .queryCancel(queryId, Number(this.projectId))
                .delete()
                .catch(() => {})
        }
        this.signal.addEventListener('abort', cancel, { once: true })
        context.signal?.addEventListener('abort', cancel, { once: true })
        try {
            return await performQuery(query, { signal: controller.signal }, 'force_blocking', queryId)
        } finally {
            this.signal.removeEventListener('abort', cancel)
            context.signal?.removeEventListener('abort', cancel)
        }
    }

    async execute(argv: string[], cwd: string, context: TerminalCommandContext = {}): Promise<unknown> {
        const [name = 'help', ...rest] = argv
        if (name === 'hogql') {
            if (rest.length === 1 && ['--help', '-h'].includes(rest[0])) {
                return HOGQL_HELP
            }
            if (rest.length !== 2 || rest[0] !== '--json') {
                throw new Error('Use hogql "SQL" or run hogql --help for examples.')
            }
            const request = z
                .object({ query: z.string(), argv: z.array(z.string()).max(1000) })
                .strict()
                .parse(JSON.parse(rest[1]))
            const { query, format } = terminalHogqlQuery(request.query, request.argv)
            if (teamLogic.values.currentTeamId !== Number(this.projectId) || this.signal.aborted) {
                throw new Error('The current project changed. Restart the terminal before running SQL.')
            }
            const result = await this.executeQuery(query, context)
            result.warnings?.forEach((warning) => context.onWarning?.(warning.message))
            // With `explain` or `modifiers.debug`, a failed query returns `error` instead of throwing.
            // JSON output shows that field, but a table would hide it behind an empty result.
            if (format !== 'json' && result.error) {
                throw new Error(result.error)
            }
            return format === 'json' ? result : terminalQueryTable(result, format)
        }
        if (name === '_complete') {
            const [position, prefix = '', previous, commandName] = rest
            if (position === '1' || (position === '2' && commandName === 'help')) {
                try {
                    await this.loadConnected()
                } catch {
                    // Keep built-in completion available when the connected tool catalog is unavailable.
                }
                return [
                    ...new Set([
                        'help',
                        'tools',
                        'refresh',
                        'run',
                        'hogql',
                        'open',
                        ...Object.keys(aliases),
                        ...this.commands.keys(),
                    ]),
                ]
                    .filter((candidate) => /^[A-Za-z0-9_@/.-]+$/.test(candidate) && candidate.startsWith(prefix))
                    .sort()
                    .join('\n')
            }
            if (prefix.startsWith('--') && previous !== '--json') {
                const flags = ['help', 'tools', 'refresh', 'open'].includes(commandName)
                    ? []
                    : commandName === 'run'
                      ? ['--help', '--markdown', '--json', '--csv', '--tsv']
                      : commandName === 'hogql'
                        ? HOGQL_FLAGS
                        : [
                              '--help',
                              '--json',
                              ...Object.keys(object((await this.find(commandName)).inputSchema.properties)).map(
                                  (key) => `--${key}`
                              ),
                          ]
                return flags
                    .filter((candidate) => /^[A-Za-z0-9_@/.-]+$/.test(candidate) && candidate.startsWith(prefix))
                    .sort()
                    .join('\n')
            }
            return ''
        }
        if (name === 'run') {
            if (rest.length === 1 && ['--help', '-h'].includes(rest[0])) {
                return RUN_HELP
            }
            if (rest.length < 2 || rest.length > 3 || !rest[0].endsWith('.sql')) {
                throw new Error('Usage: run <file.sql>. Run run --help for examples.')
            }
            const format = rest[2] ?? '--markdown'
            if (!['--markdown', '--json', '--csv', '--tsv'].includes(format)) {
                throw new Error('Unknown output format. Run run --help for formats.')
            }
            if (teamLogic.values.currentTeamId !== Number(this.projectId) || this.signal.aborted) {
                throw new Error('The current project changed. Restart the terminal before running SQL.')
            }
            const query = await this.filesystem.queryFor(rest[0], rest[1])
            if (teamLogic.values.currentTeamId !== Number(this.projectId) || this.signal.aborted) {
                throw new Error('The current project changed. Restart the terminal before running SQL.')
            }
            const result = await this.executeQuery(query, context)
            result.warnings?.forEach((warning) => context.onWarning?.(warning.message))
            if (format === '--json') {
                return {
                    columns: result.columns,
                    types: result.types,
                    results: result.results,
                    hasMore: result.hasMore,
                    ...(result.warnings?.length ? { warnings: result.warnings } : {}),
                }
            }
            return terminalQueryTable(result, format === '--csv' ? 'csv' : format === '--tsv' ? 'tsv' : 'markdown')
        }
        if (name === 'terminal-remove') {
            if (rest.length !== 2 || rest[0] !== '--json') {
                throw new Error('Use rm to delete PostHog files.')
            }
            const request = z
                .object({ argv: z.array(z.string()).max(1000) })
                .strict()
                .parse(JSON.parse(rest[1]))
            const { paths, recursive, force } = parseRemovalArguments(request.argv)
            await this.filesystem.removePaths(paths, recursive, force)
            return null
        }
        if (name === 'open') {
            if (rest.length > 1) {
                throw new Error('Use open with one file or folder path. Quote paths containing spaces.')
            }
            const url = await this.filesystem.navigationUrl(rest[0] ?? '.', cwd)
            if (this.signal.aborted) {
                throw new Error('The terminal stopped. Start it again before opening a file.')
            }
            this.navigate(url)
            return `Opened ${rest[0] ?? '.'} in PostHog.`
        }
        if (name === 'help' || name === '--help') {
            if (!rest.length) {
                return help
            }
            if (rest[0] === 'run') {
                return RUN_HELP
            }
            if (rest[0] === 'hogql') {
                return HOGQL_HELP
            }
            const tool = await this.find(rest[0])
            const { invoke: _, ...description } = tool
            return description
        }
        if (name === 'refresh') {
            await this.filesystem.load()
            this.connectedLoaded = false
            for (const key of this.commands.keys()) {
                if (key.includes('/')) {
                    this.commands.delete(key)
                    this.toolDirectory.children!.delete(`${terminalFilename(key)}.json`)
                }
            }
            await this.loadConnected()
            return 'Project files and connected tools refreshed.'
        }
        if (name === 'tools') {
            await this.loadConnected()
            const search = rest.join(' ').toLowerCase()
            return [...this.commands.values()]
                .filter((tool) => `${tool.name} ${tool.description}`.toLowerCase().includes(search))
                .map(({ name, description, readOnly }) => ({ name, description, readOnly }))
        }
        const tool = await this.find(name)
        if (rest.length === 1 && rest[0] === '--help') {
            const { invoke: _, ...description } = tool
            return description
        }
        const args = await this.parseArguments(tool, rest, cwd)
        if (tool.name.includes('/') || tool.name === 'notebooks-destroy' || args.deleted) {
            await this.filesystem.confirmOperation({
                title: tool.name.includes('/') ? 'Run a connected tool?' : 'Delete a PostHog object?',
                description: tool.name.includes('/')
                    ? `Run ${tool.name} from project ${this.projectId}. Connected tools can change or delete data in external services. Review the tool and its arguments before continuing.`
                    : `Run ${tool.name} in project ${this.projectId}. This deletes the specified notebook for everyone in the project.`,
                items: [tool.description, JSON.stringify(args, null, 2)],
            })
        } else if (!tool.readOnly) {
            await this.filesystem.confirmWrite({
                title: 'Change PostHog data?',
                description: `Run ${tool.name} in project ${this.projectId}. This affects everyone in the project.`,
                items: [tool.description, JSON.stringify(args, null, 2)],
            })
        }
        return tool.invoke(args)
    }

    private async find(name: string): Promise<Command> {
        const canonical = aliases[name] ?? name
        if (!this.commands.has(canonical)) {
            await this.loadConnected()
        }
        const tool = this.commands.get(canonical)
        if (!tool) {
            throw new Error(`Unknown command ${name}. Run ph tools to find a command.`)
        }
        return tool
    }
}