Runs

List Runs

coval runs list [OPTIONS]

Option	Type	Default	Description
`--filter`	string	—	Filter expression (e.g., `status="COMPLETED"`)
`--page-size`	number	50	Results per page
`--order-by`	string	—	Sort order (e.g., `-create_time`)

Output columns: ID, STATUS, PROGRESS, CREATED

# List all runs
coval runs list

# Filter completed runs
coval runs list --filter 'status="COMPLETED"'

Get Run

coval runs get <run_id>

Argument	Type	Required	Description
`run_id`	string	Yes	The run ID

Returns full run details as JSON including status, progress, results, and metrics.

coval runs get run_abc123

Launch Run

coval runs launch [OPTIONS]

Option	Type	Required	Description
`--agent-id`	string	Yes	Agent ID to evaluate
`--persona-id`	string	Yes	Persona ID for simulated caller
`--test-set-id`	string	Yes	Test set ID containing test cases
`--iterations`	number	No	Iterations per test case (default: 1)
`--concurrency`	number	No	Parallel simulations
`--name`	string	No	Display name for the run
`--mutation-id`	string	No	Single mutation ID to test
`--mutation-ids`	string	No	Comma-separated mutation IDs

# Basic run
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456

# Run with options
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --iterations 3 \
  --concurrency 5 \
  --name "Regression Test"

# Run with mutations
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --mutation-ids "mut_001,mut_002,mut_003"

Update Run

Modify tags on an existing run. Tags are fully replaced — pass the complete list you want on the run.

coval runs update <run_id> --tags <tag1,tag2,...>

Argument	Type	Required	Description
`run_id`	string	Yes	The run ID to update

Option	Type	Required	Description
`--tags`	string	Yes	Comma-separated tags; replaces existing tags. Pass `""` to clear all tags.

# Mark a run as the current baseline
coval runs update run_abc123 --tags baseline,prod

# Remove all tags from a run
coval runs update run_abc123 --tags ""

Max 20 tags per run, each up to 200 characters. Whitespace is trimmed and duplicates are dropped.

Watch Run

Monitor a run’s progress in real time with a live progress bar.

coval runs watch <run_id> [OPTIONS]

Argument	Type	Required	Description
`run_id`	string	Yes	The run ID to watch

Option	Type	Default	Description
`--interval`	number	2	Poll interval in seconds

# Watch with default interval
coval runs watch run_abc123

# Watch with faster polling
coval runs watch run_abc123 --interval 1

The watch command displays a progress bar and exits when the run reaches a terminal status.

Delete Run

coval runs delete <run_id>

Argument	Type	Required	Description
`run_id`	string	Yes	The run ID to delete

Run Statuses

Status	Description
`PENDING`	Run is created but not yet started
`IN_QUEUE`	Run is queued for execution
`IN_PROGRESS`	Simulations are actively running
`COMPLETED`	All simulations finished successfully
`FAILED`	Run encountered an error
`CANCELLED`	Run was cancelled
`DELETED`	Run was deleted

When using --filter, use the underscore-separated enum values (e.g., status="IN_PROGRESS").

Getting Started

Resources

List Runs

Get Run

Launch Run

Update Run

Watch Run

Delete Run

Run Statuses

​List Runs

​Get Run

​Launch Run

​Update Run

​Watch Run

​Delete Run

​Run Statuses

List Runs

Get Run

Launch Run

Update Run

Watch Run

Delete Run

Run Statuses