04.14.2026 CLI Annotation Commands

Available in @arizeai/phoenix-cli 1.0.4+ The Phoenix CLI now supports writing annotations to spans and traces. Use px span annotate and px trace annotate to attach labels, scores, and explanations directly from the terminal — useful for labeling traces in CI pipelines, scripting evaluation workflows, or quick manual review.

Annotate a Span

px span annotate <span-id> \
  --name correctness \
  --label correct \
  --score 1 \
  --explanation "The response accurately answers the user's question." \
  --annotator-kind HUMAN

Annotate a Trace

px trace annotate <trace-id> \
  --name quality \
  --label good \
  --score 0.9 \
  --annotator-kind CODE

Both commands accept:

Flag	Description
`--name`	Annotation name (e.g. `correctness`, `quality`)
`--label`	Categorical label (e.g. `correct`, `incorrect`)
`--score`	Numeric score
`--explanation`	Free-text explanation
`--annotator-kind`	`HUMAN`, `LLM`, or `CODE`
`--format`	Output format: `pretty`, `json`, or `raw`

At least one of --label or --score is required. Submitting again with the same --name updates the existing entry rather than creating a duplicate.

View Annotations in Output

Pass --include-annotations when reading traces or spans to see existing annotations alongside the data:

# Fetch a trace with trace-level and span-level annotations
px trace get <trace-id> --include-annotations

# List spans with their annotations
px span list --include-annotations

TypeScript SDK and CLI reference.

04.16.2026 Azure Managed Identity for PostgreSQL 04.13.2026 @arizeai/phoenix-otel 1.0

⌘I

​Annotate a Span

​Annotate a Trace

​View Annotations in Output

Annotate a Span

Annotate a Trace

View Annotations in Output