> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 04.14.2026 CLI Annotation Commands

> Write span and trace annotations from the terminal with px span annotate and px trace annotate.

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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
# 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
```

<CardGroup cols={2}>
  <Card icon="terminal" href="/docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-cli">
    TypeScript SDK and CLI reference.
  </Card>
</CardGroup>