Retrieve Traces via CLI

Phoenix CLI (@arizeai/phoenix-cli) is a command-line interface tool for retrieving trace data from your Phoenix projects. It allows you to use Phoenix’s tracing and debugging features directly in your terminal and development workflows.

You can use Phoenix CLI for the following use cases:

• Immediate debugging: Fetch the most recent trace of a failed or unexpected run with a single command.
• Bulk export for analysis: Export large numbers of traces to JSON files for offline analysis, building evaluation datasets, or regression tests.
• Terminal-based workflows: Integrate trace data into your existing tools; for example, piping output to Unix utilities like jq, or feeding traces into an AI coding assistant for automated analysis.
• AI coding assistant integration: Use with Claude Code, Cursor, Windsurf, or other AI-powered development tools to analyze and debug your LLM application traces.

Installation#

npm install -g @arizeai/phoenix-cli

Or run directly without installation:

npx @arizeai/phoenix-cli

Setup#

1. Set your Phoenix endpoint#

export PHOENIX_ENDPOINT=http://localhost:6006

For a remote deployment:

export PHOENIX_ENDPOINT=https://your-phoenix.example.com

2. Set your project name#

export PHOENIX_PROJECT=your-project-name

The CLI will automatically fetch traces from PHOENIX_PROJECT. Replace your-project-name with the name of your Phoenix project.

3. Set your API key (if required)#

export PHOENIX_API_KEY=your-api-key

Use with AI Coding Assistants#

The Phoenix CLI pairs well with AI coding assistants like Claude Code, Cursor, Windsurf, and others. There are two ways to wire it up.

Connect the assistant to Phoenix directly (recommended)#

Rather than pasting CLI output into a chat, connect the assistant to Phoenix once and let it query on its own:

• MCP — register the Phoenix MCP server with your agent using px setup mcp --agent cursor (swap in claude, codex, and so on). The agent then reaches your traces, projects, and docs through the remote MCP server built into Phoenix, without you copying anything by hand.
• Skills — px setup skills installs Phoenix skills so agents that support them know how to call the CLI. See Coding Agents.

Ask the assistant to run the CLI#

An assistant with terminal access can also run px directly. Ask Claude Code something like:

Use px to fetch the last 3 traces from my Phoenix project and analyze them for potential improvements

It discovers the available commands through px --help and fetches the traces itself. For an assistant without terminal access, run a command such as px trace list --limit 5 --format json yourself and paste the output into the chat.

Find Project and Trace IDs#

In most cases, you won’t need to find IDs manually (the CLI uses your environment’s project name and latest traces by default). However, if you want to fetch a specific item by ID, you can find the IDs in the Phoenix UI:

• Project Name/ID: Each project has a unique name and ID. You can find it in the project selector dropdown or in the project’s URL.
• Trace ID: Every trace has an ID. In the traces view, click on a specific trace to see its Trace ID (copyable from the trace details panel). You can use px trace get <trace-id> to retrieve that exact trace.

Usage#

After installation and setup, you can use the px command to retrieve traces. The general usage is:

px <resource> <action> [ARGUMENTS] [OPTIONS]

Phoenix CLI provides the following commands:

Options#

The commands support additional flags to filter and format the output:

Output formats#

The --format option controls how the fetched data is displayed:

• pretty (default): A human-readable tree view showing span hierarchy, status, and timing. Great for quick debugging:

  ┌─ Trace: abc123def456││  Input: What is the weather in San Francisco?│  Output: The weather is currently sunny...││  Spans:│  └─ ✓ agent_run (CHAIN) - 1250ms│     ├─ ✓ llm_call (LLM) - 800ms│     └─ ✓ tool_execution (TOOL) - 400ms└─

• json: Well-formatted JSON output with indentation. Use this if you want to examine the data structure:

  px trace get <trace-id> --format json

• raw: Compact JSON with no extra whitespace. Ideal for piping to jq or other tools:

  px trace get <trace-id> --format raw | jq '.spans[] | select(.span_kind == "LLM")'

Fetch a Single Trace#

You can fetch a single trace with its ID. The command will output to the terminal by default:

px trace get <trace-id>

You can optionally save the trace to a file using the --file option:

px trace get <trace-id> --file ./my-trace.json

To include span annotations in the trace export:

px trace get <trace-id> --include-annotations --format json

To fetch a trace from a different project than the one configured:

px trace get <trace-id> --project different-project

Fetch Multiple Traces#

You can specify a destination directory for bulk exports. For example, the following command will save the 10 most recent traces as JSON files in the my-traces-data directory:

px trace list ./my-traces-data --limit 10

Include span annotations in the export:

px trace list ./my-traces-data --limit 10 --include-annotations

If you omit the directory, the tool will output the results to your terminal:

px trace list --limit 10

When saving to a directory, files will be named by trace ID (e.g., 3b0b15fe-1e3a-4aef-afa8-48df15879cfe.json).

Filter by time#

Fetch traces from a specific time range:

# Traces from the last 30 minutespx trace list ./my-traces --limit 50 --last-n-minutes 30# Traces since a specific timepx trace list ./my-traces --since 2026-01-15T00:00:00Z

Export to Files#

You can fetch traces and export them for offline analysis or building datasets:

px trace list ./exported-traces --since 2026-01-01T00:00:00Z --limit 100

This command retrieves traces that occurred since January 1, 2026, saving each as a JSON file under ./exported-traces. This is useful for:

• Building regression test datasets
• Offline analysis and debugging
• Creating evaluation datasets for experiments

Sessions#

Sessions group multiple traces into a single multi-turn conversation. Use the session list and session get commands to explore them.

List Sessions#

px session list --limit 10px session list --format raw --no-progress | jq '.[].session_id'

View a Session#

px session get my-chat-session-001px session get my-chat-session-001 --include-annotationspx session get my-chat-session-001 --format raw | jq '.traces[].trace_id'

To drill into a specific turn’s input/output, use px trace get <trace-id> with the trace ID from the session output.

Trace Output Structure#

When using json or raw format, traces are output with the following structure:

{  "traceId": "abc123def456",  "spans": [    {      "name": "chat_completion",      "context": {        "trace_id": "abc123def456",        "span_id": "span-1"      },      "span_kind": "LLM",      "parent_id": null,      "start_time": "2026-01-17T10:00:00.000Z",      "end_time": "2026-01-17T10:00:01.250Z",      "status_code": "OK",      "attributes": {        "llm.model_name": "gpt-4",        "llm.token_count.prompt": 512,        "llm.token_count.completion": 256,        "input.value": "What is the weather?",        "output.value": "The weather is sunny..."      },      "annotations": [        {          "span_id": "span-1",          "name": "quality_score",          "annotator_kind": "LLM",          "result": {            "label": "good",            "score": 0.95          }        }      ]    }  ],  "rootSpan": { ... },  "startTime": "2026-01-17T10:00:00.000Z",  "endTime": "2026-01-17T10:00:01.250Z",  "duration": 1250,  "status": "OK"}

OpenInference Semantic Attributes#

Each span includes OpenInference semantic attributes in the attributes field:

• LLM spans: llm.model_name, llm.token_count.prompt, llm.token_count.completion, llm.invocation_parameters
• Input/Output: input.value, output.value, input.mime_type, output.mime_type
• Tool calls: tool.name, tool.description, tool.parameters
• Retrieval: retrieval.documents
• Errors: exception.type, exception.message, exception.stacktrace

AI Coding Assistant Examples#

Debug a Failed Agent Run#

# Fetch recent traces and find errorspx trace list --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

Then ask your AI assistant:

Here's a failed trace from my agent. Can you identify what went wrong and suggest a fix?

Analyze Agent Performance#

# Get traces sorted by durationpx trace list --limit 10 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:3]'

Ask your AI assistant:

Analyze these slow traces and suggest optimizations for my agent workflow

Review Token Usage#

# Extract LLM spans with token countspx trace list --limit 50 --format raw --no-progress | \  jq '[.[].spans[] | select(.span_kind == "LLM") | {name, model: .attributes["llm.model_name"], tokens: .attributes["llm.token_count.total"]}]'

Pipeline Examples#

The CLI is designed to work seamlessly in shell pipelines:

# Count traces with errorspx trace list --limit 100 --format raw --no-progress | \  jq '[.[] | select(.status == "ERROR")] | length'# Extract all LLM models usedpx trace list --limit 50 --format raw --no-progress | \  jq -r '.[].spans[] | select(.span_kind == "LLM") | .attributes["llm.model_name"] // empty' | \  sort -u# Get total duration across tracespx trace list --limit 100 --format raw --no-progress | \  jq '[.[].duration // 0] | add'

Troubleshooting#

”Phoenix endpoint not configured”#

Set the PHOENIX_ENDPOINT environment variable:

export PHOENIX_ENDPOINT=http://localhost:6006

Or use the --endpoint flag:

px trace list --endpoint http://localhost:6006 --limit 10

“Project not configured”#

Set the PHOENIX_PROJECT environment variable:

export PHOENIX_PROJECT=my-project

Or use the --project flag:

px trace list --project my-project --limit 10

“Failed to resolve project”#

Make sure your project name or ID is correct. List available projects:

px project list

Related#