Skip to main content
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:
FlagDescription
--nameAnnotation name (e.g. correctness, quality)
--labelCategorical label (e.g. correct, incorrect)
--scoreNumeric score
--explanationFree-text explanation
--annotator-kindHUMAN, LLM, or CODE
--formatOutput 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.