phoenix-cli

Phoenix CLI

调用

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

CLI 使用单数资源命令，并通过 list 和 get 等子命令操作：

px trace list
px trace get <trace-id>
px trace annotate <trace-id>
px trace add-note <trace-id>
px trace delete <trace-identifier>
px trace-annotations delete
px span list
px span annotate <span-id>
px span add-note <span-id>
px span delete <span-identifier>
px span-annotations delete
px session list
px session get <session-id>
px session annotate <session-id>
px session add-note <session-id>
px session delete <session-id>
px session-annotations delete
px dataset list
px dataset get <name>
px dataset delete <dataset-identifier>
px experiment list
px experiment get <id>
px experiment delete <experiment-id>
px prompt list
px prompt get <prompt-identifier>
px prompt delete <prompt-identifier>
px project list
px project get <name>
px project delete <project-identifier>
px annotation-config list
px annotation-config get <identifier>
px annotation-config create
px annotation-config update <identifier>
px annotation-config delete <id>
px auth login
px auth logout
px auth status
px profile list
px profile show [name]
px profile create <name>
px profile use <name>
px profile edit <name>
px profile delete <name>
px api graphql <query>
px docs fetch
px setup
px self update

上面每个 delete 命令都有保护机制：必须在环境中设置 PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true，并且除非传入 -y/--yes，否则还会提示确认（px profile delete 仅在本地执行，使用 --yes，无需设置环境变量）。未设置该环境变量时，命令会退出，不会删除任何内容。

设置

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

PHOENIX_ENDPOINT 是用于 API 访问的基础 URL。它通常与 PHOENIX_COLLECTOR_ENDPOINT 的 URL 相同；如果只设置了 collector 变量，CLI 也会用它访问 API。

在本地进行交互式使用时，px auth login 会在所选配置文件中保存 OAuth 会话；该会话具有登录用户的权限。若同时配置了 API 密钥和 OAuth 令牌，则优先使用 API 密钥。 REST、GraphQL 和 PXI 请求会自动刷新 OAuth 访问令牌，轮换后的令牌也会保存到所选配置文件中。

通过管道传递给 jq 时，务必使用 --format raw --no-progress。

px setup — 入门配置

px setup 会将当前目录中的应用连接到 Phoenix 部署，并写入 .env.phoenix（权限模式为 0600，且已加入 gitignore）。交互流程面向用户：它会提示用户、启动编码 Agent，并轮询追踪记录。从 Agent 调用时，务必传入 --no-input：

# Register only: connection + .env.phoenix, no source changes.
px setup --no-input --endpoint http://localhost:6006 --project my-app --format raw

无头模式要求 Git 仓库干净，并且默认在写入文件后停止——除非明确要求，否则不会修改源代码。如果启用了身份验证，还要设置 PHOENIX_API_KEY。项目无需预先存在——Phoenix 会在收到首条追踪记录时创建项目。缺少输入时会以状态码 3 退出，并提供确切的修复方法；取消则以状态码 2 退出。

若要同时为应用添加埋点，请指定执行通道——无头模式没有可供选择的提示，因此 --instrument 必须与 --agent 一起使用：

px setup --no-input --instrument --agent claude --yolo --format raw

--yolo 很重要：后台 Agent 没有终端来批准其修改，因此不传该参数时，运行会停滞，直到追踪验证超时。--language python 会跳过 Agent 的语言检测。--docs-mcp 会将 Phoenix 文档 MCP 服务连接到交接 Agent（claude 使用 claude mcp add；cursor/opencode 使用配置文件合并；codex 不受支持），并跳过 .px/docs 下载——Agent 会改为按需搜索文档；如果失败，则会回退到下载。--no-docs-mcp 会跳过交互式询问。 --format raw 会输出 {"endpoint","project","files","instrumentation","tracesVerified","tracesUrl"} ——请检查 tracesVerified：只有 API 确认收到追踪记录时才会设置该值，而不是 Agent 声称已完成时。

如果等待时间耗尽仍没有追踪记录，运行会以状态码 6 而非 0 退出：配置和修改确实已完成，但尚未确认追踪正常工作。应将其视为失败并报告，而不是成功——也不要用交接 Agent 自己的退出码或摘要来代替判定。未传入 --instrument 进行注册，以及用户在超时提示中选择“稍后验证”，两种情况都会以状态码 0 退出。

仅进行注册的运行中，tracesVerified 也会是 false，因此它本身无法区分“无需验证”和“未收到追踪记录”。需要区分时，请读取 verification（取值为 verified / notVerified / deferred；无需验证时不显示该字段）。

可重复运行的分步流程；已注册的仓库会跳过相关问题：

px setup instrument --agent claude   # instrument + verify only
px setup skills                      # install the Phoenix coding-agent skills

px setup mcp — 注册远程 MCP 服务

将 Phoenix 远程 MCP 服务（<endpoint>/mcp）接入编码 Agent，以便其查询 Phoenix 数据。端点从 --endpoint、当前活动配置或 PHOENIX_ENDPOINT 推断。直接运行命令会先提示选择作用范围（默认全局），再选择 Agent；--agent 可跳过这两项提示。

px setup mcp --agent codex --no-input --format raw
px setup mcp --agent claude --local            # write this repo's .mcp.json

Agent：claude、codex、gemini、cursor、opencode、vscode。作用范围为 --global（默认）或 --local（仓库；Codex 仅支持全局）。默认使用 OAuth（仅 URL 配置，首次使用时通过浏览器登录）；传入 --header "Name: value"（可重复）可改用 API 密钥 Bearer 认证。对于 Codex，Authorization: Bearer ${VAR} 标头会转换为 bearer_token_env_var。--format raw 会输出 {"endpoint","url","serverName","agent","scope","auth","file?"}。

认证

px auth login                                 # browser-based OAuth login
px auth login --no-browser                    # print URL for SSH/headless use
px auth logout                                # clear OAuth tokens; leaves API keys
px auth status                                # check connection and authentication
px auth status --endpoint http://other:6006   # check a specific endpoint
px auth status --profile staging              # check a named profile's connection
px auth status --format raw                   # machine-readable credential source

auth status 会报告凭据来源（flag、env、profile-key、oauth 或 none）。OAuth 状态会包含令牌到期时间。

当存储的凭据来源为 oauth，且经身份验证的探测失败时，auth status 会在不使用凭据的情况下重试一次；只有服务器明确说明访问为匿名时，才会报告匿名访问。这样可以避免在部署已从 OAuth 切换为匿名访问后，仍将过期或失效的配置文件令牌报告为认证失败。

配置文件

命名配置文件可让你在多个 Phoenix 实例（本地、预发布、云端）之间切换，无需频繁调整环境变量。配置文件存储在 ~/.px/settings.json（或 $XDG_CONFIG_HOME/px/settings.json）中。

配置优先级（从高到低）：CLI 标志 > 环境变量 > 当前活动配置文件 > 最近的 .env.phoenix 文件 > 内置默认值。

CLI 还会查找当前工作目录及其上级目录中最近的 .env.phoenix 文件（与 px setup 写入的文件相同）。凭据会作为一个整体解析，因此进程 API 密钥不会与文件中提供的标头混用。设置 PHOENIX_DISCOVER_CONFIG=false 可禁用查找。

px profile list                              # list all profiles (shows active profile)
px profile show                              # show the active profile's settings
px profile show staging                      # show a named profile's settings
px profile create prod --endpoint https://app.phoenix.arize.com --api-key <key> --activate
px profile create local --endpoint http://localhost:6006 --project my-app
px profile use prod                          # switch the active profile
px profile edit prod                         # open profile JSON in $EDITOR (validates on save)
px profile delete prod --yes                 # delete a profile (--yes skips confirmation)

在任何命令中使用 --profile <name>，即可指定配置文件，而不更改当前活动配置文件：

px trace list --profile staging --limit 10 --format raw --no-progress | jq .
px auth status --profile prod

px profile create 选项：--endpoint <url>、--project <name>、--api-key <key>、--header <key=value>（可重复）、--activate。

项目

px project list                                            # list all projects (table view)
px project list --format raw --no-progress | jq '.[].name' # project names as JSON
px project list --name-contains prod                       # filter by name substring (case-insensitive)
px project get my-project --format raw --no-progress       # single record by exact name
px project get my-project --format raw --no-progress | jq -r '.id'  # extract project id

project list 接受 --limit <n>（每页获取的项目数）和 --name-contains <filter>，后者会在服务器端按不区分大小写的名称子串进行筛选。如果只知道项目名称的一部分，请使用此选项，而不要将 list 的结果通过管道传给 grep。

若未找到名称，project get 会以 ExitCode.FAILURE（1）退出，并在 --format json|raw 模式下向 stderr 写入 StructuredError {error, code: "FAILURE", hint}。

追踪

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 --since 2025-01-15T00:00:00Z --limit 50 --format raw --no-progress | jq .
px trace list --since 2025-01-15T00:00:00Z --until 2025-01-16T00:00:00Z --limit 50 --format raw --no-progress | jq .  # time range (until is exclusive)
px trace list --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
px trace list --include-notes --format raw --no-progress | jq '.[].notes'
px trace get <trace-id> --format raw | jq .
px trace get <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'
px trace get <trace-id> --include-notes --format raw | jq '.notes'
px trace annotate <trace-id> --name reviewer --label pass
px trace annotate <trace-id> --name reviewer --score 0.9 --format raw --no-progress
px trace annotate <trace-id> --name reviewer --label pass --identifier "<coding-annotation-id>"  # tag with a coding annotation identifier
px trace add-note <trace-id> --text "needs follow-up"
px trace add-note <trace-id> --text "needs follow-up" --identifier "<coding-annotation-id>"  # tag + upsert on identifier
px trace-annotations delete --identifier "<coding-annotation-id>" --all -y            # nuke every annotation tied to this coding annotation identifier

px <entity>-annotations delete 必须提供 --all，或同时提供 --start-time 和 --end-time；成功时会输出 {deleted: true, target, filter}。

追踪 JSON 结构

Trace
  traceId, status ("OK"|"ERROR"), duration (ms), startTime, endTime
  annotations[] (with --include-annotations, excludes note)
    name, result { score, label, explanation }
  notes[] (with --include-notes)
    name="note", result { explanation }
  rootSpan  — top-level span (parent_id: null)
  spans[]
    name, span_kind ("LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"DECISION"|"UNKNOWN")
    status_code ("OK"|"ERROR"|"UNSET"), parent_id, context.span_id
    notes[] (with --include-notes)
      name="note", result { explanation }
    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

Span

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 --since 2025-01-15T00:00:00Z --limit 50       # spans since a timestamp
px span list --since 2025-01-15T00:00:00Z --until 2025-01-16T00:00:00Z --limit 50  # time range (until is exclusive)
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 --span-id <id> <id> --format raw --no-progress | jq .  # fetch specific spans by ID (server >= 19.6.0)
px span list --parent-id null --limit 10                   # only root spans
px span list --parent-id <span-id> --limit 10              # only children of a span
px span list --include-annotations --limit 10              # include annotation scores
px span list --include-notes --limit 10                    # include span notes
px span list --attribute llm.model_name:gpt-4 --limit 10  # filter by string attribute
px span list --attribute llm.token_count.total:500 --limit 10  # filter by numeric attribute
px span list --attribute 'user.id:"12345"' --limit 10     # force string match for numeric-looking value
px span list --attribute session.id:sess:abc:123 --limit 20  # colon in value OK (split on first colon only)
px span list --attribute llm.model_name:gpt-4 --attribute session.id:abc --limit 10  # AND multiple filters
px span list output.json --limit 100                       # save to JSON file
px span list --format raw --no-progress | jq '.[] | select(.status_code == "ERROR")'
px span annotate <span-id> --name reviewer --label pass
px span annotate <span-id> --name checker --score 1 --annotator-kind CODE
px span annotate <span-id> --name reviewer --label pass --identifier "<coding-annotation-id>"  # tag with a coding annotation identifier
px span add-note <span-id> --text "verified by agent"
px span add-note <span-id> --text "verified by agent" --identifier "<coding-annotation-id>"  # tag + upsert on identifier
px span-annotations delete --identifier "<coding-annotation-id>" --all -y           # nuke every annotation tied to this coding annotation identifier

span list 按写入顺序排序（最新的在前），而不是按 start_time 排序；对于延迟到达的 Span（补录、重放），两者顺序可能不同。若要按 start_time 排序（服务器版本 >= 20.16.0），请调用 REST，并在所有 next_cursor 分页中保持 sort/order 不变：

curl -s -H "Authorization: Bearer $PHOENIX_API_KEY" \
  "$PHOENIX_ENDPOINT/v1/projects/my-project/spans?sort=start_time&order=desc&limit=20"

Span JSON 结构

Span
  name, span_kind ("LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"DECISION"|"UNKNOWN")
  status_code ("OK"|"ERROR"|"UNSET"), status_message
  context.span_id, context.trace_id, parent_id
  start_time, end_time
  attributes
    input.value, output.value          — raw input/output
    llm.model_name, llm.provider
    llm.token_count.prompt/completion/total
    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
  annotations[] (with --include-annotations, excludes note)
    name, result { score, label, explanation }
  notes[] (with --include-notes)
    name="note", result { explanation }

会话

px session list --limit 10 --format raw --no-progress | jq .
px session list --order asc --format raw --no-progress | jq '.[].session_id'
px session list --include-annotations --include-notes --format raw --no-progress | jq '.[].notes'
px session get <session-id> --format raw | jq .
px session get <session-id> --include-annotations --format raw | jq '.session.annotations'
px session get <session-id> --include-notes --format raw | jq '.session.notes'
px session annotate <session-id> --name reviewer --label pass
px session annotate <session-id> --name reviewer --score 0.9 --format raw --no-progress
px session annotate <session-id> --name reviewer --label pass --identifier "<coding-annotation-id>"  # tag with a coding annotation identifier
px session add-note <session-id> --text "verified by agent"
px session add-note <session-id> --text "verified by agent" --identifier "<coding-annotation-id>"  # tag + upsert on identifier
px session-annotations delete --identifier "<coding-annotation-id>" --all -y              # nuke every annotation tied to this coding annotation identifier
px session delete <session-id> -y                                                        # requires PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true

session list 没有筛选标志。若要按会话特征进行筛选——错误数、令牌总数、工具使用情况、标注标签——请通过 GraphQL 使用会话筛选表达式语言（参见会话筛选表达式）。

会话 JSON 结构

SessionData
  id, session_id, project_id
  start_time, end_time
  token_count_prompt, token_count_completion, token_count_total  — cumulative across all LLM spans in the session (int, default 0)
  annotations[] (with --include-annotations, excludes note)
    name, result { score, label, explanation }
  notes[] (with --include-notes)
    name="note", result { explanation }
  traces[]
    id, trace_id, start_time, end_time

数据集 / 实验 / 提示词

px dataset list --format raw --no-progress | jq '.[].name'
px dataset get <name> --format raw | jq '.examples[] | {input, output: .expected_output}'
px dataset get <name> --split train --format raw | jq .    # filter by split
px dataset get <name> --version <version-id> --format raw | jq .
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

标注配置

完整的 CRUD 操作：list、get、create、update、delete。类型包括 CATEGORICAL（标签 + 可选分数）、CONTINUOUS（数值范围）、FREEFORM（自由文本）。

px annotation-config list                                                # all configs (table view)
px annotation-config list --format raw --no-progress | jq -r '.[].name' # config names as JSON
px annotation-config get response-quality --format raw --no-progress     # one config by name or ID

# create — categorical (scored labels), continuous (numeric range), or freeform (free text)
px annotation-config create --type CATEGORICAL --name response-quality --value good=1 --value bad=0
px annotation-config create --type CONTINUOUS --name confidence --lower-bound 0 --upper-bound 1
px annotation-config create --type FREEFORM --name reviewer-notes --description 'Free-form reviewer feedback'

# update by name or ID — only the fields you pass change; type is immutable
px annotation-config update response-quality --name answer-quality --optimization-direction MAXIMIZE
px annotation-config update response-quality --value good=1 --value acceptable=0.5 --value bad=0
px annotation-config update response-quality --description "Updated" --format raw --no-progress | jq -r '.id'

# delete by ID — requires PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true; --yes skips the prompt
px annotation-config delete QW5ub3RhdGlvbkNvbmZpZzoxMjM= --yes

在 create 和 update 中，分类值的指定方式相同：重复使用 --value label[=score]（分数可选），或使用单个 --values '<json>' 载荷；两者互斥。update 会获取现有配置，合并你的标志，然后通过 PUT /v1/annotation_configs/{id} 写回完整请求体；它至少需要一个字段标志。其他特定于类型的标志：--lower-bound/--upper-bound（CONTINUOUS/FREEFORM）、--threshold（FREEFORM）。输入无效（标志错误、类型不匹配、值格式错误）时，会以 {error, code, hint?} JSON 封装格式向 stderr 输出，并以 3（INVALID_ARGUMENT）退出，适用于 raw/json 模式。get/create/update 输出配置对象（在 raw/json 模式下为单个对象，而非数组）。

GraphQL

用于执行上述命令未涵盖的临时查询。输出为 {"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'
# evaluator kind values: "LLM" | "CODE" | "BUILTIN"
# CODE = server-side code evaluator running in a sandbox; BUILTIN = pre-built server evaluator

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

主要根字段：projects、getProjectByName(name:)、datasets、prompts、evaluators、projectCount、datasetCount、promptCount、evaluatorCount、viewer。

getProjectByName(name:) 针对单个项目；projects(first: 1) 会选取一个 任意项目。没有 traces 连接：要列出 trace，请使用 filterCondition: "parent_span is None" 查询 spans，这会保留根 span，与 UI 的 trace 表行为一致。请参阅下文的筛选表达式。

筛选表达式

spans、sessions 和项目聚合项接受筛选条件：在服务端编译的 Python 布尔表达式。共有三种语言，参数决定使用哪种语言。编写条件前请阅读 references/filter-expressions.md，其中包含每种语言的完整词汇表、运算符和编译示例。

参数	匹配对象	名称来源
filterCondition	单个 span	参考文档中的完整表格
traceFilterCondition	整个 trace	traceFilterVocabulary
sessionFilterCondition	session	sessionFilterVocabulary

根 span。 没有 traces 连接，也没有根 span 参数。 filterCondition: "parent_span is None" 会保留根 span，包括其父级从未收到的孤立 span；UI 的 trace 表也使用此条件； parent_id is None 只保留没有父 ID 的 span。每个 trace 通常有一个根 span，且这两个条件都可以与其他筛选条件组合：

px api graphql '{
  getProjectByName(name: "default") { spans(
    first: 20
    filterCondition: "parent_id is None and status_code == \"ERROR\""
    sort: { col: startTime, dir: desc }
  ) { edges { node { spanId name latencyMs } } } }
}' | jq '.data.getProjectByName.spans.edges[].node'

标注。 访问器决定匹配的层级，层级错误时不会匹配任何内容：

访问器	匹配的标注	写入命令
annotations["name"]	span 本身	px span annotate、px span add-note
trace_annotations["name"]	span 的父 trace	px trace annotate、px trace add-note
session_annotations["name"]	session（仅限 session 筛选）	px session annotate、px session add-note

px api graphql '{
  getProjectByName(name: "default") { spans(
    first: 20
    filterCondition: "parent_id is None and trace_annotations[\"quality\"].label == \"poor\""
  ) { edges { node { spanId name } } } }
}' | jq '.data.getProjectByName.spans.edges[].node'

Trace。 traceFilterCondition 会保留匹配 trace 的 span，并可与 filterCondition 组合：

px api graphql '{
  getProjectByName(name: "default") { spans(
    first: 20
    filterCondition: "parent_id is None"
    traceFilterCondition: "error_count > 0 and latency_ms > 1000"
  ) { edges { node { spanId name latencyMs } } } }
}' | jq '.data.getProjectByName.spans.edges[].node'

Session。 px session list 没有筛选标志，因此要根据特征选择 session，需使用 GraphQL：

px api graphql '{
  projects(first: 1) { edges { node { sessions(
    first: 10
    sessionFilterCondition: "num_traces > 5 and any(span.status_code == \"ERROR\" for span in spans)"
  ) { edges { node { sessionId numTraces numTracesWithError } } } } } }
}' | jq '.data.projects.edges[0].node.sessions.edges[].node'

发现名称并验证。 词汇表由编译器自身的绑定生成，因此始终与可编译内容一致：

px api graphql '{ projects(first: 1) { edges { node { traceFilterVocabulary {
  name type category description iterableName } } } } }' \
  | jq '.data.projects.edges[0].node.traceFilterVocabulary[] | {name, type, category}'

px api graphql '{ projects(first: 1) { edges { node {
  validateSpanFilterCondition(condition: "parent_id is None") { isValid errorMessage }
  validateTraceFilterCondition(condition: "error_count > 0") { isValid errorMessage }
  validateSessionFilterCondition(condition: "num_traces > 5") { isValid errorMessage }
} } } }'

对于同时接受两个层级的字段（例如 Project.recordCount）， sessionFilterCondition 和 filterCondition 互斥。

文档

下载 Phoenix 文档 Markdown，供编码 Agent 在本地使用。

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

主要选项：--workflow（可重复，取值：tracing、evaluation、datasets、prompts、integrations、sdk、self-hosting、all）、--dry-run、--refresh、--output-dir（默认值 .px/docs）、--workers（默认值 10）。