# PostHog CLI - Docs

The PostHog CLI lets you use PostHog from your terminal, your coding agents, local scripts, and CI/CD pipelines.

-   **API**: Use `posthog-cli api` to access PostHog's API and MCP tool catalog from shell-friendly commands, including running SQL queries against your data
-   **Source maps**: [Inject and upload source maps](/docs/error-tracking/upload-source-maps/cli.md) for PostHog error tracking
-   **Schema management**: Download and check schema definitions for product analytics workflows
-   **Tasks:** List, create, update, and delete PostHog tasks

The CLI is open source. You can find the code in the [`cli` directory of the PostHog repo](https://github.com/PostHog/posthog/tree/master/cli).

## Installation

Install the PostHog CLI with our wizard:

### Install the PostHog CLI

```
npx @posthog/wizard cli add
```

Installs the CLI and adds instructions to your coding agent

If you'd rather not use our wizard, you can install the CLI by running:

Terminal

PostHog AI

```bash
npm install -g @posthog/cli@latest
```

> **Using Claude Code, Codex, or another coding agent?**: You should follow our [CLI setup for agents](#setup-for-agents) instructions.

### Authentication

Terminal

PostHog AI

```bash
posthog-cli login
```

This opens a browser-based login flow, 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.

## Command reference

| Command | Description |
| --- | --- |
| posthog-cli login | Authenticate with PostHog and store a personal API token locally |
| posthog-cli api | Use agent-first PostHog API tools |
| posthog-cli sourcemap | Upload bundled JavaScript chunks and source maps to PostHog |
| posthog-cli dsym | Upload Apple dSYM debug symbol files |
| posthog-cli hermes | Upload Hermes source maps |
| posthog-cli proguard | Upload ProGuard mapping files |
| posthog-cli symbol-sets | Manage uploaded symbol sets |
| posthog-cli exp | Run experimental commands |
| posthog-cli help | Print CLI help or help for a subcommand |

## Global options

These options apply to any command and go before the subcommand (for example, `posthog-cli --dry-run hermes upload ...`).

| Option | Description |
| --- | --- |
| --host <HOST> | PostHog host to connect to. Defaults to https://us.posthog.com. |
| --no-fail | Disable non-zero exit codes on errors. Use with caution. |
| --skip-ssl-verification | Skip SSL certificate verification when talking to the PostHog API. Use only with self-signed certificates. |
| --rate-limit <RATE_LIMIT> | Set the number of requests per minute for the PostHog API client. Also settable via POSTHOG_CLIENT_RATE_LIMIT. |
| --dotenv-file <PATH> | Load PostHog credentials from a dotenv-style file when not present in the process environment. |
| --dry-run | Skip artifact processing and upload (sourcemap, dSYM, hermes, proguard) without contacting PostHog or requiring credentials. Intended for CI gates, not release builds. Also settable via POSTHOG_CLI_DRY_RUN. |

## Using the CLI with a coding agent

PostHog supports both CLI and [MCP](/docs/model-context-protocol.md) interfaces for agent workflows. You usually only need one, and which one you choose depends on how you want the agent to interact with PostHog.

### When to use the CLI

The CLI interface is familiar to agents and allows for composability, so it's more useful for scripting and deterministic flows. It can be more token-efficient when working with large datasets because the agent can stream, filter, aggregate, or sample data before it enters the model context.

### When to use the MCP

MCP is useful when you're working with an AI agent that doesn't have access to terminal or shell commands. This is especially important in non-coding environments, where the agent may support tool calling but doesn't have access to a terminal.

MCP is also preferred when you want a native tool-calling experience, you need typed tool calls and results, and your workflows are happening in an AI client rather than script, CI, or shell.

### Setup for agents

Agents don't automatically know that a CLI tool exists or is available, so we need to tell them. The PostHog wizard installation path inserts agent instructions into the instructions file your agent reads, such as `AGENTS.md` or `CLAUDE.md`.

Terminal

PostHog AI

```bash
npx -y @posthog/wizard@latest cli add
```

If you wish to install the CLI directly, you should add a snippet in your agent's instructions or tell it directly to use the `posthog-cli` for PostHog tasks. You can manually install the snippet with `posthog-cli api agents-md install [--path AGENTS.md]`.

### 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:

Terminal

PostHog AI

```bash
posthog-cli api skill list
posthog-cli api skill install <skill-id>
```

To see all skills as JSON, pass `--json`:

Terminal

PostHog AI

```bash
posthog-cli api skill list --json
```

Installed skills are a snapshot. To refresh one after an update, reinstall it with `--force`:

Terminal

PostHog AI

```bash
posthog-cli api skill install --force <skill-id>
```

## 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 agent instructions globally for your agent — or use the CLI to install it into a single repo's instructions file:

Terminal

PostHog AI

```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:

Terminal

PostHog AI

```bash
npm install -g @posthog/cli@latest
posthog-cli api --agent-help
```

### 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:

Terminal

PostHog AI

```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:

Terminal

PostHog AI

```bash
posthog-cli api search dashboard
```

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better