: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 { z } from 'zod'
import { parseHost } from '@/posthog/host'
import { longFlag, parseOption, type OptionSpec, type OptionValues } from './command'
import type { PostHogConfig } from './config'
import { EXIT_USAGE, HogError } from './errors'
import type { Env, Runtime, RuntimeFetch } from './runtime'
import { parseOrThrow, type ParseFailure } from './schema'
// Options every command takes. Each one also reads the env vars in `env`, in order, and some read
// the posthog.json key at the `config` path. A flag beats an env var, which beats posthog.json.
const RateLimitSchema = z
.string()
.regex(/^[1-9]\d*$/, {
error: (issue) =>
`The rate limit must be a whole number of requests per minute, but it is "${String(issue.input)}".`,
})
.transform(Number)
function parseRateLimit(raw: unknown, failure: ParseFailure): number {
return parseOrThrow(RateLimitSchema, raw, failure)
}
export const GLOBAL_OPTIONS = {
host: {
type: 'string',
placeholder: 'url',
env: ['HOG_HOST'],
parse: parseHost,
description: 'The PostHog host to use instead of the one in your credentials',
},
dotenvFile: {
type: 'string',
placeholder: 'path',
env: ['HOG_DOTENV_FILE'],
description:
'Read HOG_PERSONAL_API_KEY, HOG_PROJECT_ID and HOG_HOST from this file when the environment has none',
},
output: {
type: 'string',
short: 'o',
placeholder: 'format',
choices: ['text', 'json'],
env: ['HOG_OUTPUT'],
description: 'Output format, json by default for agents and pipes',
},
raw: {
type: 'boolean',
env: ['HOG_RAW'],
description: 'Print the full result as JSON, without the formatting for people or agents',
},
debug: {
type: 'boolean',
env: ['HOG_DEBUG'],
description: 'Print each HTTP request hog sends, with its status and duration, to stderr',
},
noFail: {
type: 'boolean',
env: ['HOG_NO_FAIL'],
config: 'cli.noFail',
description: 'Exit with code 0 when the command fails or reports a problem, for builds that must not break',
},
skipSslVerification: {
type: 'boolean',
env: ['HOG_SKIP_SSL_VERIFICATION'],
description: 'Accept any TLS certificate, for a self-hosted PostHog with a self-signed one',
},
noTelemetry: {
type: 'boolean',
env: ['HOG_NO_TELEMETRY', 'DO_NOT_TRACK'],
config: 'cli.telemetry',
negate: true,
lenient: true,
description: 'Send no anonymous usage data to PostHog',
},
rateLimit: {
type: 'string',
placeholder: 'requests',
env: ['HOG_RATE_LIMIT'],
config: 'cli.rateLimit',
parse: parseRateLimit,
description: 'The most requests hog sends per minute',
},
} as const satisfies Record<string, OptionSpec>
export type GlobalOptions = OptionValues<typeof GLOBAL_OPTIONS>
export const DRY_RUN_ENV = ['HOG_DRY_RUN'] as const
const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on'])
const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', ''])
export function envFlag(env: Env, names: readonly string[]): boolean | undefined {
for (const name of names) {
const value = env[name]
if (value === undefined) {
continue
}
const normalized = value.trim().toLowerCase()
if (TRUE_VALUES.has(normalized)) {
return true
}
if (FALSE_VALUES.has(normalized)) {
return false
}
throw new HogError(
'invalid_setting',
`${name} must be true or false, but it is "${value}".`,
`Set ${name} to 1 or 0.`,
EXIT_USAGE
)
}
return undefined
}
// For opt-outs shared with other tools, like DO_NOT_TRACK: any value but an explicit "no" opts out,
// and an unknown value never breaks a command.
export function optOutFlag(env: Env, names: readonly string[]): boolean | undefined {
const set = names.map((name) => env[name]?.trim().toLowerCase()).filter((value) => value !== undefined)
if (set.length === 0) {
return undefined
}
return set.some((value) => !FALSE_VALUES.has(value))
}
function envValue(env: Env, names: readonly string[]): { name: string; value: string } | undefined {
for (const name of names) {
const value = env[name]
if (value) {
return { name, value }
}
}
return undefined
}
function configValue(config: PostHogConfig, path: string): unknown {
return path
.split('.')
.reduce<unknown>((parent, key) => (parent as Record<string, unknown> | undefined)?.[key], config)
}
export function resolveGlobals(
flags: Readonly<Record<string, unknown>>,
env: Env,
config: PostHogConfig = {}
): GlobalOptions {
const resolved: Record<string, unknown> = {}
for (const [name, spec] of Object.entries(GLOBAL_OPTIONS) as [string, OptionSpec][]) {
const envNames = spec.env ?? []
let value: unknown = flags[name]
let source = longFlag(name)
if (value === undefined && spec.type === 'boolean' && spec.lenient) {
value = optOutFlag(env, envNames)
} else if (value === undefined && spec.type === 'boolean') {
value = envFlag(env, envNames)
source = envNames.find((envName) => env[envName] !== undefined) ?? source
} else if (value === undefined) {
const fromEnv = envValue(env, envNames)
value = fromEnv?.value
source = fromEnv?.name ?? source
}
const configured = spec.config === undefined ? undefined : configValue(config, spec.config)
if (value === undefined && configured !== undefined) {
value = spec.type === 'string' ? String(configured) : spec.negate ? !configured : configured
source = `${spec.config} in posthog.json`
}
if (spec.type === 'string' && spec.choices && value !== undefined && !spec.choices.includes(String(value))) {
throw new HogError(
'invalid_setting',
`${source} must be one of ${spec.choices.join(', ')}, but it is "${String(value)}".`,
undefined,
EXIT_USAGE
)
}
resolved[name] = parseOption(spec, value, source, 'invalid_setting')
}
return resolved as GlobalOptions
}
const WINDOW_MS = 60_000
export function networkRuntime(runtime: Runtime, globals: GlobalOptions): Runtime {
if (globals.skipSslVerification) {
runtime.skipTlsVerification()
}
const limit = globals.rateLimit
if (limit === undefined && !globals.debug) {
return runtime
}
const started: number[] = []
let queue = Promise.resolve()
const waitTurn = (): Promise<void> => {
const turn = queue.then(async () => {
if (limit === undefined) {
return
}
while (started.length > 0 && runtime.now() - started[0]! >= WINDOW_MS) {
started.shift()
}
if (started.length >= limit) {
await runtime.sleep(WINDOW_MS - (runtime.now() - started[0]!))
started.shift()
}
started.push(runtime.now())
})
queue = turn
return turn
}
const fetch: RuntimeFetch = async (input, init) => {
if (!init?.skipRateLimit) {
await waitTurn()
}
if (!globals.debug) {
return runtime.fetch(input, init)
}
const url = new URL(input instanceof Request ? input.url : String(input))
// The query string can carry a signed upload URL's credentials, so only the path prints.
const label = `${init?.method ?? 'GET'} ${url.origin}${url.pathname}`
const begin = runtime.now()
try {
const response = await runtime.fetch(input, init)
runtime.writeStderr(`[debug] ${label} ${response.status} ${runtime.now() - begin}ms\n`)
return response
} catch (error) {
runtime.writeStderr(`[debug] ${label} failed: ${error instanceof Error ? error.message : error}\n`)
throw error
}
}
return { ...runtime, fetch }
}