@arizeai/phoenix-cli

npm install -g @arizeai/phoenix-cli

npx @arizeai/phoenix-cli

# Configure your Phoenix instance
export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # if authentication is enabled

# Fetch the most recent trace
px traces --limit 1

# Fetch a specific trace by ID
px trace abc123def456

# Export traces to a directory
px traces ./my-traces --limit 50

px projects
px projects --format raw  # JSON output for piping

px traces --limit 10                          # Output to stdout
px traces ./my-traces --limit 10              # Save to directory
px traces --last-n-minutes 60 --limit 20      # Filter by time
px traces --since 2026-01-13T10:00:00Z        # Since timestamp
px traces --format raw --no-progress | jq     # Pipe to jq

px trace abc123def456
px trace abc123def456 --file trace.json      # Save to file
px trace abc123def456 --format raw | jq      # Pipe to jq

px sessions                                       # List recent sessions
px sessions --limit 20                            # More sessions
px sessions --order asc                           # Oldest first
px sessions --format raw --no-progress | jq       # Pipe to jq

px session my-chat-session-001                              # By session_id
px session UHJvamVjdFNlc3Npb24...                           # By GlobalID
px session my-chat-session-001 --include-annotations        # With annotations
px session my-chat-session-001 --file session.json          # Save to file
px session my-chat-session-001 --format raw | jq            # Pipe to jq

px datasets
px datasets --format json                    # JSON output
px datasets --format raw --no-progress | jq  # Pipe to jq

px dataset query_response                        # Fetch all examples
px dataset query_response --split train          # Filter by split
px dataset query_response --split train --split test  # Multiple splits
px dataset query_response --version <version-id> # Specific version
px dataset query_response --file dataset.json    # Save to file
px dataset query_response --format raw | jq '.examples[].input'

px experiments --dataset my-dataset                 # List experiments
px experiments --dataset my-dataset --format json   # JSON output
px experiments --dataset my-dataset ./experiments   # Export to directory

px experiment RXhwZXJpbWVudDox
px experiment RXhwZXJpbWVudDox --file exp.json   # Save to file
px experiment RXhwZXJpbWVudDox --format json     # JSON output

px prompts
px prompts --format json                    # JSON output
px prompts --format raw --no-progress | jq  # Pipe to jq

px prompt my-assistant-prompt                    # Latest version (pretty)
px prompt my-assistant-prompt --tag production   # Get by tag
px prompt my-assistant-prompt --version abc123   # Specific version
px prompt my-assistant-prompt --format json      # JSON output
px prompt my-assistant-prompt --format text      # Plain text for piping

<system>You are a helpful assistant specialized in...</system>
<user>{{user_input}}</user>

px api graphql '<query>' [--endpoint <url>] [--api-key <key>]

$ px api graphql '{ __schema { queryType { fields { name } } } }' | \
    jq '.data.__schema.queryType.fields[].name'
"projects"
"datasets"
"prompts"
"evaluators"
"projectCount"
"datasetCount"
"promptCount"
"evaluatorCount"
"serverStatus"
"viewer"
...

$ px api graphql '{ __type(name: "Experiment") { fields { name type { name } } } }' | \
    jq '.data.__type.fields[] | {name, type: .type.name}'
{"name": "id", "type": "ID"}
{"name": "name", "type": "String"}
{"name": "runCount", "type": "Int"}
{"name": "errorRate", "type": "Float"}
{"name": "averageRunLatencyMs", "type": "Float"}

$ px api graphql '{ projects { edges { node { name traceCount tokenCountTotal } } } }'
{
  "data": {
    "projects": {
      "edges": [
        { "node": { "name": "default", "traceCount": 1482, "tokenCountTotal": 219083 } }
      ]
    }
  }
}

$ px api graphql '{ projects { edges { node { name traceCount } } } }' | \
    jq '.data.projects.edges[].node'
{"name": "default", "traceCount": 1482}

$ px api graphql '{ datasets { edges { node { name exampleCount experimentCount } } } }' | \
    jq '.data.datasets.edges[].node'
{"name": "eval-golden-set", "exampleCount": 120, "experimentCount": 4}
{"name": "rag-test-cases", "exampleCount": 50, "experimentCount": 1}

$ px api graphql '{ datasetCount }' | jq '.data.datasetCount'
12

$ px api graphql '{
  datasets {
    edges {
      node {
        name
        experiments {
          edges {
            node { name runCount errorRate averageRunLatencyMs }
          }
        }
      }
    }
  }
}' | jq '.data.datasets.edges[].node | {dataset: .name, experiments: [.experiments.edges[].node]}'

# Find experiments with non-zero error rate
$ px api graphql '{
  datasets { edges { node { name experiments { edges { node { name errorRate runCount } } } } } }
}' | jq '.. | objects | select(.errorRate? > 0)'

$ px api graphql '{
  datasets(first: 1) {
    edges { node { experiments(first: 1) { edges { node {
      name
      runs { edges { node { traceId output error latencyMs } } }
    } } } } }
  }
}' | jq '.data.datasets.edges[0].node.experiments.edges[0].node.runs.edges[].node'
{"traceId": "b696d0ac...", "output": {"answer": "Moore's Law is..."}, "error": null, "latencyMs": 1006}

$ px api graphql '{ evaluators { edges { node { name kind description isBuiltin } } } }' | \
    jq '.data.evaluators.edges[].node'
{"name": "correctness", "kind": "LLM", "description": "Evaluates answer correctness", "isBuiltin": true}

$ px api graphql '{ projectCount datasetCount promptCount evaluatorCount }'
{
  "data": {
    "projectCount": 1,
    "datasetCount": 12,
    "promptCount": 3,
    "evaluatorCount": 2
  }
}

## Output Formats

**`pretty`** (default) — Human-readable tree view:

**`json`** — Formatted JSON with indentation.

**`raw`** — Compact JSON for piping to `jq` or other tools.

## JSON Structure

```json
{
  "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..."
      }
    }
  ],
  "rootSpan": { ... },
  "startTime": "2026-01-17T10:00:00.000Z",
  "endTime": "2026-01-17T10:00:01.250Z",
  "duration": 1250,
  "status": "OK"
}

px traces --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

px traces --limit 10 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:3]'

px traces --limit 50 --format raw --no-progress | \
  jq -r '.[].spans[] | select(.span_kind == "LLM") | .attributes["llm.model_name"]' | sort -u

px traces --limit 100 --format raw --no-progress | jq '[.[] | select(.status == "ERROR")] | length'

# List all datasets
px datasets --format raw --no-progress | jq '.[].name'
# Output: "query_response"

# List experiments for a dataset
px experiments --dataset query_response --format raw --no-progress | \
  jq '.[] | {id, successful_run_count, failed_run_count}'
# Output: {"id":"RXhwZXJpbWVudDox","successful_run_count":249,"failed_run_count":1}

# Export all experiment data for a dataset to a directory
px experiments --dataset query_response ./experiments/

# Get input queries and latency from an experiment
px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '.[] | {query: .input.query, latency_ms, trace_id}'

# Find failed runs in an experiment
px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '.[] | select(.error != null) | {query: .input.query, error}'
# Output: {"query":"looking for complex fodmap meal ideas","error":"peer closed connection..."}

# Calculate average latency across runs
px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'

# List all prompts
px prompts --format raw --no-progress | jq '.[].name'

# Get prompt template content
px prompt my-evaluator --format text --no-progress

# View prompt with all metadata
px prompt my-evaluator --format json --no-progress | jq '.template'

# Get a specific tagged version
px prompt my-evaluator --tag production --format text --no-progress

# Quick instance summary
$ px api graphql '{ projectCount datasetCount promptCount evaluatorCount }'
{"data": {"projectCount": 1, "datasetCount": 12, "promptCount": 3, "evaluatorCount": 2}}

# Discover all available query fields
$ px api graphql '{ __schema { queryType { fields { name } } } }' | \
    jq '.data.__schema.queryType.fields[].name'

# Projects with stats
$ px api graphql '{ projects { edges { node { name traceCount tokenCountTotal } } } }' | \
    jq '.data.projects.edges[].node'

# Datasets with counts
$ px api graphql '{ datasets { edges { node { name exampleCount experimentCount } } } }' | \
    jq '.data.datasets.edges[].node'

# Find experiments with errors
$ px api graphql '{
  datasets { edges { node { name experiments { edges { node { name errorRate runCount } } } } } }
}' | jq '.. | objects | select(.errorRate? > 0)'

# Drill into run outputs
$ px api graphql '{
  datasets(first: 1) { edges { node {
    experiments(first: 1) { edges { node {
      runs { edges { node { traceId output error latencyMs } } }
    } } }
  } } }
}' | jq '.data.datasets.edges[0].node.experiments.edges[0].node.runs.edges[].node'

# Get viewer info (authenticated instances)
$ px api graphql '{ viewer { username email } }'

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

# Get prompt optimization ideas
px prompt my-evaluator --format text --no-progress | claude -p "Review this prompt and suggest improvements for clarity and effectiveness"

# Analyze prompt for edge cases
px prompt my-assistant --format text --no-progress | claude -p "What edge cases might this prompt fail to handle?"

# Generate test cases for a prompt
px prompt my-classifier --format text --no-progress | claude -p "Generate 5 diverse test inputs to evaluate this prompt"

Fetch my "correctness-evaluator" prompt from Phoenix and suggest how to make the rubric more specific

Fetch my recent Phoenix traces using px and explain what my agent is doing

List my Phoenix prompts with px and help me improve the system prompt for my assistant