diff --git a/contents/docs/cli.mdx b/contents/docs/cli.mdx new file mode 100644 index 000000000000..7bb6db482205 --- /dev/null +++ b/contents/docs/cli.mdx @@ -0,0 +1,263 @@ +--- +title: PostHog CLI +sidebar: Docs +showTitle: true +--- + +The PostHog CLI lets you use PostHog from your terminal, local scripts, CI/CD pipelines, and coding agents. + +You can use it for existing workflows like uploading source maps, querying data, and downloading schema definitions. + +You can also use `posthog-cli api` to give agents shell-friendly access to PostHog's [Model Context Protocol (MCP)](/docs/model-context-protocol) tool catalog. + +The best way to set up the agentic CLI is the [PostHog wizard](/docs/ai-engineering/ai-wizard). It detects your coding agents and configures them to use `posthog-cli api` for PostHog tasks: + +```bash +npx -y @posthog/wizard@latest cli add +``` + +See [set up agent instructions](#set-up-agent-instructions) for what this installs and the per-repo alternative. + +The CLI can also be installed globally by running: + +```bash +npm install -g @posthog/cli +``` + +## Authenticate + +```bash +posthog-cli login +``` + +This stores a personal API token locally and reuses it for CLI commands. + +For CI/CD, headless environments, or agents running without a browser, set environment variables instead: + +| Environment variable | Description | +| --- | --- | +| `POSTHOG_CLI_HOST` | PostHog host to connect to. Defaults to `https://us.posthog.com`. Use `https://eu.posthog.com` for EU Cloud. | +| `POSTHOG_CLI_PROJECT_ID` | Your PostHog project ID. This is the number in your project URL, such as `12345` in `https://us.posthog.com/project/12345`. | +| `POSTHOG_CLI_API_KEY` | A personal API key with the scopes required for the commands you run. | + +`posthog-cli api` also accepts `POSTHOG_HOST`, `POSTHOG_PROJECT_ID`, and `POSTHOG_API_KEY` if you already use those names in your environment. + +For broad agent workflows, create a [personal API key](https://app.posthog.com/settings/user-api-keys?preset=mcp_server) with the **MCP Server** preset. For narrower automation, grant only the scopes needed for the specific command. + +## Use PostHog from coding agents + +`posthog-cli api` exposes PostHog's MCP tools through a single shell command. This is useful for agents because they can discover the available tool surface progressively instead of loading every tool and schema into context upfront. + +Agents should start a session by loading the full usage guide into context: + +```bash +posthog-cli api --agent-help +``` + +This prints the same tool reference the PostHog MCP server serves — command reference, schema drill-down rules, data discovery workflow, and the tool index — rewritten for CLI invocation. + +The workflow is: + +1. Search for the right tool. +2. Inspect the tool before calling it. +3. Drill into nested schemas only when needed. +4. Call the tool with JSON input. + +For example: + +```bash +posthog-cli api search feature-flag +posthog-cli api info feature-flag-get-all +posthog-cli api schema query-trends series +posthog-cli api call --json feature-flag-get-all '{"limit":5}' +``` + +Use `--dry-run` before mutations: + +```bash +posthog-cli api call --dry-run feature-flags-bulk-delete-create '{"ids":[123]}' +``` + +Destructive tools require `--confirm`: + +```bash +posthog-cli api call --confirm --json feature-flags-bulk-delete-create '{"ids":[123]}' +``` + +Because the command prints plain text or JSON, agents can pipe output to tools like `jq`, save intermediate results, and chain commands without spending tokens on unrelated schemas. + +## Set up agent instructions + +Agents don't automatically know that `posthog-cli api` exists or how PostHog expects them to use it, so something needs to tell them. That something is a managed instructions snippet. + +The best way to install it is the [PostHog wizard](/docs/ai-engineering/ai-wizard). It detects which coding agents you have installed and writes the snippet into the agent's global instructions file, such as `~/.claude/CLAUDE.md` for Claude Code or `~/.codex/AGENTS.md` for Codex: + +```bash +npx -y @posthog/wizard@latest cli add +``` + +To set up a single repo instead of your agent globally, run the CLI installer from the repo root: + +```bash +posthog-cli api agents-md install +``` + +To write to a non-default agent instructions file, pass `--path`: + +```bash +posthog-cli api agents-md install --path ./AGENTS.md +``` + +The snippet tells agents to load `posthog-cli api --agent-help` into context, use `posthog-cli api` for PostHog tasks, follow the search, inspect, schema, and call workflow, and install any PostHog skill matching the task at hand before starting it. It's installed as a `...` block, and rerunning the install replaces the block in place — so reinstalling after a CLI update refreshes outdated instructions without duplicating them. + +## Agent skills + +Skills add task-specific instructions for common PostHog workflows, installed per repo into `.agents/skills/`. You don't need to install them upfront: the instructions snippet tells agents to check `posthog-cli api skill list` for a matching skill before starting a PostHog task, install it, and follow it. + +You can also browse and pre-install skills yourself: + +```bash +posthog-cli api skill list +posthog-cli api skill install +``` + +To see all skills as JSON, pass `--json`: + +```bash +posthog-cli api skill list --json +``` + +Installed skills are a snapshot. To refresh one after an update, reinstall it with `--force`: + +```bash +posthog-cli api skill install --force +``` + +## Use existing CLI commands + +Existing CLI commands continue to work as before. For example: + +```bash +posthog-cli sourcemap inject --directory ./dist +posthog-cli sourcemap upload --directory ./dist +posthog-cli exp schema pull +posthog-cli exp schema status +``` + +See [source map uploads](/docs/error-tracking/upload-source-maps/cli) and [schema management](/docs/product-analytics/schema-management#downloading-your-schema-with-the-cli) for product-specific examples. + +## Run from a local PostHog checkout + +If you're testing unreleased CLI changes from a local `PostHog/posthog` repository checkout, build the API CLI bundle first: + +```bash +pnpm install +pnpm --filter=@posthog/mcp build:cli +``` + +Then run the CLI through Cargo from the same checkout: + +```bash +cargo run -- api search feature-flag +cargo run -- api info feature-flag-get-all +``` + +If you're using an installed `posthog-cli` binary with a locally built API CLI bundle, point the binary at the bundle: + +```bash +export POSTHOG_API_CLI_PATH=/path/to/posthog/services/mcp/dist/posthog-api-cli.mjs +posthog-cli api search feature-flag +``` + +If the bundle can't be found, the CLI tells you to run `pnpm --filter=@posthog/mcp build:cli` or set `POSTHOG_API_CLI_PATH`. + +## Command reference + +```bash +posthog-cli api --agent-help +posthog-cli api tools +posthog-cli api search +posthog-cli api info [--json] +posthog-cli api schema [field.path] +posthog-cli api call [--json] [--dry-run] [--confirm] '' +posthog-cli api skill list [--json] +posthog-cli api skill install [--force] +posthog-cli api agents-md install [--path AGENTS.md] +``` + +## Troubleshooting and FAQ + +### My agent doesn't know about the CLI + +Agents only use `posthog-cli api` if their instructions tell them to. The best way to set that up is the wizard, which installs the steering snippet globally for your agent — or use the CLI to install it into a single repo's instructions file: + +```bash +npx -y @posthog/wizard@latest cli add +posthog-cli api agents-md install +``` + +If the snippet is installed but the agent still ignores the CLI, check that the instructions file is one your agent actually reads (for example, Claude Code reads `CLAUDE.md` and `AGENTS.md`, Codex reads `AGENTS.md`) and pass `--path` if needed. + +### The `api` command is unavailable + +Install the latest version of the CLI, then rerun the command: + +```bash +npm install -g @posthog/cli@latest +posthog-cli api --agent-help +``` + +### Missing API key + +If you see a missing API key error, run `posthog-cli login` or set `POSTHOG_CLI_API_KEY` and `POSTHOG_CLI_PROJECT_ID`. + +### The tool list looks outdated + +The tool catalog is bundled with the CLI, so an old binary serves an old catalog. Update the CLI and rerun the command: + +```bash +npm install -g @posthog/cli@latest +``` + +If a tool you used before is gone, names change as the PostHog API evolves — use `search` to find the current name: + +```bash +posthog-cli api search dashboard +``` + +### Skills are missing or outdated + +Skills are installed per repo into `.agents/skills/`. The instructions snippet tells agents to check for and install a matching skill before starting a PostHog task — if your agent isn't doing that, make sure the snippet is installed and up to date (see above). To install a skill manually: + +```bash +posthog-cli api skill list +posthog-cli api skill install +``` + +Installed skills are a snapshot — they don't update themselves. To refresh a stale skill, reinstall it with `--force`: + +```bash +posthog-cli api skill install --force +``` + +### The installed `AGENTS.md` snippet is outdated + +Rerun the install with the latest CLI. The snippet lives in a `...` block that's replaced in place, so this refreshes the instructions without duplicating them: + +```bash +npx -y @posthog/cli@latest api agents-md install +``` + +### Schema errors + +Run `info` before every `call`: + +```bash +posthog-cli api info query-trends +``` + +If the schema output includes a nested field you need to populate, inspect that field with `schema`: + +```bash +posthog-cli api schema query-trends series +```