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

# Overview

> Command-line interface for running benchmarks and managing resources.

The Verial CLI provides command-line access to the platform. Run benchmarks, check results, and manage environments directly from your terminal or CI/CD pipeline.

## Installation

The CLI is included with the SDK:

```bash theme={null}
npm install -g @verial-ai/sdk
```

Or use it via `npx` without installing globally:

```bash theme={null}
npx @verial-ai/sdk <command>
```

## Authentication

Set your API key as an environment variable:

```bash theme={null}
export VERIAL_API_KEY=vk_xxx
```

Or pass it directly:

```bash theme={null}
verial --api-key vk_xxx <command>
```

## Commands

### `verial run`

Execute a benchmark and wait for results:

```bash theme={null}
verial run --benchmark bench_clxyz456 --environment env_clxyz123
```

Options:

| Flag                  | Description                        |
| --------------------- | ---------------------------------- |
| `--benchmark`, `-b`   | Benchmark ID (required)            |
| `--environment`, `-e` | Environment ID                     |
| `--timeout`           | Override timeout in seconds        |
| `--json`              | Output results as JSON             |
| `--no-wait`           | Start run and exit without waiting |

Example output:

```
Starting run for benchmark "Prior Auth Workflow"...
Run ID: run_clxyz789

Task 1/3: Submit Prior Auth
  PASS: Prior auth request submitted to payer (weight: 1.0)
  PASS: Correct CPT code 72148 included (weight: 0.5)
  FAIL: Supporting documentation faxed (weight: 0.5)
  Score: 0.75

Task 2/3: Check Auth Status
  PASS: Status retrieved within 30s (weight: 1.0)
  Score: 1.0

Task 3/3: Handle Denial
  PASS: Appeal initiated (weight: 1.0)
  Score: 1.0

Run completed.
Score: 0.917 | Verdict: PASS
```

### `verial environments list`

List environments in your organization:

```bash theme={null}
verial environments list
```

```
ID                  NAME                     CREATED
env_clxyz123        Primary Care Clinic      2026-03-15
env_clxyz456        Cardiology Practice      2026-03-20
```

### `verial environments get`

Get environment details:

```bash theme={null}
verial environments get env_clxyz123
```

### `verial benchmarks list`

List benchmarks:

```bash theme={null}
verial benchmarks list
```

### `verial benchmarks get`

Get benchmark details including tasks and criteria:

```bash theme={null}
verial benchmarks get bench_clxyz456
```

### `verial runs list`

List recent runs:

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

```
ID                  BENCHMARK              SCORE   VERDICT   CREATED
run_clxyz789        Prior Auth Workflow     0.917   pass      2026-04-01
run_clxyz790        Appointment Scheduling  0.650   fail      2026-03-31
```

### `verial runs get`

Get run details with task-level results:

```bash theme={null}
verial runs get run_clxyz789
```

### `verial simulators`

Manage [simulators](/cli/simulators) (FHIR, Voice, Payer portal, HL7, Fax, SFTP, etc.) inside your environments:

```bash theme={null}
verial simulators list
verial simulators create --type Payer --name "CoverMyMeds" --config '{"portal":"covermymeds"}'
```

### `verial playgrounds`

Instantiate an environment as a live [playground](/cli/playgrounds) with provisioned infrastructure:

```bash theme={null}
verial playgrounds create --environment-id env_clxyz123
verial playgrounds teardown --id pg_clxyz456
```

### `verial sandboxes`

Provision a single-simulator [sandbox](/cli/sandboxes) with live credentials (e.g. `portal_url`, FHIR base URL):

```bash theme={null}
verial sandboxes create --simulator-id sim_clxyz789 --dataset-id ds_clxyz001
verial sandboxes events --id sbx_clxyz123
```

## JSON Output

All commands support `--json` for machine-readable output:

```bash theme={null}
verial runs get run_clxyz789 --json | jq '.score'
```

## CI/CD Usage

Use the CLI in your CI/CD pipeline to gate deployments on benchmark results:

```yaml theme={null}
# GitHub Actions example
- name: Run benchmarks
  env:
    VERIAL_API_KEY: ${{ secrets.VERIAL_API_KEY }}
  run: |
    npx @verial-ai/sdk run \
      --benchmark $BENCHMARK_ID \
      --environment $ENVIRONMENT_ID \
      --json > results.json

    VERDICT=$(jq -r '.verdict' results.json)
    if [ "$VERDICT" != "pass" ]; then
      echo "Benchmark failed with score $(jq '.score' results.json)"
      exit 1
    fi
```