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-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  # if auth is enabled

jq にパイプで渡す場合は、必ず --format raw --no-progress を使用してください。

クイックリファレンス

タスク	ファイル
サンプリングしたトレース、スパン、またはセッションを確認し、何が問題だったか具体的なメモを記録する（分類体系はまだありません）	references/open-coding
これらのメモを体系的な障害分類体系にまとめ、重要な項目を定量化する	references/axial-coding

どちらの段階でも、すべてのアーティファクトに共通の コーディングアノテーション識別子（説明的な形式。例：coding-run:chatbot-context-loss-2026-05-06）をタグ付けします。これにより、実行をクエリ、取り消しでき、ひとまとまりとして表示できます。すべての px 呼び出しで --identifier <value> を明示的に指定してください。エージェントハーネス間では、シェルの継承が確実ではありません。オープンコーディングでは px ... add-note を使ってメモを書き込み、.px/coding/<sanitized-identifier>.jsonl に小さなローカル JSONL サイドカーを記録します。軸コーディングでは、そのサイドカーを決定論的な引き継ぎデータとして読み取り、ラベルを .px/coding/<sanitized-identifier>-axial.jsonl に記録します。実行ごとに識別子を一度だけ選び（references/open-coding.md を参照）、最後にまとめるセクションから Phoenix UI のリンクを共有してください。取り消しはオプトインであり、ユーザーから明示的な確認を得た後にのみ、識別子に紐づいた DELETE を3回実行します。

ワークフロー用語とサーバー側のアノテーション名について。 スキルの説明では、この値を コーディングアノテーション識別子（シェル変数のヒント：CODING_ANNOTATION_IDENTIFIER）と呼びます。UI フィルターに使うサーバー側のアノテーション NAME は変更されていません。以前の実行で書き込まれた行とのデータ互換性を保つため、coding_session_id のままです。サーバー側のアノテーション名を変更しないでください。この非対称性は重要な前提として扱ってください。

ワークフロー

「計測を組み込んだ後は何をすればよいですか？」／「どこに注力すればよいですか？」／「何がうまくいっていませんか？」 open-coding → axial-coding → 上位カテゴリの評価を作成します。

リファレンスカテゴリ

プレフィックス	説明
references/open-coding	サンプリングしたトレース、スパン、またはセッションに対する自由形式のメモです。LLM トラフィックを把握したいものの、障害カテゴリがまだない場合に使用します。障害モードが実際に存在するレベルでワークフローを実行できるよう、分析単位を診断する機能も含まれます（ステートレスな単発呼び出しではトレース、複数ターンのエージェントではセッション、機械的な単独障害ではスパン）。
references/axial-coding	メモをカウント付きの帰納的な MECE 分類体系にまとめます。ユーザーに観察結果があり、カテゴリや評価対象が必要な場合に使用します。

認証

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

プロファイル

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

設定の優先順位（高い順）：CLI フラグ > 環境変数 > アクティブなプロファイル > 組み込みのデフォルト値。

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 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 get は、名前が一致しない場合に ExitCode.FAILURE（1）で終了し、--format json|raw では StructuredError {error, code: "FAILURE", hint} を stderr に書き込みます。

トレース

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>"  # 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"|"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

スパン

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

スパンの 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          — 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

セッションの 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

アノテーション設定

px annotation-config list                                           # list all configs (table view)
px annotation-config list --format raw --no-progress | jq '.[].name' # config names as 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'

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

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

Docs

コーディングエージェントがローカルで使用できるよう、Phoenix のドキュメントを Markdown 形式でダウンロードします。

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）。