: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
use std::path::PathBuf;
use anyhow::Context;
use clap::{Parser, Subcommand};
use tracing::{debug, warn};
use crate::{
api_proxy,
download::SymbolSetsSubcommand,
dsym::DsymSubcommand,
error::CapturedError,
experimental::{
endpoints::EndpointCommand, logs::command::LogsCommand, query::command::QueryCommand,
tasks::TaskCommand,
},
invocation_context::{
capture_command_run_without_context, context, init_context, set_telemetry_command_name,
set_telemetry_env_id_from_environment, INVOCATION_CONTEXT,
},
proguard::ProguardSubcommand,
release::ReleaseSubcommand,
sourcemaps::{hermes::HermesSubcommand, plain::SourcemapCommand},
};
#[derive(Parser)]
#[command(version, about, long_about = None)]
pub struct Cli {
/// The PostHog host to connect to
#[arg(long)]
host: Option<String>,
/// Disable non-zero exit codes on errors. Use with caution.
#[arg(long, default_value = "false")]
no_fail: bool,
/// Skip SSL certificate verification when talking to the PostHog API. Use only with
/// self-signed certificates.
#[arg(long, default_value = "false")]
skip_ssl_verification: bool,
/// Set the number of requests per minute for the Posthog API Client.
#[arg(long, env = "POSTHOG_CLIENT_RATE_LIMIT")]
rate_limit: Option<usize>,
/// Load PostHog credentials from this dotenv-style file when not present in the process
/// environment. Prefer this over the `--env-file` alias: the npm package runs the binary
/// through a `node` wrapper, and Node's own built-in `--env-file` flag intercepts that spelling.
/// Also settable as `POSTHOG_CLI_DOTENV_FILE`, for callers that control the environment but
/// not the command line (e.g. an Xcode build phase invoking the iOS SDK's upload-symbols.sh).
#[arg(
long = "dotenv-file",
alias = "env-file",
value_name = "PATH",
env = "POSTHOG_CLI_DOTENV_FILE"
)]
env_file: Option<PathBuf>,
/// Skip artifact processing and upload (sourcemap, dSYM, hermes, proguard, release) without
/// contacting PostHog or requiring credentials. Intended for CI gates that bundle to catch
/// regressions but must not (or cannot) upload. Not for release builds. Pass it before the
/// subcommand (`posthog-cli --dry-run hermes upload ...`) or set `POSTHOG_CLI_DRY_RUN`. This is
/// distinct from the `exp endpoints` `--dry-run`, which previews endpoint changes.
#[arg(
long,
env = "POSTHOG_CLI_DRY_RUN",
value_parser = clap::builder::BoolishValueParser::new(),
num_args = 0..=1,
require_equals = true,
default_value = "false",
default_missing_value = "true",
)]
dry_run: bool,
#[command(subcommand)]
command: Commands,
}
/// Commands that `--dry-run` turns into a no-op. Returns what gets skipped, for logging, or `None`
/// for commands that don't write anything to PostHog (login, queries, schema sync, symbol-set
/// downloads).
fn dry_run_skipped_command(command: &Commands) -> Option<&'static str> {
match command {
Commands::Sourcemap { .. } => Some("sourcemap"),
Commands::Dsym { .. } => Some("dSYM"),
Commands::SymbolSets {
cmd: SymbolSetsSubcommand::Upload(_),
} => Some("native debug symbols"),
Commands::Hermes { .. } => Some("hermes sourcemap"),
Commands::Proguard { .. } => Some("proguard"),
// Resolving a release creates the row when it doesn't exist yet, which a dry run must not
// do. The command prints nothing, so a caller injecting the id ships a bundle without one.
Commands::Release { .. } => Some("release"),
Commands::Exp { cmd } => match cmd {
ExpCommand::Hermes { .. } => Some("hermes sourcemap"),
ExpCommand::Proguard { .. } => Some("proguard"),
ExpCommand::Dsym { .. } => Some("dSYM"),
_ => None,
},
_ => None,
}
}
// These are the API key env vars recognized by the Node `posthog-cli api` bundle.
// Rust auth only reads the POSTHOG_CLI_* aliases; this check is deliberately about
// whether the child process already has a usable key, so we avoid loading and mixing
// stored credentials.
const API_KEY_ENV_VARS: &[&str] = &[
"POSTHOG_API_KEY",
"POSTHOG_CLI_API_KEY",
"POSTHOG_CLI_TOKEN",
];
fn api_command_needs_stored_credentials_with_env(
args: &[String],
has_env: impl Fn(&str) -> bool,
) -> bool {
let Some(command) = args.first().map(String::as_str) else {
return false;
};
command == "call"
&& !args.iter().skip(1).any(|arg| arg == "--dry-run")
&& !API_KEY_ENV_VARS.iter().any(|name| has_env(name))
}
fn api_command_needs_stored_credentials(args: &[String]) -> bool {
api_command_needs_stored_credentials_with_env(args, |name| std::env::var_os(name).is_some())
}
#[derive(Subcommand)]
pub enum Commands {
/// Interactively authenticate with PostHog, storing a personal API token locally. You can also use the
/// environment variables `POSTHOG_CLI_API_KEY` and `POSTHOG_CLI_PROJECT_ID`
Login,
/// Update posthog-cli to the latest version
Update,
/// Experimental commands, not quite ready for prime time
Exp {
#[command(subcommand)]
cmd: ExpCommand,
},
#[command(about = "Upload a directory of bundled chunks to PostHog")]
Sourcemap {
#[command(subcommand)]
cmd: SourcemapCommand,
},
#[command(about = "Upload Apple dSYM debug symbol files to PostHog")]
Dsym {
#[command(subcommand)]
cmd: DsymSubcommand,
},
#[command(about = "Upload hermes sourcemaps to PostHog")]
Hermes {
#[command(subcommand)]
cmd: HermesSubcommand,
},
#[command(about = "Upload proguard mapping files to PostHog")]
Proguard {
#[command(subcommand)]
cmd: ProguardSubcommand,
},
#[command(about = "Upload, download, and manage symbol sets")]
SymbolSets {
#[command(subcommand)]
cmd: SymbolSetsSubcommand,
},
#[command(about = "Look up the release a build belongs to")]
Release {
#[command(subcommand)]
cmd: ReleaseSubcommand,
},
#[command(
about = "Agent-first PostHog API tools",
long_about = "Agent-first PostHog API tools.\n\n\
Exposes PostHog's MCP tool catalog through a shell-friendly interface so coding \
agents (and the humans driving them) can discover, inspect, and call PostHog API \
tools without loading every schema into context upfront.",
after_help = "Commands:\n \
tools List every available tool\n \
search <regex> Find tools by name, title, or description\n \
info [--json] <tool> Show a tool's description and input schema\n \
schema <tool> [field.path] Drill into a nested schema field\n \
call [--json] [--dry-run] [--confirm] <tool> '<json>' Execute a tool with JSON input\n \
skill list [--json] List installable PostHog agent skills\n \
skill install [--force] <skill-id> Install a skill into .agents/skills/\n \
agents-md install [--path AGENTS.md] Install the PostHog steering snippet\n\n\
Run `posthog-cli api --agent-help` for the full agent-facing usage guide.\n\n\
Destructive tools require --confirm. Use --dry-run before mutations.\n\n\
Limitation: `login` grants the MCP scope set minus the writes PostHog \
withholds from long-lived API keys, so a few tools (desktop file-system \
writes, integration deletes, reminder and user-settings writes) are not \
available through this command.",
trailing_var_arg = true
)]
Api {
#[arg(trailing_var_arg = true, allow_hyphen_values = true)]
args: Vec<String>,
},
}
#[derive(Subcommand)]
pub enum ExpCommand {
/// Manage tasks - list, create, update, delete etc
Task {
#[command(subcommand)]
cmd: TaskCommand,
/// Whether to skip SSL verification when talking to the posthog API - only use when using self-signed certificates for
/// self-deployed instances
// TODO - it seems likely we won't support tasks for self hosted, but I'm putting this here in case we do
#[arg(long, default_value = "false")]
skip_ssl_verification: bool,
},
/// Run a SQL query against any data you have in posthog. This is mostly for fun, and subject to change
Query {
#[command(subcommand)]
cmd: QueryCommand,
},
/// Manage PostHog endpoints as YAML files. Pull endpoints from PostHog, or push changes from your YAML files.
Endpoints {
#[command(subcommand)]
cmd: EndpointCommand,
},
/// Import historical logs into PostHog from another log store
Logs {
#[command(subcommand)]
cmd: LogsCommand,
},
// TODO(sept 2026): remove these backward-compat aliases, they moved to top-level commands
#[command(about = "Upload hermes sourcemaps to PostHog", hide = true)]
Hermes {
#[command(subcommand)]
cmd: HermesSubcommand,
},
#[command(about = "Upload proguard mapping files to PostHog", hide = true)]
Proguard {
#[command(subcommand)]
cmd: ProguardSubcommand,
},
#[command(about = "Upload iOS/macOS dSYM files to PostHog", hide = true)]
Dsym {
#[command(subcommand)]
cmd: DsymSubcommand,
},
/// Download event definitions and generate typed SDK
Schema {
#[command(subcommand)]
cmd: SchemaCommand,
},
}
#[derive(Subcommand)]
pub enum SchemaCommand {
/// Download event definitions and generate typed SDK
Pull {
/// Output path for generated definitions (stored in posthog.json for future runs)
#[arg(short, long)]
output: Option<String>,
},
/// Show current schema sync status
Status,
}
impl Commands {
fn telemetry_command_name(&self) -> &'static str {
match self {
Commands::Login => "login",
Commands::Update => "update",
Commands::Exp { cmd } => cmd.telemetry_command_name(),
Commands::Sourcemap { cmd } => match cmd {
SourcemapCommand::Inject(_) => "sourcemap_inject",
SourcemapCommand::Upload(_) => "sourcemap_upload",
SourcemapCommand::Process(_) => "sourcemap_process",
},
Commands::Dsym { cmd } => match cmd {
DsymSubcommand::Upload(_) => "dsym_upload",
},
Commands::Hermes { cmd } => match cmd {
HermesSubcommand::Inject(_) => "hermes_inject",
HermesSubcommand::Upload(_) => "hermes_upload",
HermesSubcommand::Clone(_) => "hermes_clone",
},
Commands::Proguard { cmd } => match cmd {
ProguardSubcommand::Upload(_) => "proguard_upload",
},
Commands::SymbolSets { cmd } => match cmd {
SymbolSetsSubcommand::Upload(_) => "symbolset_upload",
SymbolSetsSubcommand::Download(_) => "symbolset_download",
SymbolSetsSubcommand::Extract(_) => "symbolset_extract",
},
Commands::Release { cmd } => match cmd {
ReleaseSubcommand::Resolve(_) => "release_resolve",
},
Commands::Api { .. } => "api",
}
}
}
impl ExpCommand {
fn telemetry_command_name(&self) -> &'static str {
match self {
ExpCommand::Logs { cmd } => match cmd {
LogsCommand::Import { .. } => "logs_import",
},
ExpCommand::Task { cmd, .. } => match cmd {
TaskCommand::List { .. } => "task_list",
TaskCommand::Progress { .. } => "task_progress",
TaskCommand::UpdateStage { .. } => "task_update_stage",
},
ExpCommand::Query { cmd } => match cmd {
QueryCommand::Editor { .. } => "query_editor",
QueryCommand::Run { .. } => "query_run",
QueryCommand::Check { .. } => "query_check",
},
ExpCommand::Endpoints { cmd } => match cmd {
EndpointCommand::List(_) => "endpoints_list",
EndpointCommand::Get(_) => "endpoints_get",
EndpointCommand::Open(_) => "endpoints_open",
EndpointCommand::Run(_) => "endpoints_run",
EndpointCommand::Push(_) => "endpoints_push",
EndpointCommand::Pull(_) => "endpoints_pull",
EndpointCommand::Diff(_) => "endpoints_diff",
},
ExpCommand::Hermes { cmd } => match cmd {
HermesSubcommand::Inject(_) => "hermes_inject",
HermesSubcommand::Upload(_) => "hermes_upload",
HermesSubcommand::Clone(_) => "hermes_clone",
},
ExpCommand::Proguard { cmd } => match cmd {
ProguardSubcommand::Upload(_) => "proguard_upload",
},
ExpCommand::Dsym { cmd } => match cmd {
DsymSubcommand::Upload(_) => "dsym_upload",
},
ExpCommand::Schema { cmd } => match cmd {
SchemaCommand::Pull { .. } => "schema_pull",
SchemaCommand::Status => "schema_status",
},
}
}
}
impl Cli {
/// `Ok(Some(code))` means the command completed by delegating to a child
/// process that exited non-zero; the caller should exit with that code
/// after flushing telemetry.
pub fn run() -> Result<Option<i32>, CapturedError> {
let command = Cli::parse();
let no_fail = command.no_fail;
set_telemetry_command_name(command.command.telemetry_command_name());
let result = command.run_impl().map_err(|error| error.capture());
if INVOCATION_CONTEXT.get().is_some() {
context().finish();
}
match result {
Ok(exit_code) => Ok(if no_fail { None } else { exit_code }),
Err(e) => {
if no_fail {
match &e.exception_id {
Some(id) => crate::safe_eprintln!("Oops! {} (ID: {})", e.inner, id),
None => crate::safe_eprintln!("Oops! {:?}", e.inner),
};
Ok(None)
} else {
Err(e)
}
}
}
}
fn run_impl(self) -> Result<Option<i32>, CapturedError> {
if self.dry_run {
if let Some(kind) = dry_run_skipped_command(&self.command) {
warn!(
"Dry run enabled (--dry-run / POSTHOG_CLI_DRY_RUN): skipping the {kind} step. \
Nothing was sent to PostHog and no credentials were used. \
Do not use --dry-run for release builds."
);
return Ok(None);
}
}
if !matches!(
self.command,
Commands::Login
// Updating talks to the release bucket, never to PostHog, so
// requiring credentials would lock out anyone without a token.
| Commands::Update
| Commands::Api { .. }
| Commands::SymbolSets {
cmd: SymbolSetsSubcommand::Extract(_)
}
) {
init_context(
self.host.clone(),
self.skip_ssl_verification,
self.rate_limit,
self.env_file.clone(),
)?;
}
let mut api_exit_code: Option<i32> = None;
match self.command {
Commands::Login => {
// Notably login doesn't have a context set up going it - it sets one up
crate::login::login(self.host)?;
}
Commands::Update => {
crate::update::update()?;
}
Commands::Sourcemap { cmd } => match cmd {
SourcemapCommand::Inject(input_args) => {
crate::sourcemaps::plain::inject::inject(&input_args, None)?;
}
SourcemapCommand::Upload(upload_args) => {
crate::sourcemaps::plain::upload::upload(&upload_args, None)?;
}
SourcemapCommand::Process(args) => {
let (inject_args, upload_args) = args.resolve_stdin()?.into();
let cwd =
std::env::current_dir().context("Failed to determine current directory")?;
let release = crate::sourcemaps::inject::get_release_for_maps(
&cwd,
inject_args.release.clone(),
std::iter::empty(),
)?;
// Hand the pairs inject wrote straight to upload, instead of letting
// upload re-walk the directory: a bundler writing into it mid-run
// (e.g. Turbopack's background filesystem-cache flush on Next.js
// 16.3+) would otherwise give upload files inject never stamped,
// aborting the build with "Chunk ID not found" (posthog-js#4667).
let pairs =
crate::sourcemaps::plain::inject::inject(&inject_args, release.as_ref())?;
let file_selection = upload_args.file_selection.clone();
crate::sourcemaps::plain::upload::upload_pairs(
&upload_args,
pairs,
release.as_ref(),
file_selection,
)?;
}
},
Commands::Dsym { cmd } => match cmd {
DsymSubcommand::Upload(args) => {
crate::dsym::upload::upload(&args)?;
}
},
Commands::Hermes { cmd } => match cmd {
HermesSubcommand::Inject(args) => {
crate::sourcemaps::hermes::inject::inject(&args)?;
}
HermesSubcommand::Upload(args) => {
crate::sourcemaps::hermes::upload::upload(&args)?;
}
HermesSubcommand::Clone(args) => {
crate::sourcemaps::hermes::clone::clone(&args)?;
}
},
Commands::Proguard { cmd } => match cmd {
ProguardSubcommand::Upload(args) => {
crate::proguard::upload::upload(&args)?;
}
},
Commands::SymbolSets { cmd } => match cmd {
SymbolSetsSubcommand::Upload(args) => {
crate::debug_symbols::upload::upload(&args)?;
}
SymbolSetsSubcommand::Download(args) => {
crate::download::download(&args)?;
}
SymbolSetsSubcommand::Extract(args) => {
crate::download::extract(&args)?;
}
},
Commands::Release { cmd } => match cmd {
ReleaseSubcommand::Resolve(args) => {
crate::release::resolve(&args)?;
}
},
Commands::Api { args } => {
// The proxy often runs without stored credentials (env-var auth,
// metadata subcommands), so attach the project id from the
// environment for telemetry attribution; init_context overrides
// it with the stored value when it runs.
set_telemetry_env_id_from_environment();
// No InvocationContext on this path, so capture the usage event
// directly — without it the `api` command has no telemetry
// denominator to compute failure rates against.
let usage_capture = capture_command_run_without_context();
let api_context = if api_command_needs_stored_credentials(&args) {
match init_context(
self.host.clone(),
self.skip_ssl_verification,
self.rate_limit,
self.env_file.clone(),
) {
Ok(_) => Some(context()),
Err(error) => {
debug!("API CLI proxy running without invocation context: {error:?}");
None
}
}
} else {
None
};
let run_result = api_proxy::run(args, self.host, api_context);
let _ = usage_capture.join();
api_exit_code = run_result?;
}
Commands::Exp { cmd } => match cmd {
ExpCommand::Task {
cmd,
skip_ssl_verification: _,
} => {
cmd.run()?;
}
ExpCommand::Query { cmd } => {
crate::experimental::query::command::query_command(&cmd)?
}
ExpCommand::Endpoints { cmd } => {
cmd.run()?;
}
ExpCommand::Logs { cmd } => {
cmd.run()?;
}
// TODO(sept 2026): remove these backward-compat aliases
ExpCommand::Hermes { cmd } => match cmd {
HermesSubcommand::Inject(args) => {
crate::sourcemaps::hermes::inject::inject(&args)?;
}
HermesSubcommand::Upload(args) => {
crate::sourcemaps::hermes::upload::upload(&args)?;
}
HermesSubcommand::Clone(args) => {
crate::sourcemaps::hermes::clone::clone(&args)?;
}
},
ExpCommand::Proguard { cmd } => match cmd {
ProguardSubcommand::Upload(args) => {
crate::proguard::upload::upload(&args)?;
}
},
ExpCommand::Dsym { cmd } => match cmd {
DsymSubcommand::Upload(args) => {
crate::dsym::upload::upload(&args)?;
}
},
ExpCommand::Schema { cmd } => match cmd {
SchemaCommand::Pull { output } => {
crate::experimental::schema::pull(self.host, output)?;
}
SchemaCommand::Status => {
crate::experimental::schema::status()?;
}
},
},
}
Ok(api_exit_code)
}
}
#[cfg(test)]
mod tests {
use super::*;
use clap::{CommandFactory, Parser};
#[test]
fn cli_definition_is_valid() {
Cli::command().debug_assert();
}
#[test]
fn dry_run_flag_is_wired_to_env_var() {
let cmd = Cli::command();
let arg = cmd
.get_arguments()
.find(|a| a.get_id().as_str() == "dry_run")
.expect("dry_run arg should exist");
assert_eq!(
arg.get_env(),
Some(std::ffi::OsStr::new("POSTHOG_CLI_DRY_RUN"))
);
}
#[test]
fn env_file_flag_is_wired_to_env_var() {
let cmd = Cli::command();
let arg = cmd
.get_arguments()
.find(|a| a.get_id().as_str() == "env_file")
.expect("env_file arg should exist");
assert_eq!(
arg.get_env(),
Some(std::ffi::OsStr::new("POSTHOG_CLI_DOTENV_FILE"))
);
}
#[test]
fn dry_run_defaults_to_false() {
let cli = Cli::try_parse_from(["posthog-cli", "login"]).unwrap();
assert!(!cli.dry_run);
}
#[test]
fn dry_run_flag_sets_true_before_subcommand() {
let cli = Cli::try_parse_from(["posthog-cli", "--dry-run", "login"]).unwrap();
assert!(cli.dry_run);
}
#[test]
fn dry_run_classifies_every_command() {
// (argv, expected kind). `dry_run_skipped_command` matches on the top-level command, so one
// representative subcommand per family is enough; the `exp` aliases get their own rows.
let cases: &[(&[&str], Option<&str>)] = &[
(&["sourcemap", "upload"], Some("sourcemap")),
(&["dsym", "upload", "--directory", "d"], Some("dSYM")),
(
&[
"hermes",
"clone",
"--minified-map-path",
"m",
"--composed-map-path",
"c",
],
Some("hermes sourcemap"),
),
(
&["proguard", "upload", "--path", "p", "--map-id", "m"],
Some("proguard"),
),
// resolving a release creates the row, so a dry run must not reach it
(&["release", "resolve"], Some("release")),
// hidden `exp` aliases must skip too
(&["exp", "dsym", "upload", "--directory", "d"], Some("dSYM")),
(
&[
"exp",
"hermes",
"clone",
"--minified-map-path",
"m",
"--composed-map-path",
"c",
],
Some("hermes sourcemap"),
),
(
&["exp", "proguard", "upload", "--path", "p", "--map-id", "m"],
Some("proguard"),
),
// commands that don't upload artifacts must run normally
(&["login"], None),
(&["exp", "schema", "status"], None),
(&["exp", "endpoints", "push", "f.yaml"], None),
];
for (argv, expected) in cases {
let cli = Cli::try_parse_from(std::iter::once(&"posthog-cli").chain(argv.iter()))
.unwrap_or_else(|e| panic!("failed to parse {argv:?}: {e}"));
assert_eq!(
dry_run_skipped_command(&cli.command),
*expected,
"wrong dry-run classification for {argv:?}"
);
}
}
#[test]
fn api_metadata_commands_do_not_need_stored_credentials() {
let cases: &[&[&str]] = &[
&[],
&["--agent-help"],
&["tools"],
&["search", "feature-flag"],
&["info", "feature-flag-get-all"],
&["schema", "query-trends", "series"],
&["skill", "list"],
&["agents-md", "install"],
];
for argv in cases {
let args = argv.iter().map(|arg| arg.to_string()).collect::<Vec<_>>();
assert!(
!api_command_needs_stored_credentials_with_env(&args, |_| false),
"metadata command should not load stored credentials: {argv:?}"
);
}
}
#[test]
fn api_call_uses_stored_credentials_only_when_needed() {
let call_args = ["call", "--json", "feature-flag-get-all", "{\"limit\":5}"]
.iter()
.map(|arg| arg.to_string())
.collect::<Vec<_>>();
assert!(api_command_needs_stored_credentials_with_env(
&call_args,
|_| false
));
assert!(!api_command_needs_stored_credentials_with_env(
&call_args,
|name| name == "POSTHOG_API_KEY"
));
let dry_run_args = [
"call",
"--dry-run",
"feature-flags-bulk-delete-create",
"{\"ids\":[123]}",
]
.iter()
.map(|arg| arg.to_string())
.collect::<Vec<_>>();
assert!(!api_command_needs_stored_credentials_with_env(
&dry_run_args,
|_| false
));
}
#[test]
fn endpoints_dry_run_is_independent_of_top_level_flag() {
// The `exp endpoints` commands have their own `--dry-run` (preview). The top-level flag is
// not global, so `exp endpoints push --dry-run` sets only the endpoint flag, and the
// top-level skip never fires for endpoints — preview semantics stay intact.
use crate::experimental::endpoints::EndpointCommand;
let cli = Cli::try_parse_from([
"posthog-cli",
"exp",
"endpoints",
"push",
"f.yaml",
"--dry-run",
])
.unwrap();
assert!(
!cli.dry_run,
"endpoint --dry-run must not set the top-level flag"
);
assert_eq!(dry_run_skipped_command(&cli.command), None);
let Commands::Exp {
cmd:
ExpCommand::Endpoints {
cmd: EndpointCommand::Push(args),
},
} = &cli.command
else {
panic!("expected `exp endpoints push`");
};
assert!(args.dry_run, "endpoint preview flag should be set");
}
}