Runs

launch and update also accept --input-json (inline JSON, @file, or - for stdin); explicit flags override fields from the JSON. See Input JSON.

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 (1-1000)
`--order-by`	string	`-create_time`	Sort field, prefix with `-` for descending

Supported filter fields: status, agent_id, persona_id, test_set_id, create_time, tag Output columns: ID, STATUS, PROGRESS, CREATED

# List all runs
coval runs list

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

# Runs for one agent, tagged baseline
coval runs list --filter 'agent_id="ag_abc123" AND tag="baseline"'

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 to evaluate (22-char ID)
`--persona-id`	string	Yes	Simulated persona for the run (22-char ID)
`--test-set-id`	string	Yes	Test set to run against (8-char ID)
`--metric-ids`	string	No	Comma-separated metric IDs; defaults to the agent’s metrics
`--iterations`	number	No	Times to repeat each test case (1-50, default 1)
`--concurrency`	number	No	Parallel simulations (1-100, default 1)
`--test-cases`	string	No	Comma-separated test case IDs to run from the test set (1-100)
`--sub-sample-size`	number	No	Random subset of test cases to run (0 = all)
`--sub-sample-seed`	number	No	Seed for reproducible sub-sampling
`--name`	string	No	Display name for the run
`--mutation-id`	string	No	Single mutation to apply (26-char ULID)
`--mutation-ids`	string	No	Comma-separated mutation IDs for multi-mutation runs
`--tags`	string	No	Comma-separated tags for categorizing the run
`--config-overrides`	JSON	No	Launch-specific simulator configuration overriding the stored agent config, e.g. `'{"temperature":0.7}'`

# 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" \
  --tags "nightly,regression"

# Run a random sample of 20 test cases, reproducibly
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --sub-sample-size 20 \
  --sub-sample-seed 42

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

# Override the stored agent config for this launch only
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --config-overrides '{"temperature":0.7}'

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

Follow 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