---
title: "judgment traces"
description: "Search, inspect, tag, and re-evaluate traces in a project."
sidebar:
  label: "Traces"
seo:
  title: "judgment traces CLI Reference | Judgment Docs"
  description: "Command reference for `judgment traces`, used to search, inspect, tag, and re-evaluate traces in Judgment CLI workflows."
---

> **Warning**
>
> **The Judgment CLI is deprecated and no longer under active development.**
> This reference is retained for existing users. See the [CLI deprecation
> notice](/documentation/cli) for supported alternatives.


Search, inspect, tag, and re-evaluate traces in a project.

## Commands

| Command | Description |
| ------- | ----------- |
| [`traces add-tags`](#traces-add-tags) | Add tags to a trace. |
| [`traces behaviors`](#traces-behaviors) | List behaviors observed on a trace. |
| [`traces evaluate`](#traces-evaluate) | Re-evaluate traces. |
| [`traces get`](#traces-get) | Get a trace by ID. |
| [`traces search`](#traces-search) | Search traces. |
| [`traces span`](#traces-span) | Get span details. |
| [`traces spans`](#traces-spans) | List a trace’s spans. |
| [`traces tags`](#traces-tags) | List a trace’s tags. |

### `traces add-tags`

Add tags to a trace.

Attach one or more string tags to an existing trace. Tags are additive — existing tags are preserved.

```bash
judgment traces add-tags [OPTIONS] [[[ORG_ID] PROJECT_ID] TRACE_ID...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID] TRACE_ID` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--tags</code> | text | yes | String tags to attach to the trace. Tags are additive — existing tags on the trace are preserved. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces behaviors`

List behaviors observed on a trace.

```bash
judgment traces behaviors [OPTIONS] [[[ORG_ID] PROJECT_ID] TRACE_ID...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID] TRACE_ID` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces evaluate`

Re-evaluate traces.

Queue traces for re-evaluation by the project’s judges. Pass `trace_ids` to re-evaluate specific traces, or `evaluate_all: true` to re-evaluate every trace in the project.

```bash
judgment traces evaluate [OPTIONS] [[[ORG_ID] PROJECT_ID]...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID]` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--evaluate-all</code> | boolean | no | When true, re-evaluate every trace in the project. Mutually exclusive with `trace_ids`. |
| <code style={{whiteSpace:"nowrap"}}>--trace-ids</code> | text | no | Trace UUIDs to re-evaluate. Mutually exclusive with `evaluate_all`. |
| <code style={{whiteSpace:"nowrap"}}>--specific-judge-names</code> | text | no | Restrict evaluation to judges with these names. Omit to run every applicable judge. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces get`

Get a trace by ID.

```bash
judgment traces get [OPTIONS] [[[ORG_ID] PROJECT_ID] TRACE_ID...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID] TRACE_ID` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces search`

Search traces.

Filter, sort, time-bound, and paginate traces in a project. See each body field for the exact JSON shape it expects.

```bash
judgment traces search [OPTIONS] [[[ORG_ID] PROJECT_ID]...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID]` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--filters</code> | text | no | Filter expressions, ANDed together. Each item is `{"field":&lt;field&gt;,"op":&lt;op&gt;,"value":&lt;value&gt;}`. Allowed ops depend on the field's type.  **Op groups:** - `STRING_OPS` = `=` \| `!=` \| `contains` \| `does_not_contain` \| `exists` \| `is_absent` - `NUMERIC_OPS` = `=` \| `!=` \| `&lt;` \| `&lt;=` \| `&gt;` \| `&gt;=` - `ARRAY_ANY` = `any` (matches when the row's array overlaps the supplied values)  **String fields** (op in STRING_OPS, value is a string): `span_name`, `customer_id`, `customer_user_id`, `session_id`, `error`, `dataset_id`.  **Numeric fields** (op in NUMERIC_OPS, value is a number): `duration` (nanoseconds), `llm_cost` (USD).  **Array fields** (op = `any`, value is an array): `tags` (strings), `rules_invoked` (rule names from this project, strings), `behaviors` (behavior UUIDs).  **Special:** - `full_text_search`: op = `contains`, value is a string searched across span attribute text. - `span_attributes_roots`: matches a single span attribute key/value: `{"field":"span_attributes_roots","key":"&lt;attribute-name&gt;","op":&lt;STRING_OPS&gt;,"value":"&lt;string&gt;"}` |
| <code style={{whiteSpace:"nowrap"}}>--sort-by</code> | text | no | `{"field":&lt;sort_field&gt;,"direction":"asc"\|"desc"}` where `sort_field` is one of: `created_at`, `span_name`, `duration`, `llm_cost`. Default when omitted: `{"field":"created_at","direction":"desc"}`. Any sort other than `created_at` desc requires `time_range.start_time` and a window between `start_time` and `end_time` of at most 7 days; use `created_at` desc sorting for broader ranges. |
| <code style={{whiteSpace:"nowrap"}}>--time-range</code> | text | no | `{"start_time":&lt;iso8601-string&gt;\|null,"end_time":&lt;iso8601-string&gt;\|null}`. Either bound may be null to leave that side open. Invalid timestamps return 400. For any sort other than `created_at` desc, `start_time` is required and the window between `start_time` and `end_time` must be at most 7 days. |
| <code style={{whiteSpace:"nowrap"}}>--pagination</code> | text | yes | `{"limit":&lt;int 1-200&gt;,"cursorSortValue":&lt;string&gt;\|null,"cursorItemId":&lt;string&gt;\|null}`.  First page: pass null for both cursor fields. Each response returns `nextCursor:{sort_value,trace_id}` (or null when `hasMore=false`); copy those into `cursorSortValue` and `cursorItemId` for the next page. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `table`, `yaml`, `json` | no | Output format. |


### `traces span`

Get span details.

Fetch full details (inputs/outputs/attributes) for up to 20 specific spans across one or more traces.

```bash
judgment traces span [OPTIONS] [[[ORG_ID] PROJECT_ID]...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID]` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--spans</code> | text | yes | Up to 20 trace/span ID pairs to fetch span details for in a single request. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces spans`

List a trace’s spans.

```bash
judgment traces spans [OPTIONS] [[[ORG_ID] PROJECT_ID] TRACE_ID...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID] TRACE_ID` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |


### `traces tags`

List a trace’s tags.

```bash
judgment traces tags [OPTIONS] [[[ORG_ID] PROJECT_ID] TRACE_ID...]
```

**Arguments**

| Name | Required |
| ---- | -------- |
| `[[ORG_ID] PROJECT_ID] TRACE_ID` | no |

**Options**

| Flag | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| <code style={{whiteSpace:"nowrap"}}>--organization-id</code>, <code style={{whiteSpace:"nowrap"}}>--org-id</code> | text | no | Organization ID. Defaults to JUDGMENT_ORG_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--organization</code>, <code style={{whiteSpace:"nowrap"}}>--org</code> | text | no | Organization name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>--project-id</code> | text | no | Project ID. Defaults to JUDGMENT_PROJECT_ID or saved context. |
| <code style={{whiteSpace:"nowrap"}}>--project</code> | text | no | Project name to resolve. |
| <code style={{whiteSpace:"nowrap"}}>-o</code>, <code style={{whiteSpace:"nowrap"}}>--output</code> | `yaml`, `json` | no | Output format. |