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

# Simulations

> View simulation results and download audio with the Coval CLI

## List Simulations

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

| Option        | Type   | Default | Description       |
| ------------- | ------ | ------- | ----------------- |
| `--filter`    | string | —       | Filter expression |
| `--run-id`    | string | —       | Filter by run ID  |
| `--page-size` | number | 50      | Results per page  |
| `--order-by`  | string | —       | Sort order        |

**Output columns:** ID, STATUS, RUN, TEST CASE, AUDIO

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

# Filter by run
coval simulations list --run-id run_abc123

# Combine filters
coval simulations list --filter 'status="COMPLETED"' --run-id run_abc123
```

## Get Simulation

```bash theme={null}
coval simulations get <simulation_id>
```

| Argument        | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `simulation_id` | string | **Yes**  | The simulation ID |

Returns full simulation details as JSON including transcript, status, and metadata.

```bash theme={null}
coval simulations get sim_abc123
```

## Download Audio

Download or get the audio URL for a simulation recording.

```bash theme={null}
coval simulations audio <simulation_id> [OPTIONS]
```

| Argument        | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `simulation_id` | string | **Yes**  | The simulation ID |

| Option         | Type   | Description             |
| -------------- | ------ | ----------------------- |
| `-o, --output` | string | File path to save audio |

```bash theme={null}
# Print audio URL
coval simulations audio sim_abc123

# Download audio file
coval simulations audio sim_abc123 -o recording.wav
```

When using `-o`, a progress bar shows the download status.

## List Metrics

List all metric results for a simulation.

```bash theme={null}
coval simulations metrics <simulation_id>
```

| Argument        | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `simulation_id` | string | **Yes**  | The simulation ID |

**Output columns:** OUTPUT ID, METRIC ID, STATUS, VALUE, SUBVALUES

```bash theme={null}
coval simulations metrics sim_abc123
```

## Get Metric Detail

Retrieve metric results for a simulation. The second argument accepts two ID types and the output adapts accordingly:

* **26-char MetricOutput ULID** — prints one row (the specific output).
* **22-char Metric definition ID** — prints every output recorded for that metric on the simulation.

```bash theme={null}
coval simulations metric-detail <simulation_id> <id>
```

| Argument        | Type   | Required | Description                                                          |
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
| `simulation_id` | string | **Yes**  | The simulation ID                                                    |
| `id`            | string | **Yes**  | Either a 26-char MetricOutput ULID or a 22-char Metric definition ID |

By MetricOutput ULID (one row):

```bash theme={null}
coval simulations metric-detail sim_abc123 01ARZ3NDEKTSV4RRFFQ69G5FAV
```

By Metric definition ID (one or more rows):

```bash theme={null}
coval simulations metric-detail sim_abc123 29BlkepvvX19ebbLDB0y6Q
```

## Delete Simulation

```bash theme={null}
coval simulations delete <simulation_id>
```

| Argument        | Type   | Required | Description                 |
| --------------- | ------ | -------- | --------------------------- |
| `simulation_id` | string | **Yes**  | The simulation ID to delete |

## Simulation Statuses

| Status        | Description                               |
| ------------- | ----------------------------------------- |
| `PENDING`     | Simulation is created but not yet started |
| `IN_QUEUE`    | Simulation is queued for execution        |
| `IN_PROGRESS` | Simulation is actively running            |
| `COMPLETED`   | Simulation finished successfully          |
| `FAILED`      | Simulation encountered an error           |
| `CANCELLED`   | Simulation was cancelled                  |
| `DELETED`     | Simulation was deleted                    |

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