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?

  • CLI: your agent runs px commands in the terminal. You see each command and can run it yourself. Use it with agents that can run shell commands, such as Claude Code, Codex, and Cursor.
  • MCP server: your agent talks to Phoenix directly, with no commands to run. Use it with agents that have no terminal, such as Claude Desktop, or when you installed the Claude Code or Codex plugin, which sets it up for you.

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

​
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 installs the CLI alongside the MCP server and skills for your 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 alternative for clients that cannot run a shell.
  • PXI is the same idea inside Phoenix itself, with no terminal.