diff --git a/contents/docs/cli.mdx b/contents/docs/cli.mdx
new file mode 100644
index 000000000000..1ec9b09d8e8b
--- /dev/null
+++ b/contents/docs/cli.mdx
@@ -0,0 +1,281 @@
+---
+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.
+
+## Install the CLI
+
+Install `posthog-cli` globally:
+
+```bash
+npm install -g @posthog/cli
+```
+
+Or install the latest release with the installer script. This also installs `posthog-cli-update`, which updates the script-installed binary:
+
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PostHog/posthog/releases/latest/download/posthog-cli-installer.sh | sh
+posthog-cli-update
+```
+
+Check that the CLI is installed:
+
+```bash
+posthog-cli --version
+```
+
+## Authenticate
+
+For local use, log in through your browser:
+
+```bash
+posthog-cli login
+```
+
+This stores a personal API token locally and reuses it for CLI commands, including `posthog-cli api`.
+
+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 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.
+
+## 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.
+
+> **Experimental:** the `api` command group is gated behind an opt-in while it stabilizes. Set `POSTHOG_CLI_EXPERIMENTAL_API=1` in the environment, or pass `--experimental` immediately after `api`.
+
+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 `<posthog>...</posthog>` 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 <skill-id>
+```
+
+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 <skill-id>
+```
+
+## 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 <regex>
+posthog-cli api info [--json] <tool>
+posthog-cli api schema <tool> [field.path]
+posthog-cli api call [--json] [--dry-run] [--confirm] <tool> '<json>'
+posthog-cli api skill list [--json]
+posthog-cli api skill install [--force] <skill-id>
+posthog-cli api agents-md install [--path AGENTS.md]
+```
+
+For EU Cloud, either set `POSTHOG_CLI_HOST=https://eu.posthog.com` or pass `--host`:
+
+```bash
+posthog-cli --host https://eu.posthog.com api search feature-flag
+```
+
+## Troubleshooting and FAQ
+
+### The command group is disabled
+
+`posthog-cli api` is experimental. If it reports that the command group is disabled, set `POSTHOG_CLI_EXPERIMENTAL_API=1` in the environment or pass `--experimental` immediately after `api`.
+
+### 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`.
+
+### 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 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, or invoke the latest release directly without installing:
+
+```bash
+npx -y @posthog/cli@latest api search feature-flag
+```
+
+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 <skill-id>
+```
+
+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 <skill-id>
+```
+
+### The installed `AGENTS.md` snippet is outdated
+
+Rerun the install with the latest CLI. The snippet lives in a `<posthog>...</posthog>` 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
+```