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