Reports

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.

List Reports

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

coval reports list

Get Report

coval reports get <report_id>

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

coval reports get 01HXYZ1234567890ABCDEF

Report Rows

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

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

# All rows, two metrics only
coval reports rows 01HXYZ1234567890ABCDEF --metric-ids "met_001,met_002" --format json

Create Report

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`

# 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.

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`

coval reports merge \
  --report-ids "01HXYZ1234567890ABCDEF,01HXYZ1234567890ABCDEG" \
  --name "Q3 weekly reports" \
  --dimension-name "Week"

Update Report

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`

coval reports update 01HXYZ1234567890ABCDEF --name "Prompt v2 vs v1 (final)" --permissions public

Delete Report

coval reports delete <report_id>

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

coval reports delete 01HXYZ1234567890ABCDEF

Getting Started

Resources

List Reports

Get Report

Report Rows

Create Report

Merge Reports

Update Report

Delete Report

​List Reports

​Get Report

​Report Rows

​Create Report

​Merge Reports

​Update Report

​Delete Report

List Reports

Get Report

Report Rows

Create Report

Merge Reports

Update Report

Delete Report