# @arizeai/phoenix-cli 中文文档

规范地址：https://npmcn.com/package/%40arizeai/phoenix-cli/

版本：1\.20\.0
npm 元数据更新时间：2026-11-06T00:49:15.397Z
中文译文更新时间：2026-11-06T19:35:38.326Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arizeai/phoenix-cli
原文对照：https://npmcn.com/package/%40arizeai/phoenix-cli/?lang=original
项目主页：https://github.com/Arize-ai/phoenix/tree/main/js/packages/phoenix-cli
源码仓库：https://github.com/Arize-ai/phoenix

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，464 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：13 个
- 首次发布：2025-07-16T20:48:00.013Z
- 最新版本发布：2026-11-06T00:49:15.068Z
- 近 30 天下载量：3459（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：90（近 12 个月 89 个）

## 中文简介

凤凰城的命令行界面

## 安装

```sh
npm install @arizeai/phoenix-cli
```

也可以使用：`pnpm add @arizeai/phoenix-cli`、`yarn add @arizeai/phoenix-cli`、`bun add @arizeai/phoenix-cli`

## README

# 

[![Arize Phoenix logo](https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg)](https://phoenix.arize.com/?utm_medium=github&utm_content=header_img&utm_campaign=phoenix-cli)  
@arizeai/凤凰-cli

 [![NPM Version](https://img.shields.io/npm/v/%40arizeai%2Fphoenix-cli)](https://www.npmjs.com/package/@arizeai/phoenix-cli)[![Documentation](https://img.shields.io/badge/docs-blue?logo=typescript&logoColor=white) ](https://arize.com/docs/phoenix/)![](https://static.scarf.sh/a.png?x-pxid=8e8e8b34-7900-43fa-a38f-1f070bd48c64&page=js/packages/phoenix-cli/README.md)

用于命令行接口 [阿里兹·凤凰](https://github.com/Arize-ai/phoenix)获取痕迹,检查数据集,查询实验,并直接从您的终端访问提示——或者将它们管道入诸如克洛德码,克勒斯码,克勒斯码和双子座CLI等AI编码代理.

## 安装

```bash
npm install -g @arizeai/phoenix-cli
# or run without installing:
npx @arizeai/phoenix-cli

# once installed globally, update in place:
px self update
```

## 配置

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

CLI 旗帜(`--endpoint`, (中文(简体) ), `--project`, (中文(简体) ), `--api-key`) 覆盖环境变量。 供当地互动使用, `px auth login` 将 OAuth 会话存储在您当前配置文件中; 会话得到登录用户的允许。 API 密钥在配置时优先 .

| 变量 | 说明 |
| --- | --- |
| `PHOENIX_ENDPOINT` | 凤凰基地 URL( 动画) |
| `PHOENIX_COLLECTOR_ENDPOINT` | 跟踪- 导出基址,通常与 `PHOENIX_ENDPOINT`· ; `px` 未设置时使用 |
| `PHOENIX_HOST` | 基准 URL 的后退 |
| `PHOENIX_PROJECT` | 项目名称或ID(名称) |
| `PHOENIX_PROJECT_NAME` | 项目名称或ID(上面的别名) |
| `PHOENIX_API_KEY` | API 密钥( 如果启用了认证) |
| `PHOENIX_CLIENT_HEADERS` | 自定义标题为 JSON 字符串 |
| `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES` | 设定为时启用 CLI 删除命令 `true` |

删除命令默认已禁用并需要 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true`。 。 。 .

CLI 也发现最近的 `.env.phoenix` 当前或以上的文件 工作目录。 配置优先级为: CLI 旗,进程环境, 活动简介, `.env.phoenix`,然后内置默认值。 全权证书问题已解决 作为一组,所以一个进程 API 密钥永远不会与文件提供的客户端结合 头. 如果高优先级证书与来自 文档中, CLI 警告一次并继续。 设定 `PHOENIX_DISCOVER_CONFIG=false` 以禁用发现.

## 简介

配置文件为凤凰城实例保存端点、工程、 API 密钥和标题, 名称如下: `prod` 或者说 `staging`。激活一个配置和每个 `px` 命令在不重新导出环境变量的情况下取取这些设置。 环境变量和CLI旗仍然会覆盖活性剖面,因此已存在的脚本继续工作.

```bash
px profile create prod --endpoint https://phoenix.example.com --project main \
                       --api-key sk-xxx --activate
px profile list                # all profiles, kubectl-style "current" column
px profile show                # the active profile (or pass <name>)
px profile use prod            # switch the active profile
px profile edit prod           # open in $EDITOR, validates on save
px profile delete prod         # remove a profile (--yes to skip prompt)
```

过 `--profile <name>` 改为 `auth login`, (中文(简体) ), `auth logout`,或 `auth status` 将单一援引的范围扩大到一个非现行概况.

### 通过编辑器自动补全 `$schema`

CLI写道: `$schema` 字段首次创建时自动  `settings.json`因此,像 VS 代码和JetBrains 等编辑验证和 自动完成框外的文件 :

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

如果用手取出线条,则CLI不会添加回. 计划 生活状况 `schemas/phoenix-cli-settings.json` 在凤凰城仓库 并跟踪出版的Zod计划。 该指针目前被固定在 `main`一旦注册,我们将切换到SchemaStore条目.

用于 VS 全项目协会代码 `.vscode/settings.json`数字 :

```json
{
  "json.schemas": [
    {
      "fileMatch": ["settings.json"],
      "url": "https://raw.githubusercontent.com/Arize-ai/phoenix/main/schemas/phoenix-cli-settings.json"
    }
  ]
}
```

## 图标

### `pxi`

打开 **临十一** (Phoenix Intelligence),与凤凰网互动终端聊天 探员 它连接到运行中的 Phoenix 实例, 是相同的服务器侧代理 赋予浏览器助手权力 —— 调查失败的痕迹, 显示 提示,把凤凰城从终点站开走.

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

`pxi` 需要版本上的凤凰服务器 **20.0.0或更新**它检查服务器 版本在启动和退出时带有针对旧服务器的升级消息.

在聊天中,斜线命令(`/help`, (中文(简体) ), `/clear`, (中文(简体) ), `/new`, (中文(简体) ), `/temporary`, (中文(简体) ), `/sessions`, (中文(简体) ), `/model`, (中文(简体) ), `/compact`, (中文(简体) ), `/exit`)由当地处理。 见 [PXI文件](https://arize.com/docs/phoenix/pxi) 为全旗和 斜线命令参考、模型设置和隐私控制.

* * *

### `px setup`

把你的应用带去凤凰城 从应用程序根运行 :

```bash
px setup                                          # interactive
px setup --endpoint https://phoenix.example.com   # skip the endpoint prompt
npx -y @arizeai/phoenix-cli setup                 # try without installing
```

设置保存连接到 gitignored `.env.phoenix`,然后可选择 手动编码代理( Claude Code, Codex, Cursor, OpenCode) 仪器 任务和等待真实的跟踪出现。 之后它可以指点 `px` 地点 新建工程并安装凤凰城技能,以便代理商可以查询您捕获到的.

它提供连接凤凰Docs MCP服务器和代理商的方式 进行交接——通过经纪人拥有的CLI(`claude mcp add`),否则其每个项目的配置文件(`.cursor/mcp.json`, (中文(简体) ), `opencode.json`) (中文(简体) ). 接受这个提议就跳过了 `.px/docs` 完全下载——代理搜索 反之,文件是按要求提供的,它更快地设置,更便宜的代币. 任何失败都会被退回下载. 过 `--docs-mcp` 接受这个提议 没有被询问, `--no-docs-mcp` 永远不要问.

对于CI或特工,通过标记而不是回答提示:

```bash
# 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

# Same, but connect the docs MCP instead of downloading the docs
px setup --no-input --instrument --agent claude --yolo --docs-mcp --format raw
```

只有找到线索 才能成功 代理商自己声称它完成了不算. 每个输出都这么说,所以 退出代码 :

| 退出 | 含义 |
| --- | --- |
| `0` | 已验证,只登记,或者您选择“ 稍后验证” |
| `1` | 意外错误 |
| `2` | 已取消 |
| `3` | 缺少或无效的旗帜( 错误打印出正确的引用) |
| `4` | 未经认证,或证书未经批准 |
| `5` | 无法到达凤凰城终点 |
| `6` | 等待时间已过,没有找到任何线索——没有证实追查工作有效 |

等不及了,就等着吧 `6`。不注册 `--instrument`,以及 回答“ 完成设置—— 我稍后核实” `0` 这样啊 `px setup && npm run dev` 财务报告和审定财务报表 `set -e` 脚本继续工作 故意推迟.

单位 `--format json|raw`, (中文(简体) ), `verification` 实值 `verified`, (中文(简体) ), `notVerified`,或 `deferred`并且当没有可核实时缺席; `tracesVerified` 实值 布尔快手 `verification == "verified"`。 。 。 . `--format pretty` 打印 a `traces:` 线条。 不要在交接员自己的出口上得分 代码 – 它可能正确编辑应用程序, 然后退出很糟, 或者干净地退出 却一无所获.

后用:

```bash
px setup instrument --agent codex   # instrument and verify again
px setup skills                     # install coding-agent skills only
```

#### `px setup mcp`

登记凤凰城 **远程 MCP 服务器** (单位:千美元)`<endpoint>/mcp`有编码 代理, 这样代理可以搜索、 查询和操作您的凤凰数据 。 这个 结束点推断自 `--endpoint`,活动剖面,或 `PHOENIX_ENDPOINT` —— 说 你永远不要重打它.

```bash
px setup mcp                        # pick scope (global default) + agent, interactively
px setup mcp --agent codex          # configure one agent
px setup mcp --agent claude --local # write this repo's config (.mcp.json)
```

支助代理人: `claude`, (中文(简体) ), `codex`, (中文(简体) ), `gemini`, (中文(简体) ), `cursor`, (中文(简体) ), `opencode`, (中文(简体) ), `vscode`。 。 。 . 如果代理人运送 `mcp add` (Claude、Codex、双子座、VS码全球) CLI 驱动它; 其余的则在他们的配置文件中获得合并( C)`~/.cursor/mcp.json`, (中文(简体) ), `~/.config/opencode/opencode.json`, (中文(简体) ), `.vscode/mcp.json`) (中文(简体) ). 范围是 `--global` (全用户,默认值)或 `--local` (这个 repo — Codex 是全局的).

Auth 默认为 **奥奥特**: 配置是仅限 URL , 代理打开 Phoenix 的 浏览器登录在第一次使用时 。 对于无头客户端,请通过 API 键无头头 与 `--header` (可重复):

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

* * *

### `px self update`

检查 npm 登记册以获取最新的 CLI 发布并更新已安装 当有更新版本时,全球CLI到位.

```bash
px self update          # show current/latest and update if needed
px self update --check  # show current/latest without installing
```

全局支持自动更新 `npm`, (中文(简体) ), `pnpm`, (中文(简体) ), `bun`标准 `deno install -g` 包装器安装.

### `px trace list [directory]`

从配置的工程中获取最近的痕迹 。 所有输出都是JSON.

```bash
px trace list --limit 10                          # stdout (pretty)
px trace list --format raw --no-progress | jq    # pipe-friendly compact JSON
px trace list ./my-traces --limit 50             # save as JSON files to directory
px trace list --last-n-minutes 60 --limit 20     # filter by time window
px trace list --since 2026-01-13T10:00:00Z       # since ISO timestamp
px trace list --since 2026-01-13T10:00:00Z --until 2026-01-14T10:00:00Z # time range
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `[directory]` | 将追踪保存为 JSON 文件到目录 | 静态 |
| `-n, --limit <number>` | 痕迹数量( 最新第一) | 10个 |
| `--last-n-minutes <number>` | 只有最后N分钟的痕迹 | —— 说 |
| `--since <timestamp>` | ISO 时间戳后追踪 | —— 说 |
| `--until <timestamp>` | 追踪在ISO 时间戳之前开始的周期( 专属) | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |
| `--include-annotations` | 包含跟踪和跨度说明 | —— 说 |
| `--include-notes` | 包含跟踪和间距注释 | —— 说 |

```bash
# Find ERROR traces
px trace list --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

# Sort by duration, take top 5 slowest
px trace list --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'

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

* * *

### `px trace get <trace-id>`

凭身份证找到一个线索.

```bash
px trace get abc123def456
px trace get abc123def456 --format raw | jq '.spans[] | select(.status_code != "OK")'
px trace get abc123def456 --file trace.json
px trace get abc123def456 --include-notes --format raw | jq '{traceNotes: .notes, spanNotes: [.spans[].notes]}'
```

* * *

### `px trace annotate <trace-id>`

由 OpenTeleometry 痕量ID 创建或更新人类痕量注释.

```bash
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 <trace-id>`

由 OpenTeleometry track ID 添加一个音符到追踪.

```bash
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`

删除已配置项目的微量说明 。 要求数 `--all` (删除每行匹配) **或者说** 两者 `--start-time` 财务报告和审定财务报表 `--end-time` 将删除绑入 a `[start_time, end_time)` 窗口 - `--name`, (中文(简体) ), `--identifier`,以及 `--annotator-kind` 正在缩小过滤器, 并且从未自行授权请求 。 删除默认已禁用; 设置 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true` 先说.

```bash
px trace-annotations delete --identifier "$PHOENIX_CODING_IDENTIFIER" --all -y
px trace-annotations delete --identifier "$PHOENIX_CODING_IDENTIFIER" --all -y --format raw --no-progress
px trace-annotations delete --start-time 2026-01-01T00:00:00Z --end-time 2026-01-02T00:00:00Z -y
```

产出(json/raw): `{ deleted: true, target: "trace", filter: { identifier?, name?, annotator_kind?, start_time?, end_time?, all? } }`。 。 。 .

* * *

### `px span list [file]`

以过滤选项获取配置项目的跨度 。 输出是JSON.

```bash
px span list --limit 50                                    # stdout (pretty)
px span list --span-kind LLM --limit 20                    # only LLM spans
px span list --status-code ERROR --format raw --no-progress # pipe-friendly error spans
px span list --name chat_completion --trace-id abc123       # filter by name and trace
px span list --span-id abc123 def456                        # fetch specific spans by ID
px span list --parent-id null                               # root spans only
px span list spans.json --limit 100 --include-annotations   # save to file with annotations
px span list --last-n-minutes 30 --span-kind TOOL RETRIEVER # multiple span kinds
px span list --since 2026-07-01T00:00:00Z --until 2026-07-02T00:00:00Z # time range
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `[file]` | 将跨度保存为 JSON 文件 | 静态 |
| `-n, --limit <number>` | 最大跨度( 最新第一个) | `100` |
| `--last-n-minutes <number>` | 从最后N分钟开始 | —— 说 |
| `--since <timestamp>` | 自ISO 时间戳以来的垃圾桶 | —— 说 |
| `--until <timestamp>` | Spans 开始于 ISO 时间戳( 专属) | —— 说 |
| `--span-kind <kinds...>` | 按跨度类型过滤( E)`LLM`, (中文(简体) ), `CHAIN`, (中文(简体) ), `TOOL`, (中文(简体) ), `RETRIEVER`, (中文(简体) ), `EMBEDDING`, (中文(简体) ), `AGENT`, (中文(简体) ), `RERANKER`, (中文(简体) ), `GUARDRAIL`, (中文(简体) ), `EVALUATOR`, (中文(简体) ), `DECISION`, (中文(简体) ), `UNKNOWN`(中文(简体) ) | —— 说 |
| `--status-code <codes...>` | 按状态代码过滤( E)`OK`, (中文(简体) ), `ERROR`, (中文(简体) ), `UNSET`(中文(简体) ) | —— 说 |
| `--name <names...>` | 按跨度名称过滤 | —— 说 |
| `--trace-id <ids...>` | 通过微量ID过滤 | —— 说 |
| `--span-id <ids...>` | 由 OpenTeleometry 进行跨 ID 过滤 。 需要凤凰城服务器 19.6.0. | —— 说 |
| `--parent-id <id>` | 按父跨 ID (使用) 过滤 `"null"` 仅用于根跨) | —— 说 |
| `--include-annotations` | 在输出中包含间距说明 | —— 说 |
| `--include-notes` | 在输出中包含间距注释 | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

```bash
# Find all ERROR spans
px span list --status-code ERROR --format raw --no-progress | jq '.[] | {name, status_code}'

# Get LLM spans with token counts
px span list --span-kind LLM --format raw --no-progress | \
  jq '.[] | {name, model: .attributes["llm.model_name"], tokens: (.attributes["llm.token_count.prompt"] + .attributes["llm.token_count.completion"])}'

# Root spans only, sorted by name
px span list --parent-id null --format raw --no-progress | jq 'sort_by(.name)'
```

* * *

### `px span annotate <span-id>`

由 OpenTeleometry 跨 ID 创建或更新一个人类跨度注释 .

```bash
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 <span-id>`

由 OpenTeleometry 跨 ID 添加一个长度的注释 .

```bash
px span add-note 7e2f08cb43bbf521 --text "double-check tool output"
px span add-note 7e2f08cb43bbf521 --text "verified by agent" --format raw --no-progress
```

* * *

### `px span-annotations delete`

删除已配置工程的间距说明 。 与 `px trace-annotations delete` 要求 `--all` 或两者兼有 `--start-time` 财务报告和审定财务报表 `--end-time`。 。 。 .

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

* * *

### `px dataset list`

列出所有数据集.

```bash
px dataset list --format raw --no-progress | jq '.[].name'
```

* * *

### `px dataset get <dataset-identifier>`

从数据集获取示例.

```bash
px dataset get my-dataset --format raw | jq '.examples[].input'
px dataset get my-dataset --split train --split test
px dataset get my-dataset --version <version-id>
px dataset get my-dataset --file dataset.json
```

* * *

### `px experiment list --dataset <name-or-id>`

列出一个数据集的实验.

```bash
px experiment list --dataset my-dataset --format raw --no-progress | \
  jq '.[] | {id, successful_run_count, failed_run_count}'
```

* * *

### `px experiment get <experiment-id>`

获取所有运行数据的单一实验(输入,输出,评价,痕量ID).

```bash
# Find failed runs
px experiment get RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '.[] | select(.error != null) | {input, error}'

# Average latency
px experiment get RXhwZXJpbWVudDox --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'
```

* * *

### `px prompt list`

列出所有提示 .

```bash
px prompt list --format raw --no-progress | jq '.[].name'
```

* * *

### `px prompt-versions list <prompt-identifier>`

按名称或ID列出所有提示版本, 首先是最新版本 。 表格显示每个 版本的ID,描述,模型提供者,模型名称,和创建日期. 创建 日期使用本地日期/ 时间格式化, 与旧日期连接时为空白 服务器。 标记不包含 .

```bash
px prompt-versions list my-evaluator
px prompt-versions list my-evaluator --limit 10 --format json
px prompt-versions list my-evaluator --format raw --no-progress | jq '.[].id'
```

无 `--limit`,获取全部页面。 JSON 和 原始输出包含一组全 版本对象; `created_at` 只在服务器返回时存在. JSON和生出输出保留了原来的时间戳字符串.

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--limit <number>` | 要获取的最大版本数 | 所有版本 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--endpoint <url>` | 凤凰网 API 端点 | 配置的终点 |
| `--api-key <key>` | 凤凰 API 密钥 | 配置了 API 密钥 |
| `--no-progress` | 抑制进度产出 | 已启用进度 |

* * *

### `px prompt get <prompt-identifier>`

快拿来 这个 `text` 格式对 AI 助手来说是理想的.

```bash
px prompt get my-evaluator --format text --no-progress | claude -p "Review this prompt"
px prompt get my-evaluator --tag production --format json | jq '.template'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--tag <name>` | 通过标签获取版本 | —— 说 |
| `--version <id>` | 获取特定版本 | 最新消息 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`, (中文(简体) ), `raw`,或 `text` | `pretty` |

使用 `px prompt-versions list <prompt-identifier>` 以发现版本ID `--version`。 。 。 .

* * *

### `px project list`

列出所有可用的凤凰城项目.

```bash
px project list                                           # pretty output
px project list --format raw --no-progress | jq '.[].name'
px project list --limit 5
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--limit <number>` | 每页最大项目数 | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px project get <name>`

获取一个凤凰城项目的确切名称. 输出是单个记录(不是数组)——JSON和生生模式会放出一个赤色物体. 名称丢失时, 退出 `ExitCode.FAILURE` (1) 写道: `StructuredError` JSON 信封输入 `--format json|raw`。 。 。 .

```bash
px project get my-project
px project get my-project --format raw --no-progress | jq -r '.id'
px project get my-project --format json
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--limit <number>` | 基础搜索的页面大小 | `100` |
| `--no-progress` | 抑制进度产出 | —— 说 |

小写 Stderr( raw) : `{"error":"Project 'foo' not found","code":"FAILURE","hint":"px project list --format raw"}`。 。 。 .

* * *

### `px session list`

列出一个项目的会话.

```bash
px session list                                            # latest 10 sessions
px session list --limit 20 --order asc                     # oldest first
px session list --format raw --no-progress | jq '.[].session_id'
px session list --include-annotations --include-notes --format raw | jq '.[].notes'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `-n, --limit <number>` | 最多会议次数 | `10` |
| `--order <order>` | 排序顺序 : `asc` 或者说 `desc` | `desc` |
| `--include-annotations` | 包括会议说明,不包括说明 | —— 说 |
| `--include-notes` | 在当前时包含会话说明 | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px session get <session-id>`

查看会话的对话流程 .

```bash
px session get my-session-id
px session get my-session-id --file session.json
px session get my-session-id --include-annotations --format raw | jq '.session.annotations'
px session get my-session-id --include-notes --format raw | jq '.session.notes'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--file <path>` | 保存会话到文件而非 stdout | —— 说 |
| `--include-annotations` | 包括会议说明,不包括说明 | —— 说 |
| `--include-notes` | 在当前时包含会话说明 | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px session annotate <session-id>`

通过 GlobalID 或用户提供创建或更新人类会话注释 `session_id`。 。 。 .

```bash
px session annotate my-session-id --name reviewer --label pass
px session annotate my-session-id --name reviewer --score 0.9 --format raw --no-progress
px session annotate my-session-id --name evaluator --label pass --annotator-kind LLM
px session annotate my-session-id --name reviewer --explanation "needs follow-up"
```

* * *

### `px session add-note <session-id>`

GlobalID 或用户提供的会话中添加一个注释 `session_id`。需要凤凰服务器 `14.17.0` 或更新.

```bash
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`

删除配置工程的会话说明 。 与微量/平面等同的授权门——要求 `--all` 或两者兼有 `--start-time` 财务报告和审定财务报表 `--end-time`。 。 。 .

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

* * *

注释配置分为三种类型—— `CATEGORICAL` (一套固定的标签,每个标签都有可选的数字分数), `CONTINUOUS` (数字范围),和 `FREEFORM` (免费文本). 这个 `create`, (中文(简体) ), `get`, (中文(简体) ), `update`,以及 `delete` 命令将完整 CRUD 与 `list`。 。 。 .

#### 指定绝对值

`create` 财务报告和审定财务报表 `update` 接受同样的绝对标签, 所以你只学习一次。 更倾向于可重复的,对外壳友好的旗帜;JSON形式是一种散装/代理替代.

```bash
# Repeatable flag: label with an optional score (label=score, or just label)
--value good=1 --value bad=0 --value needs-review

# JSON payload (handy for agents or large label sets)
--values '[{"label":"good","score":1},{"label":"bad","score":0}]'
```

这两种形式是相互排斥的——通过一种或另一种,而不是两种.

* * *

### `px annotation-config list`

列出您 Phoenix 实例中定义的注释配置 .

```bash
# Show all annotation configs as a table
px annotation-config list

# Extract config names as JSON (agent-friendly)
px annotation-config list --format raw --no-progress | jq -r '.[].name'

# Fetch at most 10 configs
px annotation-config list --limit 10
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px annotation-config get <config-identifier>`

按名称或ID获取单个注释配置 。 配置写入到选中的 stdout `--format` (一个用于 `raw`编号 :`json`) (中文(简体) ).

```bash
# Look up a config by name
px annotation-config get response-quality

# Resolve a config name to its ID (agent-friendly)
px annotation-config get response-quality --format raw --no-progress | jq -r '.id'

# Inspect the labels of a categorical config
px annotation-config get response-quality --format raw --no-progress | jq '.values'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px annotation-config create`

通过 `POST /v1/annotation_configs`。所创建的配置将写入选中的 `--format`。 。 。 .

```bash
# Pass/fail quality rating with scored labels (higher is better)
px annotation-config create --type CATEGORICAL --name response-quality \
  --value good=1 --value bad=0 --optimization-direction MAXIMIZE

# Sentiment labels without scores
px annotation-config create --type CATEGORICAL --name sentiment \
  --value positive --value neutral --value negative

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

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

# Create from a JSON payload and capture the new config ID (agent-friendly)
px annotation-config create --type CATEGORICAL --name response-quality \
  --values '[{"label":"good","score":1},{"label":"bad","score":0}]' \
  --format raw --no-progress | jq -r '.id'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--type <type>` | `CATEGORICAL`, (中文(简体) ), `CONTINUOUS`,或 `FREEFORM` (必须) | —— 说 |
| `--name <name>` | 注释配置名称( 需要) | —— 说 |
| `--description <description>` | 说明 | —— 说 |
| `--optimization-direction <dir>` | `MINIMIZE`, (中文(简体) ), `MAXIMIZE`,或 `NONE` | `NONE` |
| `--value <label[=score]>` | 分类标签(可重复;类别配置) | —— 说 |
| `--values <json>` | 分类值为 JSON( CATEGOR 配置) | —— 说 |
| `--lower-bound <number>` | 下限( 连续/ FREFORM 配置) | —— 说 |
| `--upper-bound <number>` | 上行( 连续/ FREEFORM 配置) | —— 说 |
| `--threshold <number>` | 阈值( FREFORM 配置) | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

`--type` 财务报告和审定财务报表 `--name` 需要;a `CATEGORICAL` 配置还需要至少一个值. `--type` 财务报告和审定财务报表 `--optimization-direction` 属于对案件不敏感。 无效的输入——包括不适用于所选类型的旗帜——退出 `INVALID_ARGUMENT`。 。 。 .

* * *

### `px annotation-config update <config-identifier>`

按名称或ID更新注释配置 。 只有您通过的字段被更改——命令获取已有的配置, 合并您的旗帜, 并将结果通过 `PUT /v1/annotation_configs/{id}`配置 `type` ; 要更改, 删除并重现配置。 更新的配置写入到选中的 stdout `--format`。 。 。 .

```bash
# Change only the description; every other field is preserved
px annotation-config update response-quality --description 'Pass/fail rating from human review'

# Rename a config and set its 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

# Widen the range of a continuous config
px annotation-config update confidence --lower-bound -1 --upper-bound 1

# Update and capture the config ID (agent-friendly)
px annotation-config update response-quality --description 'Updated' --format raw --no-progress | jq -r '.id'
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--name <name>` | 新名称 | —— 说 |
| `--description <description>` | 新说明 | —— 说 |
| `--optimization-direction <dir>` | `MINIMIZE`, (中文(简体) ), `MAXIMIZE`,或 `NONE` | —— 说 |
| `--value <label[=score]>` | 分类标签(可重复;类别配置) | —— 说 |
| `--values <json>` | 分类值为 JSON( CATEGOR 配置) | —— 说 |
| `--lower-bound <number>` | 下限( 连续/ FREFORM 配置) | —— 说 |
| `--upper-bound <number>` | 上行( 连续/ FREEFORM 配置) | —— 说 |
| `--threshold <number>` | 阈值( FREFORM 配置) | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |
| `--no-progress` | 抑制进度产出 | —— 说 |

需要至少一面战地旗. 无效的输入——包括不适用于配置类型(例如. `--value` 连续配置)——与 `INVALID_ARGUMENT`。 。 。 .

* * *

### `px annotation-config delete <config-id>`

用 ID 删除注释配置 。 和所有删除命令一样,除非 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true` 已设定,并提示予以确认,除非 `--yes` 通过.

```bash
# Delete with an interactive confirmation prompt
px annotation-config delete QW5ub3RhdGlvbkNvbmZpZzoxMjM=

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

# Resolve a name to its ID, then delete it
px annotation-config get response-quality --format raw --no-progress | jq -r '.id' | xargs px annotation-config delete --yes
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `-y, --yes` | 跳过确认提示 | —— 说 |
| `--no-progress` | 抑制进度产出 | —— 说 |

* * *

### `px auth login`

登录基于浏览器的 OAuth 流并存储选定配置文件上的符号 。 URL总是被打印为stderr,因此SSH和无头用户可以手动打开. OAuth CLI 会话根据登录用户的许可行事.

CLI 自动刷新 REST、 GraphQL 和 到期访问符 PXI请求. 请求被驳回 `401` 触发一次刷新并重试; 旋转的令牌被坚持到选定的配置文件 .

```bash
px auth login
px auth login --no-browser
px auth login --profile staging --format raw
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--endpoint <url>` | 凤凰网 API 端点 | —— 说 |
| `--api-key <key>` | 凤凰 API 密钥 | —— 说 |
| `--profile <name>` | 保存 OAuth 令牌的配置文件 | 活动 |
| `--no-browser` | 不打开浏览器而打印 URL | —— 说 |
| `--no-input` | 不为粘贴的重定向 URL 提示 | —— 说 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |

### `px auth logout`

从选中的配置中清除 OAuth 令牌 。 登录最优努力取消服务器上的刷新令牌, 并留下任何配置的 API 密钥未被更改 .

```bash
px auth logout
px auth logout --profile staging
px auth logout --format raw
```

### `px auth status`

显示当前 Phoenix 认证状态, 包括配置的端点、 证书来源、 身份, 以及 OAuth 访问级别/ 到期 .

```bash
px auth status
px auth status --endpoint http://localhost:6006
px auth status --profile staging --format raw
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--endpoint <url>` | 凤凰网 API 端点 | —— 说 |
| `--api-key <key>` | 凤凰 API 密钥 | —— 说 |
| `--profile <name>` | 要使用的配置文件 | 活动 |
| `--format <format>` | `pretty`, (中文(简体) ), `json`,或 `raw` | `pretty` |

* * *

### `px api graphql <query>`

根据凤凰城 API 进行认证的 GraphQL 查询 。 输出为 `{"data": {...}}` JSON——烟斗 `jq '.data.<field>'` 以提取值。 只允许查询;突变和订阅被拒绝.

```bash
px api graphql '<query>' [--endpoint <url>] [--api-key <key>]
```

将 HTTP 请求预览为 `curl` 不执行它:

```bash
px api graphql '{ projects { edges { node { name } } } }' --curl
px api graphql '{ projects { edges { node { name } } } }' --curl --show-token
```

`--curl` 在不进行网络呼叫的情况下,打印相应的 Stdout 请求并退出。 默认情况下,包括通过 `PHOENIX_API_KEY` 或者说 `PHOENIX_CLIENT_HEADERS`启用 `--show-token` 只有当您明确需要生成命令中的原始证书时.

目前的范围和行为:

-   `--curl` 目前正在为 `px api graphql` 只有这个.
-   `--curl` 不执行而打印请求.
-   `--show-token` 只对 `--curl`。 。 。 .
-   授权口罩和信头正常化是为了配合用户使用的活请求行为 `fetch`。 。 。 .

使用反演来发现可用的字段 :

```bash
$ px api graphql '{ __schema { queryType { fields { name } } } }' | jq '.data.__schema.queryType.fields[].name'
"projects"
"datasets"
"prompts"
"evaluators"
"projectCount"
"datasetCount"
...

$ 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"}
```

**项目:**

```bash
$ px api graphql '{ projects { edges { node { name traceCount tokenCountTotal } } } }' | \
    jq '.data.projects.edges[].node'
{"name": "default", "traceCount": 1482, "tokenCountTotal": 219083}
```

**数据集 :**

```bash
$ 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}
```

**实验:**

```bash
# List experiments per dataset with error rate and avg latency
$ 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 failures
$ px api graphql '{
  datasets { edges { node { name experiments { edges { node { name errorRate runCount } } } } } }
}' | jq '.. | objects | select(.errorRate? > 0) | {name, errorRate, runCount}'
```

**数一看:**

```bash
$ px api graphql '{ projectCount datasetCount promptCount evaluatorCount }'
{"data": {"projectCount": 1, "datasetCount": 12, "promptCount": 3, "evaluatorCount": 2}}
```

* * *

### `px docs fetch`

下载凤凰文档标记下的文件,供编码代理使用. 从中获取页面 [页:1](https://arize.com/docs/phoenix/llms.txt) 索引,按工作流程类别过滤,并用自动生成的索引文件将其写入本地目录.

```bash
px docs fetch                                # fetch default workflows
px docs fetch --workflow tracing             # fetch only tracing docs
px docs fetch --workflow tracing --workflow evaluation
px docs fetch --dry-run                      # preview without downloading
px docs fetch --refresh                      # clear output dir and re-download
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--workflow <name>` | 按工作流程类别过滤(可重复). 数值 : `tracing`, (中文(简体) ), `evaluation`, (中文(简体) ), `datasets`, (中文(简体) ), `prompts`, (中文(简体) ), `integrations`, (中文(简体) ), `sdk`, (中文(简体) ), `self-hosting`, (中文(简体) ), `all` | `tracing`, (中文(简体) ), `evaluation`, (中文(简体) ), `datasets`, (中文(简体) ), `prompts`, (中文(简体) ), `integrations` |
| `--output-dir <dir>` | 下载文件输出目录 | `.px/docs` |
| `--dry-run` | 只发现链接; 不写入文件 | `false` |
| `--refresh` | 下载前清除输出目录 | `false` |
| `--strict` | 如果任何页面下载失败, 命令失败 | `false` |
| `--workers <n>` | 同时下载的工人人数 | `10` |

* * *

## JSON 输出形状

所有命令输出 JSON. 使用 `--format raw` 用于压缩 JSON 和 `--no-progress` 在管道时压制 stderr :

```bash
px trace list --format raw --no-progress | jq ...
px dataset list --format raw --no-progress | jq ...
```

追踪JSON结构:

```json
{
  "traceId": "abc123def456",
  "status": "OK",
  "duration": 1250,
  "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..."
      }
    }
  ]
}
```

`px api graphql` 输出总是在 `{"data": {...}}`管道 `jq '.data.<field>'` 用来提取.

* * *

## 社区

-   🌍 [黑社会](https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g)
-   📚 [文档](https://arize.com/docs/phoenix)
-   🌟 [GitHub 图像](https://github.com/Arize-ai/phoenix)
-   🐞 [报告错误](https://github.com/Arize-ai/phoenix/issues)
-   页:1 [@ ArizePhoenix (英语)](https://twitter.com/ArizePhoenix)
-   💼 [链接](https://www.linkedin.com/showcase/113218220)

## 常见问题

### @arizeai/phoenix-cli 是什么？

凤凰城的命令行界面

### 如何安装 @arizeai/phoenix-cli？

在项目目录运行 npm install @arizeai/phoenix-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 px、pxi、phoenix-cli，可以用 npx px 直接运行。

### @arizeai/phoenix-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arizeai/phoenix-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arizeai/phoenix-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @arizeai/phoenix-cli 可以商用吗？

@arizeai/phoenix-cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @arizeai/phoenix-cli 的下载量有多少？

根据 npm 官方下载统计，@arizeai/phoenix-cli 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,459 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arizeai/phoenix-cli 还在维护吗？

最新版本 1\.20\.0 发布于 2026/11/06（1 天前）；至今共发布 90 个版本，其中过去 12 个月发布了 89 个；首次发布于 2025/07/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。