---
id: daily-phoenix-cli
name: "phoenix-cli"
url: https://skills.yangsir.net/skill/daily-phoenix-cli
author: github
domain: ai-system-observability-sre
tags: ["phoenix", "cli", "observability", "llm", "tracing"]
install_count: 1000
rating: 4.30 (16 reviews)
github: https://github.com/github/awesome-copilot
---

# phoenix-cli

> Arize Phoenix 命令行工具，用于查询 traces、spans、datasets 等 LLM 可观测性数据

**Stats**: 1,000 installs · 4.3/5 (16 reviews)

## Before / After 对比

### 快速定位LLM错误痕迹

**Before**:

当LLM应用出现问题时，开发人员需登录Arize Phoenix Web界面，手动导航至痕迹/跨度视图。需逐个应用时间、LLM类型、错误状态等过滤器，涉及多次点击、页面加载等待。在海量数据中定位特定问题痕迹耗时且易错，尤其在需深入分析时效率低下。

**After**:

借助 `phoenix-cli`，开发人员可在终端执行一行命令，如 `px trace list --last-n-minutes 60 --format raw | jq '.[] | select(.status == "ERROR")'`。这能立即查询最近一小时内所有错误LLM痕迹，并以JSON格式输出，方便通过 `jq` 快速筛选和分析。极大简化故障排查，减少上下文切换和手动操作。

| Metric | Before | After | Change |
|---|---|---|---|
| 定位问题痕迹所需时间 | 300秒 | 15秒 | -95% |
| 手动操作步骤数 | 8步骤 | 1步骤 | -87.5% |

### 自动化LLM可观测数据分析

**Before**:

若需将LLM可观测数据集成到自动化脚本、CI/CD或自定义监控系统，开发人员必须直接调用Arize Phoenix API。这要求编写自定义代码处理HTTP请求、认证、JSON解析及错误处理，增加了开发复杂性和集成时间。每次数据需求变更，都需修改或重写API调用逻辑。

**After**:

 `phoenix-cli` 提供标准化命令行接口，可轻松集成到Shell脚本或自动化流程。结合 `px <resource> <action> --format raw | jq .`，可方便获取结构化JSON数据，并利用 `jq` 进行强大过滤、转换和分析。这消除了编写底层API客户端代码的需要，显著加速自动化数据管道构建，提高开发效率。

| Metric | Before | After | Change |
|---|---|---|---|
| 集成脚本开发时间 | 240分钟 | 30分钟 | -87.5% |
| 数据处理代码行数 | 80行代码 | 10行代码 | -87.5% |

## Readme

# phoenix-cli

# Phoenix CLI

## Invocation

```
px <resource> <action>                          # if installed globally
npx @arizeai/phoenix-cli <resource> <action>    # no install required

```

The CLI uses singular resource commands with subcommands like `list` and `get`:

```
px trace list
px trace get <trace-id>
px span list
px dataset list
px dataset get <name>

```

## Setup

```
export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # if auth is enabled

```

Always use `--format raw --no-progress` when piping to `jq`.

## Traces

```
px trace list --limit 20 --format raw --no-progress | jq .
px trace list --last-n-minutes 60 --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
px trace list --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
px trace get <trace-id> --format raw | jq .
px trace get <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'

```

## Spans

```
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 --name chat_completion --limit 10             # filter by span name
px span list --trace-id <id> --format raw --no-progress | jq .   # all spans for a trace
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 '.[] | select(.status_code == "ERROR")'

```

### Span JSON shape

```
Span
  name, span_kind ("LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"UNKNOWN")
  status_code ("OK"|"ERROR"|"UNSET"), status_message
  context.span_id, context.trace_id, parent_id
  start_time, end_time
  attributes (same as trace span attributes above)
  annotations[] (with --include-annotations)
    name, result { score, label, explanation }

```

### Trace JSON shape

```
Trace
  traceId, status ("OK"|"ERROR"), duration (ms), startTime, endTime
  rootSpan  — top-level span (parent_id: null)
  spans[]
    name, span_kind ("LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT")
    status_code ("OK"|"ERROR"), parent_id, context.span_id
    attributes
      input.value, output.value          — raw input/output
      llm.model_name, llm.provider
      llm.token_count.prompt/completion/total
      llm.token_count.prompt_details.cache_read
      llm.token_count.completion_details.reasoning
      llm.input_messages.{N}.message.role/content
      llm.output_messages.{N}.message.role/content
      llm.invocation_parameters          — JSON string (temperature, etc.)
      exception.message                  — set if span errored

```

## Sessions

```
px session list --limit 10 --format raw --no-progress | jq .
px session list --order asc --format raw --no-progress | jq '.[].session_id'
px session get <session-id> --format raw | jq .
px session get <session-id> --include-annotations --format raw | jq '.annotations'

```

### Session JSON shape

```
SessionData
  id, session_id, project_id
  start_time, end_time
  traces[]
    id, trace_id, start_time, end_time

SessionAnnotation (with --include-annotations)
  id, name, annotator_kind ("LLM"|"CODE"|"HUMAN"), session_id
  result { label, score, explanation }
  metadata, identifier, source, created_at, updated_at

```

## Datasets / Experiments / Prompts

```
px dataset list --format raw --no-progress | jq '.[].name'
px dataset get <name> --format raw | jq '.examples[] | {input, output: .expected_output}'
px experiment list --dataset <name> --format raw --no-progress | jq '.[] | {id, name, failed_run_count}'
px experiment get <id> --format raw --no-progress | jq '.[] | select(.error != null) | {input, error}'
px prompt list --format raw --no-progress | jq '.[].name'
px prompt get <name> --format text --no-progress   # plain text, ideal for piping to AI

```

## GraphQL

For ad-hoc queries not covered by the commands above. Output is `{"data": {...}}`.

```
px api graphql '{ projectCount datasetCount promptCount evaluatorCount }'
px api graphql '{ projects { edges { node { name traceCount tokenCountTotal } } } }' | jq '.data.projects.edges[].node'
px api graphql '{ datasets { edges { node { name exampleCount experimentCount } } } }' | jq '.data.datasets.edges[].node'
px api graphql '{ evaluators { edges { node { name kind } } } }' | jq '.data.evaluators.edges[].node'

# Introspect any type
px api graphql '{ __type(name: "Project") { fields { name type { name } } } }' | jq '.data.__type.fields[]'

```

Key root fields: `projects`, `datasets`, `prompts`, `evaluators`, `projectCount`, `datasetCount`, `promptCount`, `evaluatorCount`, `viewer`.

## Docs

Download Phoenix documentation markdown for local use by coding agents.

```
px docs fetch                                # fetch default workflow docs to .px/docs
px docs fetch --workflow tracing             # fetch only tracing docs
px docs fetch --workflow tracing --workflow evaluation
px docs fetch --dry-run                      # preview what would be downloaded
px docs fetch --refresh                      # clear .px/docs and re-download
px docs fetch --output-dir ./my-docs         # custom output directory

```

Key options: `--workflow` (repeatable, values: `tracing`, `evaluation`, `datasets`, `prompts`, `integrations`, `sdk`, `self-hosting`, `all`), `--dry-run`, `--refresh`, `--output-dir` (default `.px/docs`), `--workers` (default 10).
Weekly Installs518Repository[github/awesome-copilot](https://github.com/github/awesome-copilot)GitHub Stars29.6KFirst Seen12 days agoSecurity Audits[Gen Agent Trust HubPass](/github/awesome-copilot/phoenix-cli/security/agent-trust-hub)[SocketPass](/github/awesome-copilot/phoenix-cli/security/socket)[SnykWarn](/github/awesome-copilot/phoenix-cli/security/snyk)Installed onopencode475codex473gemini-cli472github-copilot472deepagents469amp469

---
*Source: https://skills.yangsir.net/skill/daily-phoenix-cli*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-phoenix-cli/markdown*