> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> Save, merge, and read multi-run comparison reports with the Coval CLI

Reports are saved comparisons across one or more runs. A report can group its runs by a dimension (agent, persona, test case, mutation, or a metadata key) and can be pinned to a subset of simulations, for example the ones reviewed in a Human Review project.

`create` and `update` also accept `--input-json` (inline JSON, `@file`, or `-` for stdin); explicit flags override fields from the JSON. See [Input JSON](/cli/agent-mode#input-json).

## List Reports

```bash theme={null}
coval reports list [OPTIONS]
```

| Option     | Type   | Default | Description                                            |
| ---------- | ------ | ------- | ------------------------------------------------------ |
| `--limit`  | number | 50      | Results per page (1-100)                               |
| `--cursor` | string | —       | Opaque cursor from a previous response's `next_cursor` |

**Output columns:** ID, NAME, COMPARE BY, RUNS, PERMISSIONS

```bash theme={null}
coval reports list
```

## Get Report

```bash theme={null}
coval reports get <report_id>
```

| Argument    | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `report_id` | string | **Yes**  | Report ID (26-character ULID) |

```bash theme={null}
coval reports get 01HXYZ1234567890ABCDEF
```

## Report Rows

Read the per-simulation rows of a report. Rows are cursor-paginated.

```bash theme={null}
coval reports rows <report_id> [OPTIONS]
```

| Argument    | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `report_id` | string | **Yes**  | Report ID (26-character ULID) |

| Option             | Type   | Default | Description                                                |
| ------------------ | ------ | ------- | ---------------------------------------------------------- |
| `--limit`          | number | 2000    | Rows per page (1-2000)                                     |
| `--cursor`         | string | —       | Opaque cursor from a previous response's `next_page_token` |
| `--metric-ids`     | string | —       | Comma-separated metric IDs to include                      |
| `--simulation-ids` | string | —       | Comma-separated simulation IDs to restrict the page to     |

**Output columns:** SIMULATION ID, RUN ID, AGENT, PERSONA, STATUS

```bash theme={null}
# All rows, two metrics only
coval reports rows 01HXYZ1234567890ABCDEF --metric-ids "met_001,met_002" --format json
```

## Create Report

```bash theme={null}
coval reports create [OPTIONS]
```

| Option                             | Type   | Required    | Description                                                                                                                           |
| ---------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`                           | string | **Yes**     | Display name for the saved report (1-200 characters)                                                                                  |
| `--run-ids`                        | string | **Yes**     | Comma-separated run IDs to include (min 1)                                                                                            |
| `--compare-by`                     | string | No          | Dimension to group and compare runs by: `none` (default), `run`, `agent`, `mutation`, `persona`, `test_case`, `metadata`, or `custom` |
| `--metadata-key`                   | string | Conditional | Metadata key to group by. Required when `--compare-by metadata`, rejected otherwise                                                   |
| `--view-mode`                      | string | No          | Report layout: `rows` (default) or `grouped`                                                                                          |
| `--simulation-output-ids`          | string | No          | Comma-separated simulation IDs pinning the report to a subset of the runs                                                             |
| `--source-human-review-project-id` | string | No          | Human Review project the pinned simulations came from (26-character ULID)                                                             |
| `--permissions`                    | string | No          | Report visibility: `private` (default) or `public`                                                                                    |

```bash theme={null}
# Compare two runs by agent
coval reports create \
  --name "Prompt v2 vs v1" \
  --run-ids "run_abc123,run_def456" \
  --compare-by agent

# Group by a metadata key
coval reports create \
  --name "By campaign" \
  --run-ids "run_abc123" \
  --compare-by metadata \
  --metadata-key campaign
```

## Merge Reports

Combine existing reports into a new report, with each source report becoming a group.

```bash theme={null}
coval reports merge --report-ids <ids> --name <name> [OPTIONS]
```

| Option             | Type   | Required | Description                                                           |
| ------------------ | ------ | -------- | --------------------------------------------------------------------- |
| `--report-ids`     | string | **Yes**  | Comma-separated IDs of the reports to merge (2-500, must be distinct) |
| `--name`           | string | **Yes**  | Display name for the merged report (1-200 characters)                 |
| `--dimension-name` | string | No       | Label for the generated grouping dimension (default `Report`)         |
| `--permissions`    | string | No       | Merged report visibility: `private` (default) or `public`             |

```bash theme={null}
coval reports merge \
  --report-ids "01HXYZ1234567890ABCDEF,01HXYZ1234567890ABCDEG" \
  --name "Q3 weekly reports" \
  --dimension-name "Week"
```

## Update Report

```bash theme={null}
coval reports update <report_id> [OPTIONS]
```

| Argument    | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `report_id` | string | **Yes**  | Report ID (26-character ULID) |

| Option                             | Type   | Description                                                     |
| ---------------------------------- | ------ | --------------------------------------------------------------- |
| `--name`                           | string | Updated display name                                            |
| `--run-ids`                        | string | Updated comma-separated run IDs (replaces existing)             |
| `--compare-by`                     | string | Updated compare-by dimension (same values as create)            |
| `--metadata-key`                   | string | Updated metadata key (only valid when compare-by is `metadata`) |
| `--simulation-output-ids`          | string | Updated comma-separated simulation IDs (replaces existing)      |
| `--source-human-review-project-id` | string | Updated Human Review project the pinned simulations came from   |
| `--view-config`                    | JSON   | Partial update to the saved view configuration                  |
| `--permissions`                    | string | Updated visibility: `private` or `public`                       |

```bash theme={null}
coval reports update 01HXYZ1234567890ABCDEF --name "Prompt v2 vs v1 (final)" --permissions public
```

## Delete Report

```bash theme={null}
coval reports delete <report_id>
```

| Argument    | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `report_id` | string | **Yes**  | Report ID (26-character ULID) |

```bash theme={null}
coval reports delete 01HXYZ1234567890ABCDEF
```