: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
import type { Context } from './context'
import { EXIT_USAGE } from './errors'
import type { Output } from './output'
import type { ParseFailure } from './schema'
import { kebabCase } from './text'
export interface ArgumentSpec {
description: string
optional?: boolean
// Collects every remaining argument into a list. Only the last argument can be variadic.
variadic?: boolean
// `-` reads the value from stdin, and an empty value is an error.
stdin?: boolean
}
// `env` and `config` are for global options only: the env vars and the posthog.json key path, such
// as `cli.noFail`, that set them.
interface OptionSource {
env?: readonly string[]
config?: string
// The posthog.json key means the opposite of the option, as `cli.telemetry: false` for --no-telemetry.
negate?: boolean
lenient?: boolean
}
export type OptionSpec =
| ({ type: 'boolean'; description: string; short?: string } & OptionSource)
| ({
type: 'string'
description: string
short?: string
// 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
// Turns the text into the value the command gets, such as a `Host`. It throws with `failure`
// when the text is not valid, so a bad flag or env var fails before the command runs.
parse?: (raw: string, failure: ParseFailure) => unknown
} & OptionSource)
type ArgumentValues<Args> = {
[Name in keyof Args]: Args[Name] extends { variadic: true }
? string[]
: Args[Name] extends { optional: true }
? string | undefined
: string
}
export type OptionValues<Options> = {
[Name in keyof Options]: Options[Name] extends { type: 'boolean' }
? boolean | undefined
: Options[Name] extends { multiple: true }
? string[] | undefined
: Options[Name] extends { parse: (...args: never[]) => infer Parsed }
? Parsed | undefined
: (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined
}
interface CommandInput<Args, Options> {
args: ArgumentValues<Args>
options: OptionValues<Options>
}
interface RenderInput<Args, Options, Result> extends CommandInput<Args, Options> {
result: Result
out: Output
}
interface CommandDefinition<Args, Options, Result> {
description: string
args?: Args
// The key becomes the flag: `dotenvFile` is `--dotenv-file`.
options?: Options
// The command changes something in PostHog or on disk. HOG_DRY_RUN turns on its `dryRun` option,
// and fails it when it has none. Commands that only read run as usual in a dry run.
writes?: boolean
// The command runs when posthog.json is invalid, like `hog config check`, which reports why.
// Every other command stops, so it never runs with settings hog couldn't read.
allowsInvalidConfig?: boolean
// Personal API key scopes the command needs. `hog commands` lists them, and a 403 names them.
scopes?: readonly string[]
notes?: string
examples?: readonly string[]
// Does the work and returns data. It never prints: `human` and `agent` decide how the data
// looks. Import heavy dependencies here with `await import()`, so other commands don't load them.
run(input: CommandInput<Args, Options> & { ctx: Context }): Promise<Result> | Result
// What a person at a terminal sees. Defaults to the result as indented JSON.
human?(input: RenderInput<Args, Options, Result>): void
// What agents, pipes and `-o json` see. Defaults to the result as one line of JSON.
agent?(input: RenderInput<Args, Options, Result>): void
// Extra properties for the anonymous usage event: counts and names from the result, never
// values, paths or text the caller typed.
telemetry?(input: CommandInput<Args, Options> & { result: Result }): Record<string, unknown>
// What --raw prints, for a result that holds more than its views show. Defaults to the result.
raw?(result: Result): unknown
// The exit code for a result. Defaults to 0. Failures throw a HogError instead.
exitCode?(result: Result): number
}
// Methods, not function properties, so a command with specific arguments still fits `Command`.
export interface Command<
Args extends Record<string, ArgumentSpec> = Record<string, ArgumentSpec>,
Options extends Record<string, OptionSpec> = Record<string, OptionSpec>,
Result = unknown,
> extends CommandDefinition<Args, Options, Result> {
kind: 'command'
}
export interface Group {
kind: 'group'
description: string
commands: CommandTree
// Shorter names that work the same, like `et` for `error-tracking`. Help and agents use the full name.
aliases?: readonly string[]
}
// A command posthog-cli still owns. hog lists it and points the caller to `use`, with the same arguments.
export interface Legacy {
kind: 'legacy'
description: string
use: string
}
export type CommandTree = Readonly<Record<string, Command | Group | Legacy>>
export function defineCommand<
const Args extends Record<string, ArgumentSpec> = {},
const Options extends Record<string, OptionSpec> = {},
Result = void,
>(definition: CommandDefinition<Args, Options, Result>): Command<Args, Options, Result> {
return { kind: 'command', ...definition }
}
export function defineGroup(definition: Omit<Group, 'kind'>): Group {
return { kind: 'group', ...definition }
}
export function defineLegacy(definition: Omit<Legacy, 'kind'>): Legacy {
return { kind: 'legacy', ...definition }
}
// `source` names where the value came from, such as `--host` or `HOG_HOST`, so the error says what to fix.
export function parseOption(spec: OptionSpec, value: unknown, source: string, code: string): unknown {
if (spec.type !== 'string' || !spec.parse || value === undefined) {
return value
}
return spec.parse(String(value), { code, context: `${source} is not valid.`, exitCode: EXIT_USAGE })
}
export function longFlag(name: string): string {
return `--${kebabCase(name)}`
}
export function optionFlags(name: string, spec: OptionSpec): string {
const long = longFlag(name)
const flag = spec.type === 'string' ? `${long} <${spec.placeholder ?? kebabCase(name)}>` : long
return spec.short ? `-${spec.short}, ${flag}` : flag
}
export function argumentSyntax(name: string, spec: ArgumentSpec): string {
const label = `${kebabCase(name)}${spec.variadic ? '...' : ''}`
return spec.optional ? `[${label}]` : `<${label}>`
}