Phoenix CLI

実行方法

px <resource> <action>                          # グローバルにインストール済みの場合
npx @arizeai/phoenix-cli <resource> <action>    # インストール不要

CLIは単数形のリソースコマンドと list、get などのサブコマンドを使用します:

px trace list
px trace get <trace-id>
px trace annotate <trace-id>
px trace add-note <trace-id>
px trace-annotations delete
px span list
px span annotate <span-id>
px span add-note <span-id>
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-annotations delete
px dataset list
px dataset get <name>
px project list
px project get <name>
px annotation-config list
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>

セットアップ

export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # 認証が有効な場合

jq にパイプする際は、常に --format raw --no-progress を使用してください。

クイックリファレンス

タスク	ファイル
サンプリングされたトレース、スパン、またはセッションを確認し、何が問題だったかについて具体的なメモを書く（まだ分類法はない）	references/open-coding
これらのメモをグループ化して構造化された障害の分類法を作成し、重要なものを定量化する	references/axial-coding

両方のステージは、実行をクエリ可能、可逆的、ユニットとして表示可能にするために、1つの共有された コーディング注釈識別子 (説明的な形式、例: coding-run:chatbot-context-loss-2026-05-06) ですべてのアーティファクトにタグを付けます。すべての px 呼び出しで明示的に --identifier <value> を渡してください — シェル継承はエージェントハーネス全体で信頼性がありません。オープンコーディングは px ... add-note 経由でメモを書き、小さなローカル JSONL サイドカーを .px/coding/<sanitized-identifier>.jsonl に記録します。軸コーディングはそのサイドカーを決定論的なハンドオフとして読み込み、ラベルを .px/coding/<sanitized-identifier>-axial.jsonl に記録します。実行ごとに1回識別子を選択してください (references/open-coding.md を参照)、次に総括セクションから Phoenix UI リンクを共有します。リバート はオプトインであり、明示的なユーザー確認後にのみ識別子にバインドされた3つの DELETE を実行します。

ワークフロー用語 vs. サーバー注釈名。 スキルのテキストではこの値を コーディング注釈識別子 (シェル変数ヒント: CODING_ANNOTATION_IDENTIFIER) と呼びます。UI フィルタに使用されるサーバー側の注釈 NAME は、以前の実行で既に書かれた行とのデータ互換性のために coding_session_id のままです。サーバー側の注釈の名前を変更しようとしないでください。この非対称性を負荷を支える設計として扱います。

ワークフロー

「インストルメンテーション後は何をするか」/ 「どこに焦点を当てるか」/ 「何が問題か」 open-coding → axial-coding → トップカテゴリ用にevals を構築。

リファレンスカテゴリ

プレフィックス	説明
references/open-coding	サンプリングされたトレース、スパン、またはセッションに対する自由形式のメモ — ユーザーが LLM トラフィックを理解したいが失敗カテゴリがまだない場合に活用します。ワークフローが実際に失敗モードが存在するレベルで実行されるように分析単位の診断が含まれています (ステートレスな単一ショット呼び出しの場合はトレース、マルチターンエージェントの場合はセッション、機械的/独立した失敗の場合はスパン)。
references/axial-coding	メモを MECE 分類法にグループ化し、カウントを追加 — ユーザーが観察を持っていてカテゴリまたはevals ターゲットが必要な場合に活用します

認証

px auth status                                # 接続と認証をチェック
px auth status --endpoint http://other:6006   # 特定のエンドポイントをチェック
px auth status --profile staging              # 指定されたプロファイルの接続をチェック

プロファイル

名前付きプロファイルにより、複数の Phoenix インスタンス (ローカル、ステージング、クラウド) 間で環境変数をいじることなく切り替えられます。プロファイルは ~/.px/settings.json (または $XDG_CONFIG_HOME/px/settings.json) に保存されます。

設定優先度 (高から低): CLI フラグ > 環境変数 > アクティブなプロファイル > 組み込みデフォルト。

px profile list                              # すべてのプロファイルを一覧表示 (アクティブなプロファイルを表示)
px profile show                              # アクティブなプロファイルの設定を表示
px profile show staging                      # 指定されたプロファイルの設定を表示
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                          # アクティブなプロファイルを切り替え
px profile edit prod                         # プロファイル JSON を $EDITOR で開く (保存時に検証)
px profile delete prod --yes                 # プロファイルを削除 (--yes で確認をスキップ)

アクティブなプロファイルを変更せずに、任意のコマンドで --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                                            # すべてのプロジェクトを一覧表示 (テーブルビュー)
px project list --format raw --no-progress | jq '.[].name' # プロジェクト名を JSON で取得
px project get my-project --format raw --no-progress       # 正確な名前で単一レコードを取得
px project get my-project --format raw --no-progress | jq -r '.id'  # プロジェクト ID を抽出

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 --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>"  # コーディング注釈識別子でタグ付け
px trace add-note <trace-id> --text "needs follow-up"
px trace add-note <trace-id> --text "needs follow-up" --identifier "<coding-annotation-id>"  # タグ付けと識別子でのアップサート
px trace-annotations delete --identifier "<coding-annotation-id>" --all -y            # このコーディング注釈識別子に関連するすべての注釈を削除

px <entity>-annotations delete は --all か --start-time と --end-time の両方を必須とし、成功時に {deleted: true, target, filter} を出力します。

トレース JSON の構造

Trace
  traceId, status ("OK"|"ERROR"), duration (ms), startTime, endTime
  annotations[] (--include-annotations 時、note を除外)
    name, result { score, label, explanation }
  notes[] (--include-notes 時)
    name="note", result { explanation }
  rootSpan  — トップレベルスパン (parent_id: null)
  spans[]
    name, span_kind ("LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"UNKNOWN")
    status_code ("OK"|"ERROR"|"UNSET"), parent_id, context.span_id
    notes[] (--include-notes 時)
      name="note", result { explanation }
    attributes
      input.value, output.value          — 生の入出力
      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 文字列 (temperature など)
      exception.message                  — スパンがエラーの場合に設定

スパン

px span list --limit 20                                    # 最近のスパン (テーブルビュー)
px span list --last-n-minutes 60 --limit 50                # 過去1時間のスパン
px span list --since 2025-01-15T00:00:00Z --limit 50       # タイムスタンプ以降のスパン
px span list --span-kind LLM --limit 10                    # LLM スパンのみ
px span list --status-code ERROR --limit 20                # エラーのあるスパンのみ
px span list --name chat_completion --limit 10             # スパン名でフィルタ
px span list --trace-id <id> --format raw --no-progress | jq .   # トレースのすべてのスパン
px span list --parent-id null --limit 10                   # ルートスパンのみ
px span list --parent-id <span-id> --limit 10              # スパンの子スパンのみ
px span list --include-annotations --limit 10              # 注釈スコアを含む
px span list --include-notes --limit 10                    # スパンメモを含む
px span list --attribute llm.model_name:gpt-4 --limit 10  # 文字列属性でフィルタ
px span list --attribute llm.token_count.total:500 --limit 10  # 数値属性でフィルタ
px span list --attribute 'user.id:"12345"' --limit 10     # 数値のような値を強制的に文字列マッチ
px span list --attribute session.id:sess:abc:123 --limit 20  # 値内のコロン OK (最初のコロンで分割)
px span list --attribute llm.model_name:gpt-4 --attribute session.id:abc --limit 10  # 複数フィルタの AND
px span list output.json --limit 100                       # JSON ファイルに保存
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>"  # コーディング注釈識別子でタグ付け
px span add-note <span-id> --text "verified by agent"
px span add-note <span-id> --text "verified by agent" --identifier "<coding-annotation-id>"  # タグ付けと識別子でのアップサート
px span-annotations delete --identifier "<coding-annotation-id>" --all -y           # このコーディング注釈識別子に関連するすべての注釈を削除

スパン JSON の構造

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
    input.value, output.value          — 生の入出力
    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 文字列 (temperature など)
    exception.message                  — スパンがエラーの場合に設定
  annotations[] (--include-annotations 時、note を除外)
    name, result { score, label, explanation }
  notes[] (--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>"  # コーディング注釈識別子でタグ付け
px session add-note <session-id> --text "verified by agent"
px session add-note <session-id> --text "verified by agent" --identifier "<coding-annotation-id>"  # タグ付けと識別子でのアップサート
px session-annotations delete --identifier "<coding-annotation-id>" --all -y              # このコーディング注釈識別子に関連するすべての注釈を削除

セッション JSON の構造

SessionData
  id, session_id, project_id
  start_time, end_time
  token_count_prompt, token_count_completion, token_count_total  — セッション内のすべての LLM スパンにおける累積 (整数、デフォルト 0)
  annotations[] (--include-annotations 時、note を除外)
    name, result { score, label, explanation }
  notes[] (--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 .    # 分割でフィルタ
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   # プレーンテキスト、AI にパイプするのに最適

注釈設定

px annotation-config list                                           # すべての設定を一覧表示 (テーブルビュー)
px annotation-config list --format raw --no-progress | jq '.[].name' # 設定名を 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'

# 任意の型をイントロスペクト
px api graphql '{ __type(name: "Project") { fields { name type { name } } } }' | jq '.data.__type.fields[]'

主要なルートフィールド: projects、datasets、prompts、evaluators、projectCount、datasetCount、promptCount、evaluatorCount、viewer。

ドキュメント

Phoenix ドキュメント Markdown をダウンロードして、コーディングエージェントで使用します。

px docs fetch                                # デフォルトワークフロードキュメントを .px/docs にフェッチ
px docs fetch --workflow tracing             # トレーシングドキュメントのみフェッチ
px docs fetch --workflow tracing --workflow evaluation
px docs fetch --dry-run                      # ダウンロード予定内容をプレビュー
px docs fetch --refresh                      # .px/docs をクリアして再ダウンロード
px docs fetch --output-dir ./my-docs         # カスタム出力ディレクトリ

主要なオプション: --workflow (繰り返し可能、値: tracing、evaluation、datasets、prompts、integrations、sdk、self-hosting、all)、--dry-run、--refresh、--output-dir (デフォルト .px/docs)、--workers (デフォルト 10)。