> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# verial benchmark-runs

> Start, inspect, and wait on benchmark runs from the command line.

The `verial benchmark-runs` commands manage [Benchmark Runs](/api-reference/resources/runs) — a single execution of a benchmark that produces a verdict, score, and per-task results. Use them to launch runs from CI and block on completion.

Authentication is required. See [verial auth](/cli/auth).

## Subcommands

| Command                        | Description                                                    |
| ------------------------------ | -------------------------------------------------------------- |
| `verial benchmark-runs list`   | List recent benchmark runs in your organization.               |
| `verial benchmark-runs create` | Start a new benchmark run.                                     |
| `verial benchmark-runs get`    | Get a single benchmark run by ID.                              |
| `verial benchmark-runs wait`   | Poll a run until it completes, then exit based on its verdict. |

## verial benchmark-runs list

List benchmark runs visible to your organization.

Synopsis:

```bash theme={null}
verial benchmark-runs list
```

Example:

```bash theme={null}
verial benchmark-runs list
```

```
ID                  STATUS      VERDICT   SCORE   CREATED
run_cm456001        completed   pass      0.917   4/22/2026, 3:41:08 PM
run_cm456002        completed   fail      0.650   4/22/2026, 3:42:11 PM
run_cm456003        active      —         —       4/23/2026, 9:18:44 AM
```

REST equivalent: [GET /runs](/api-reference/runs/list).

## verial benchmark-runs create

Start a new run of a benchmark. The run executes asynchronously; use `verial benchmark-runs wait` to block on completion.

Synopsis:

```bash theme={null}
verial benchmark-runs create --benchmark-id <id> [--environment-id <id>]
```

Options:

| Flag                    | Description                                        | Required |
| ----------------------- | -------------------------------------------------- | -------- |
| `--benchmark-id <id>`   | Benchmark to execute.                              | Yes      |
| `--environment-id <id>` | Override the environment the benchmark references. | No       |

Example:

```bash theme={null}
verial benchmark-runs create \
  --benchmark-id bench_cly987 \
  --environment-id env_clxyz123
```

REST equivalent: [POST /runs](/api-reference/runs/create).

## verial benchmark-runs get

Fetch a single benchmark run, including status, verdict, score, and task-level summaries.

Synopsis:

```bash theme={null}
verial benchmark-runs get --id <id>
```

Example:

```bash theme={null}
verial benchmark-runs get --id run_cm456001
```

```
id         run_cm456001
status     completed
verdict    pass
score      0.917
createdAt  4/22/2026, 3:41:08 PM
```

REST equivalent: [GET /runs/:id](/api-reference/runs/get).

## verial benchmark-runs wait

Poll a run until it leaves the `active` state, then exit 0 on `pass` or 1 otherwise. Exits with an error if the run does not complete within `--timeout`. Pair with `--json` in CI to capture the final run object.

Synopsis:

```bash theme={null}
verial benchmark-runs wait --id <id> [--interval <seconds>] [--timeout <seconds>]
```

Options:

| Flag                   | Description        | Default  |
| ---------------------- | ------------------ | -------- |
| `--id <id>`            | Run ID to wait on. | Required |
| `--interval <seconds>` | Polling interval.  | `5`      |
| `--timeout <seconds>`  | Maximum wait time. | `600`    |

Example:

```bash theme={null}
verial benchmark-runs wait --id run_cm456001 --interval 10 --timeout 900
```

Exit codes:

| Code | Meaning                                                              |
| ---- | -------------------------------------------------------------------- |
| `0`  | Run completed with verdict `pass`.                                   |
| `1`  | Run completed with a non-pass verdict, or the API returned an error. |
| `2`  | CLI error (timeout, invalid flags, unreachable API).                 |

## CI example

```bash theme={null}
RUN=$(verial benchmark-runs create \
  --benchmark-id "$BENCHMARK_ID" \
  --environment-id "$ENV_ID" \
  --json | jq -r '.id')

verial benchmark-runs wait --id "$RUN" --timeout 1800 --json > run.json
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Runs" icon="play" href="/api-reference/resources/runs">
    Run model, statuses, and verdict semantics.
  </Card>

  <Card title="Runs API" icon="code" href="/api-reference/runs/list">
    Full REST parameters and response schema.
  </Card>
</CardGroup>