Skip to main content
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 teaches it the commands.

​
CLI or MCP server?

Start with the MCP server. 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.

​
Install

Install the Phoenix CLI globally:
Point it at your Phoenix instance. Add PHOENIX_API_KEY if your instance has auth enabled.
Verify the install and the connection:
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 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.

​
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.
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.

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

​
Run without prompts (CI or agents)

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 lists every flag.

​
Use an unsupported agent

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

​
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:
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, or from the UI. The fix itself goes in your code.

​
Learn more

  • Connect Your Coding Agent gives the recommended setup for each agent.
  • px --help lists every command, and px <command> --help its flags. The CLI reference has them all.
  • Skills teach an agent how to use these commands.
  • MCP Server is the recommended way to connect an agent, with or without a shell.
  • PXI is the same idea inside Phoenix itself, with no terminal.