> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Phoenix CLI

> Let any coding agent query your Phoenix traces, datasets, experiments, and prompts from the terminal.

`px` is the Phoenix CLI. Any coding agent with a terminal can use it to reach your traces, sessions, datasets, experiments, and prompts: you ask in plain language, the agent runs `px` underneath. The [`phoenix-cli` skill](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/developer-tools/skills) teaches it the commands.

## CLI or MCP server?

Start with the [MCP server](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/mcp.md). It's what the plugins set up, it reaches every Phoenix operation, and it serves the Phoenix skills that match your server. The CLI is optional.

Add the CLI when you want any of these:

* Commands you can see, copy, and run yourself.
* Phoenix access from scripts and CI.
* An agent that has a shell but no MCP support.

| | Phoenix CLI (`px`) | [MCP server](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/mcp.md) |
| - | - | - |
| Setup | Install, set `PHOENIX_ENDPOINT` | A [plugin](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/developer-tools/coding-agents.md#plugins), or `<your-endpoint>/mcp` in your agent's MCP config |
| Surface | The `px` commands | Every Phoenix REST operation, composed in one `execute` call |
| Output | Tables, or `--format json` | Results filtered and joined server-side |
| Skills | `phoenix-cli`, installed as a file | Four Phoenix skills, served by the server |

## Install

Install the Phoenix CLI globally:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install -g @arizeai/phoenix-cli
```

Point it at your Phoenix instance. Add `PHOENIX_API_KEY` if your instance has auth enabled.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export PHOENIX_ENDPOINT=http://localhost:6006
```

Verify the install and the connection:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
px --help
px project list
```

`project list` works before you have sent a single trace: every Phoenix has a project named `default`, created on first start, where traces land when no project name is set. A wrong endpoint fails with `Error fetching projects: fetch failed`.

Once your app is sending traces to a named project, set `PHOENIX_PROJECT` to that name so commands do not need `--project`. Not sending traces yet? [Connect a project with px setup](#connect-a-project-with-px-setup) wires an app to Phoenix and waits for a real trace.

To teach your agent the commands, install the `phoenix-cli` skill. The Claude Code, Codex, and Cursor plugins already include it.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx skills add Arize-ai/phoenix --skill phoenix-cli
```

## Connect a project with px setup

`px setup` is the fastest way to add tracing to an app. Run it from the app's root directory while Phoenix is running. It saves the connection (endpoint, project, and key) to a gitignored `.env.phoenix` file, hands your coding agent the instrumentation task, and does not finish until a real trace arrives. It hands off to Claude Code, Codex, Cursor, and OpenCode.

```bash npx theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx -y @arizeai/phoenix-cli setup
```

```bash Installed theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
px setup
```

`px setup` warns on a dirty git tree before it starts, so the agent's edits stay separate from your own work. When it finishes, open your project in Phoenix and check the **Traces** tab. If nothing arrived, see the [tracing FAQ](https://arizeai-433a7140.mintlify.site/docs/phoenix/tracing/concepts-tracing/faqs-tracing.md).

### Re-run one step

The connection questions only need answering once. On a project that is already registered, re-run just the slice you need:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
px setup instrument   # Instrument and verify traces again
px setup skills       # Install the coding-agent skills alone
```

### Run without prompts (CI or agents)

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Connection only. Writes .env.phoenix, no source changes.
px setup --no-input --endpoint http://localhost:6006 --project my-app

# Instrument too. --agent is required when there is no terminal to choose one.
px setup --no-input --instrument --agent claude --yolo --format raw
```

A run that instruments succeeds only if a trace arrived; the agent's own claim that it finished does not count. Exit code `6` means the wait ran out with no trace: the connection, `.env.phoenix`, and the agent's edits are in place, but tracing is unverified. In a pipeline, treat `6` as "configured but unverified" and re-run `px setup instrument`. Pass `--docs-mcp` or `--no-docs-mcp` so a non-interactive run never stalls on the docs MCP question. In `--format json|raw`, the `verification` field carries the same verdict. The [CLI reference](https://arizeai-433a7140.mintlify.site/docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-cli.md#px-setup) lists every flag.

### Use an unsupported agent

If your agent is not one of the four, paste this prompt into it instead:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Follow the instructions from https://raw.githubusercontent.com/Arize-ai/phoenix/main/docs/PROMPT.md and ask me questions as needed.
```

## What your agent can do with it

Common agent workflows with `px`:

* investigate trace failures and performance regressions
* inspect and compare experiment runs
* list and fetch datasets for evaluation workflows
* inspect and retrieve prompt versions and content
* annotate spans and traces with what it found, so the finding stays with the data

Example prompt:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Debug my agent's tool-call failures. Use Phoenix CLI to inspect traces, recent experiments, and relevant prompts, then summarize root causes.
```

Annotations, notes, and annotation configs are the only things `px` writes to Phoenix. It does not create datasets, edit prompts, or run experiments; do that with the SDK, as in [Evaluate](https://arizeai-433a7140.mintlify.site/docs/phoenix/get-started/get-started-evaluations.md), or from the UI. The fix itself goes in your code.

## Learn more

* [Connect Your Coding Agent](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/developer-tools/coding-agents.md) gives the recommended setup for each agent.
* `px --help` lists every command, and `px <command> --help` its flags. The [CLI reference](https://arizeai-433a7140.mintlify.site/docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-cli.md) has them all.
* [Skills](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/developer-tools/skills.md) teach an agent how to use these commands.
* [MCP Server](https://arizeai-433a7140.mintlify.site/docs/phoenix/integrations/mcp.md) is the recommended way to connect an agent, with or without a shell.
* [PXI](https://arizeai-433a7140.mintlify.site/docs/phoenix/pxi.md) is the same idea inside Phoenix itself, with no terminal.