@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 trace list --limit 1

# Fetch a specific trace by ID
px trace get abc123def456

# Fetch recent LLM spans
px span list --span-kind LLM --limit 10

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

px profile create prod \
  --endpoint https://prod.phoenix.example.com \
  --project main \
  --api-key sk-xxx \
  --activate

px profile list
px profile list --format json

px profile show           # active profile
px profile show staging   # specific profile

px profile use prod

px profile edit prod

px profile delete staging
px profile delete staging --yes  # skip confirmation

{
  "$schema": "https://raw.githubusercontent.com/Arize-ai/phoenix/main/schemas/phoenix-cli-settings.json",
  "activeProfile": "prod",
  "profiles": {
    "prod": {
      "endpoint": "https://prod.phoenix.example.com",
      "apiKey": "...",
      "project": "production"
    }
  }
}

px setup                                          # Interactive
px setup --endpoint https://phoenix.example.com   # Skip the endpoint prompt
npx -y @arizeai/phoenix-cli setup                 # Run without installing

# Connection only — write .env.phoenix, no source changes
px setup --no-input --endpoint http://localhost:6006 --project my-app

# Instrument too — requires --agent when there's no TTY to choose one
px setup --no-input --instrument --agent claude --yolo --language python --format raw

px setup instrument --agent codex   # Instrument and verify again
px setup skills                     # Install coding-agent skills only

px project list
px project list --format raw  # JSON output for piping

px project get my-project
px project get my-project --format raw --no-progress | jq -r '.id'  # Resolve name to ID

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

px trace get abc123def456
px trace get abc123def456 --file trace.json                # Save to file
px trace get abc123def456 --include-notes --format raw | jq # Include notes
px trace get abc123def456 --format raw | jq                # Pipe to jq

px trace annotate abc123def456 --name reviewer --label pass
px trace annotate abc123def456 --name reviewer --score 0.9 --format raw --no-progress
px trace annotate abc123def456 --name evaluator --label pass --annotator-kind LLM
px trace annotate abc123def456 --name reviewer --explanation "needs follow-up"

px trace add-note abc123def456 --text "needs follow-up"
px trace add-note abc123def456 --text "agent triage complete" --format raw --no-progress

px trace-annotations delete --identifier "$PHOENIX_CODING_IDENTIFIER" --all -y
px trace-annotations delete --start-time 2026-01-01T00:00:00Z --end-time 2026-01-02T00:00:00Z -y

px span list --limit 20                                    # Recent spans (table view)
px span list --last-n-minutes 60 --limit 50                # Spans from last hour
px span list --span-kind LLM --limit 10                    # Only LLM spans
px span list --status-code ERROR --limit 20                # Only errored spans
px span list --span-kind LLM TOOL --status-code OK         # Combine filters
px span list --name chat_completion --limit 10             # Filter by span name
px span list --trace-id abc123 --format raw | jq           # All spans for a trace
px span list --attribute llm.model_name:gpt-4              # Filter by attribute
px span list --attribute llm.model_name:gpt-4 --attribute user.role:admin  # AND filters
px span list --include-annotations --limit 10              # Include annotation scores
px span list output.json --limit 100                       # Save to JSON file
px span list --format raw --no-progress | jq               # Pipe to jq

px span annotate 7e2f08cb43bbf521 --name reviewer --label pass
px span annotate 7e2f08cb43bbf521 --name reviewer --score 0.9 --format raw --no-progress
px span annotate 7e2f08cb43bbf521 --name checker --score 1 --annotator-kind CODE
px span annotate 7e2f08cb43bbf521 --name reviewer --explanation "looks good"

px span add-note abc123def456 --text "Escalated: retrieval returned empty results"
px span add-note abc123def456 --text "Reviewed by on-call" --format json

px span-annotations delete --identifier "$PHOENIX_CODING_IDENTIFIER" --all -y

px session list                                              # List recent sessions
px session list --limit 20                                   # More sessions
px session list --order asc                                  # Oldest first
px session list --include-annotations --include-notes        # With annotations and notes
px session list --format raw --no-progress | jq              # Pipe to jq

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

px session annotate my-session-id --name correctness --label pass
px session annotate my-session-id --name correctness --score 0.9 --format raw --no-progress
px session annotate my-session-id --name groundedness --label pass --annotator-kind LLM
px session annotate my-session-id --name correctness --explanation "needs follow-up"

px session add-note my-session-id --text "needs follow-up"
px session add-note my-session-id --text "agent triage complete" --format raw --no-progress

px session-annotations delete --identifier "$PHOENIX_CODING_IDENTIFIER" --all -y

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

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

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

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

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

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

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

px annotation-config list                                            # Table view
px annotation-config list --limit 10                                 # At most 10 configs
px annotation-config list --format raw --no-progress | jq -r '.[].name'  # Names as JSON

px annotation-config get response-quality                                    # Look up by name
px annotation-config get response-quality --format raw --no-progress | jq -r '.id'  # Resolve name to ID

# Categorical config with scored labels
px annotation-config create --type CATEGORICAL --name response-quality \
  --value good=1 --value bad=0 --optimization-direction MAXIMIZE

# Continuous config bounded between 0 and 1
px annotation-config create --type CONTINUOUS --name confidence --lower-bound 0 --upper-bound 1

# Free-text config
px annotation-config create --type FREEFORM --name reviewer-notes --description 'Free-form reviewer feedback'

# Categorical labels as a JSON payload (bulk/agent alternative to --value)
px annotation-config create --type CATEGORICAL --name response-quality \
  --values '[{"label":"good","score":1},{"label":"bad","score":0}]'

# Change only the description
px annotation-config update response-quality --description 'Pass/fail rating from human review'

# Rename and set optimization direction
px annotation-config update response-quality --name answer-quality --optimization-direction MAXIMIZE

# Replace the label set of a categorical config
px annotation-config update response-quality --value good=1 --value acceptable=0.5 --value bad=0

px annotation-config delete QW5ub3RhdGlvbkNvbmZpZzoxMjM=          # Interactive confirmation
px annotation-config delete QW5ub3RhdGlvbkNvbmZpZzoxMjM= --yes    # Skip the prompt (scripts/agents)

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 trace list --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

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

px span list --status-code ERROR --limit 50 --format raw --no-progress | jq '.[] | {name, status_message}'

px span list --span-kind LLM --include-annotations --limit 20

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

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

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

# List experiments for a dataset
px experiment list --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 experiment list --dataset query_response ./experiments/

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

# Find failed runs in an experiment
px experiment get 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 get RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'

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

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

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

# Get a specific tagged version
px prompt get 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 get 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 get 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 get 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