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

# Runs

> Launch and manage evaluation runs with the Coval CLI

## List Runs

```bash theme={null}
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

```bash theme={null}
# List all runs
coval runs list

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

## Get Run

```bash theme={null}
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.

```bash theme={null}
coval runs get run_abc123
```

## Launch Run

```bash theme={null}
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          |

```bash theme={null}
# 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.

```bash theme={null}
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. |

```bash theme={null}
# 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 ""
```

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

## Watch Run

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

```bash theme={null}
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 |

```bash theme={null}
# 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

```bash theme={null}
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                       |

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