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:

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 annotationspx trace get <trace-id> --include-annotations# List spans with their annotationspx span list --include-annotations