@arizeai/phoenix-cli

npm install -g @arizeai/phoenix-cli

npx @arizeai/phoenix-cli

# Configure your Phoenix instanceexport PHOENIX_ENDPOINT=http://localhost:6006export PHOENIX_PROJECT=my-projectexport PHOENIX_API_KEY=your-api-key  # if authentication is enabled# Fetch the most recent tracepx trace list --limit 1# Fetch a specific trace by IDpx trace get abc123def456# Fetch recent LLM spanspx span list --span-kind LLM --limit 10# Export traces to a directorypx 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 listpx profile list --format json

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

px profile use prod

px profile edit prod

px profile delete stagingpx 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                                          # Interactivepx setup --endpoint https://phoenix.example.com   # Skip the endpoint promptnpx -y @arizeai/phoenix-cli setup                 # Run without installing

# Connection only — write .env.phoenix, no source changespx setup --no-input --endpoint http://localhost:6006 --project my-app# Instrument too — requires --agent when there's no TTY to choose onepx setup --no-input --instrument --agent claude --yolo --language python --format raw

px setup instrument --agent codex   # Instrument and verify againpx setup skills                     # Install coding-agent skills onlypx setup mcp --agent claude         # Register the Phoenix MCP server with an agent

px setup mcp                        # Pick scope + agent interactivelypx setup mcp --agent codex          # Configure one agentpx setup mcp --agent claude --local # Write this repo's config (.mcp.json)

px setup mcp --agent codex --no-input --format rawpx setup mcp --agent claude --header 'Authorization: Bearer ${PHOENIX_API_KEY}'

pxi                                                # uses PHOENIX_ENDPOINT / PHOENIX_API_KEYpxi --endpoint http://localhost:6006 --provider OPENAI --model gpt-5.4npx -y @arizeai/phoenix-cli pxi                    # run without installing

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

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

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

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

px trace annotate abc123def456 --name reviewer --label passpx trace annotate abc123def456 --name reviewer --score 0.9 --format raw --no-progresspx trace annotate abc123def456 --name evaluator --label pass --annotator-kind LLMpx 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 -ypx 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 hourpx span list --span-kind LLM --limit 10                    # Only LLM spanspx span list --status-code ERROR --limit 20                # Only errored spanspx span list --span-kind LLM TOOL --status-code OK         # Combine filterspx span list --name chat_completion --limit 10             # Filter by span namepx span list --trace-id abc123 --format raw | jq           # All spans for a tracepx span list --attribute llm.model_name:gpt-4              # Filter by attributepx span list --attribute llm.model_name:gpt-4 --attribute user.role:admin  # AND filterspx span list --include-annotations --limit 10              # Include annotation scorespx span list output.json --limit 100                       # Save to JSON filepx span list --format raw --no-progress | jq               # Pipe to jq

px span annotate 7e2f08cb43bbf521 --name reviewer --label passpx span annotate 7e2f08cb43bbf521 --name reviewer --score 0.9 --format raw --no-progresspx span annotate 7e2f08cb43bbf521 --name checker --score 1 --annotator-kind CODEpx 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 sessionspx session list --limit 20                                   # More sessionspx session list --order asc                                  # Oldest firstpx session list --include-annotations --include-notes        # With annotations and notespx session list --format raw --no-progress | jq              # Pipe to jq

px session get my-chat-session-001                              # By session_idpx session get UHJvamVjdFNlc3Npb24...                           # By GlobalIDpx session get my-chat-session-001 --include-annotations        # With annotationspx session get my-chat-session-001 --include-notes              # With notespx session get my-chat-session-001 --file session.json          # Save to filepx session get my-chat-session-001 --format raw | jq            # Pipe to jq

px session annotate my-session-id --name correctness --label passpx session annotate my-session-id --name correctness --score 0.9 --format raw --no-progresspx session annotate my-session-id --name groundedness --label pass --annotator-kind LLMpx 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 listpx dataset list --format json                    # JSON outputpx dataset list --format raw --no-progress | jq  # Pipe to jq

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

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

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

px prompt listpx prompt list --format json                    # JSON outputpx 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 tagpx prompt get my-assistant-prompt --version abc123   # Specific versionpx prompt get my-assistant-prompt --format json      # JSON outputpx 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 viewpx annotation-config list --limit 10                                 # At most 10 configspx annotation-config list --format raw --no-progress | jq -r '.[].name'  # Names as JSON

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

# Categorical config with scored labelspx annotation-config create --type CATEGORICAL --name response-quality \  --value good=1 --value bad=0 --optimization-direction MAXIMIZE# Continuous config bounded between 0 and 1px annotation-config create --type CONTINUOUS --name confidence --lower-bound 0 --upper-bound 1# Free-text configpx 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 descriptionpx annotation-config update response-quality --description 'Pass/fail rating from human review'# Rename and set optimization directionpx annotation-config update response-quality --name answer-quality --optimization-direction MAXIMIZE# Replace the label set of a categorical configpx annotation-config update response-quality --value good=1 --value acceptable=0.5 --value bad=0

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

px auth login                          # browser-based OAuth login into the active profilepx auth login --no-browser             # print the URL instead of opening a browserpx auth login --profile staging        # log in to a named profile

px auth logout                         # clear the stored sessionpx auth logout --profile staging       # clear a named profile's session

px auth status                         # show the current session/identitypx auth status --profile staging       # inspect a named profile

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 datasetspx dataset list --format raw --no-progress | jq '.[].name'# Output: "query_response"# List experiments for a datasetpx 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 directorypx experiment list --dataset query_response ./experiments/

# Get input queries and latency from an experimentpx experiment get RXhwZXJpbWVudDox --format raw --no-progress | \  jq '.[] | {query: .input.query, latency_ms, trace_id}'# Find failed runs in an experimentpx 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 runspx experiment get RXhwZXJpbWVudDox --format raw --no-progress | \  jq '[.[].latency_ms] | add / length'

# List all promptspx prompt list --format raw --no-progress | jq '.[].name'# Get prompt template contentpx prompt get my-evaluator --format text --no-progress# View prompt with all metadatapx prompt get my-evaluator --format json --no-progress | jq '.template'# Get a specific tagged versionpx 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 ideaspx prompt get my-evaluator --format text --no-progress | claude -p "Review this prompt and suggest improvements for clarity and effectiveness"# Analyze prompt for edge casespx prompt get my-assistant --format text --no-progress | claude -p "What edge cases might this prompt fail to handle?"# Generate test cases for a promptpx 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