Skip to main content

​
Agent-Assisted Setup

The fastest way to add Phoenix tracing to your application. One command connects your app to Phoenix, hands the instrumentation to your coding agent, and confirms a real trace arrived — so “done” means traces are actually flowing.
Run this from your app’s root directory:
Already installed the CLI (npm install -g @arizeai/phoenix-cli)? Just run px setup.
Supported stacks: Python and TypeScript/JavaScript. See the full integration list for the LLM providers and frameworks Phoenix instruments.

​
What happens when you run it

px setup walks you through an interactive flow with five steps:
  1. Checks git safety. Warns on a dirty tree so agent edits stay separate from your own work.
  2. Establishes the connection. Asks where your Phoenix instance is running, handles auth, and writes a gitignored .env.phoenix file.
  3. Hands off instrumentation. Passes an instrumentation task to a coding agent (Claude Code, Codex, Cursor, or OpenCode), which detects your language, LLM providers, and frameworks, then adds tracing.
  4. Verifies traces. Waits until the Phoenix API confirms a real trace arrived.
  5. Sets up tooling. Optionally points px at the new project and installs Phoenix skills so your agent can query what you captured.

​
Confirm traces are flowing

px setup verifies traces automatically. To check for yourself:
  1. Run your application and trigger at least one LLM call.
  2. Open the Phoenix UI (local: http://localhost:6006, or your deployment URL).
  3. Open the Traces view and verify traces appear under your project.
If no traces appear, check the Troubleshooting FAQ.

​
Re-run a single step

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

​
Run non-interactively (CI or agents)

Pass flags instead of answering prompts:
A run that instruments only succeeds if a trace actually arrived — the agent’s own claim that it finished doesn’t count. Exit code 6 means the wait ran out with no trace, so tracing isn’t confirmed working even though the connection, .env.phoenix, and the agent’s edits are all in place. In a pipeline, treat 6 as “configured but unverified” rather than a hard failure: re-run px setup instrument or check the exporter. In --format json|raw, the verification field carries the same verdict. See the CLI reference for the full list of flags.

​
Use an unsupported agent

px setup hands off to Claude Code, Codex, Cursor, and OpenCode. If your agent isn’t one of those (Windsurf, Copilot, and others), paste this prompt into it instead:
For ongoing agent workflows beyond initial setup (CLI, MCP, and skills), see the Coding Agents guide.