---
name: phoenix-cli
description: Debug LLM applications using the Phoenix CLI. Fetch traces, analyze errors, review experiments, and inspect datasets. Use when debugging AI/LLM applications, analyzing trace data, working with Phoenix observability, or investigating LLM performance issues.
license: Apache-2.0
metadata:
author: arize-ai
version: "1.0"
---
# Phoenix CLI
Debug and analyze LLM applications using the Phoenix CLI (`px`).
## Quick Start
### Installation
```bash
npm install -g @arizeai/phoenix-cli
# Or run directly with npx
npx @arizeai/phoenix-cli
```
### Configuration
Set environment variables before running commands:
```bash
export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key # if authentication is enabled
```
CLI flags override environment variables when specified.
## Debugging Workflows
### Debug a failing LLM application
1. Fetch recent traces to see what's happening:
```bash
px traces --limit 10
```
2. Find failed traces:
```bash
px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
```
3. Get details on a specific trace:
```bash
px trace <trace-id>
```
4. Look for errors in spans:
```bash
px trace <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'
```
### Find performance issues
1. Get the slowest traces:
```bash
px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
```
2. Analyze span durations within a trace:
```bash
px trace <trace-id> --format raw | jq '.spans | sort_by(-.duration_ms) | .[0:5] | .[] | {name, duration_ms, span_kind}'
```
### Analyze LLM usage
Extract models and token counts:
```bash
px traces --limit 50 --format raw --no-progress | \
jq -r '.[].spans[] | select(.span_kind == "LLM") | {model: .attributes["llm.model_name"], prompt_tokens: .attributes["llm.token_count.prompt"], completion_tokens: .attributes["llm.token_count.completion"]}'
```
### Review experiment results
1. List datasets:
```bash
px datasets
```
2. List experiments for a dataset:
```bash
px experiments --dataset my-dataset
```
3. Analyze experiment failures:
```bash
px experiment <experiment-id> --format raw --no-progress | \
jq '.[] | select(.error != null) | {input: .input, error}'
```
4. Calculate average latency:
```bash
px experiment <experiment-id> --format raw --no-progress | \
jq '[.[].latency_ms] | add / length'
```
## Command Reference
### px traces
Fetch recent traces from a project.
```bash
px traces [directory] [options]
```
| Option | Description |
|--------|-------------|
| `[directory]` | Save traces as JSON files to directory |
| `-n, --limit <number>` | Number of traces (default: 10) |
| `--last-n-minutes <number>` | Filter by time window |
| `--since <timestamp>` | Fetch since ISO timestamp |
| `--format <format>` | `pretty`, `json`, or `raw` |
| `--include-annotations` | Include span annotations |
### px trace
Fetch a specific trace by ID.
```bash
px trace <trace-id> [options]
```
| Option | Description |
|--------|-------------|
| `--file <path>` | Save to file |
| `--format <format>` | `pretty`, `json`, or `raw` |
| `--include-annotations` | Include span annotations |
### px datasets
List all datasets.
```bash
px datasets [options]
```
### px dataset
Fetch examples from a dataset.
```bash
px dataset <dataset-name> [options]
```
| Option | Description |
|--------|-------------|
| `--split <name>` | Filter by split (repeatable) |
| `--version <id>` | Specific dataset version |
| `--file <path>` | Save to file |
### px experiments
List experiments for a dataset.
```bash
px experiments --dataset <name> [directory]
```
| Option | Description |
|--------|-------------|
| `--dataset <name>` | Dataset name or ID (required) |
| `[directory]` | Export experiment JSON to directory |
### px experiment
Fetch a single experiment with run data.
```bash
px experiment <experiment-id> [options]
```
### px prompts
List all prompts.
```bash
px prompts [options]
```
### px prompt
Fetch a specific prompt.
```bash
px prompt <prompt-name> [options]
```
## Output Formats
- **`pretty`** (default): Human-readable tree view
- **`json`**: Formatted JSON with indentation
- **`raw`**: Compact JSON for piping to `jq` or other tools
Use `--format raw --no-progress` when piping output to other commands.
## Trace Structure
Traces contain spans with OpenInference semantic attributes:
```json
{
"traceId": "abc123",
"spans": [{
"name": "chat_completion",
"span_kind": "LLM",
"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..."
}
}],
"duration": 1250,
"status": "OK"
}
```
Key span kinds: `LLM`, `CHAIN`, `TOOL`, `RETRIEVER`, `EMBEDDING`, `AGENT`.
Key attributes for LLM spans:
- `llm.model_name`: Model used
- `llm.provider`: Provider name (e.g., "openai")
- `llm.token_count.prompt` / `llm.token_count.completion`: Token counts
- `llm.input_messages.*`: Input messages (indexed, with role and content)
- `llm.output_messages.*`: Output messages (indexed, with role and content)
- `input.value` / `output.value`: Raw input/output as text
- `exception.message`: Error message if failed
