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

# CLI

> Command-line interface for the Coval AI evaluation platform

The **Coval CLI** provides terminal access to Coval's evaluation APIs for scripting, automation, and CI/CD integration.

<Card title="GitHub Repository" icon="github" href="https://github.com/coval-ai/cli">
  View source, releases, and contribute
</Card>

## Quick Start

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    brew install coval-ai/tap/coval
    ```

    See [Installation](/cli/installation) for all methods.
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    coval login
    ```
  </Step>

  <Step title="Launch an evaluation">
    ```bash theme={null}
    coval runs launch \
      --agent-id <agent_id> \
      --persona-id <persona_id> \
      --test-set-id <test_set_id>
    ```
  </Step>

  <Step title="Watch progress">
    ```bash theme={null}
    coval runs watch <run_id>
    ```
  </Step>
</Steps>

## Command Reference

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/cli/agents">
    Create, list, update, and delete agent configurations
  </Card>

  <Card title="Runs" icon="play" href="/cli/runs">
    Launch evaluations and monitor progress in real time
  </Card>

  <Card title="Simulations" icon="rocket" href="/cli/simulations">
    Inspect individual simulation results and download audio
  </Card>

  <Card title="Conversations" icon="comments" href="/cli/conversations">
    Inspect monitored conversations, audio, and metric results
  </Card>

  <Card title="Test Sets" icon="database" href="/cli/test-sets">
    Organize test cases into collections
  </Card>

  <Card title="Test Cases" icon="flask" href="/cli/test-cases">
    Define inputs and expected outputs for evaluations
  </Card>

  <Card title="Personas" icon="circle-user" href="/cli/personas">
    Configure simulated callers with voice and language settings
  </Card>

  <Card title="Metrics" icon="ballot-check" href="/cli/metrics">
    Define how simulations are scored and evaluated
  </Card>

  <Card title="Mutations" icon="flask-vial" href="/cli/mutations">
    Test agent variations with config overrides
  </Card>

  <Card title="API Keys" icon="key" href="/cli/api-keys">
    Manage API keys for programmatic access
  </Card>

  <Card title="Run Templates" icon="puzzle-piece" href="/cli/run-templates">
    Save reusable evaluation configurations
  </Card>

  <Card title="Scheduled Runs" icon="clock" href="/cli/scheduled-runs">
    Schedule recurring evaluation runs
  </Card>

  <Card title="Dashboards" icon="chart-line" href="/cli/dashboards">
    Create dashboards and widgets for monitoring
  </Card>
</CardGroup>

## Global Flags

All commands support these flags:

| Flag                | Description                       | Default |
| ------------------- | --------------------------------- | ------- |
| `--format <format>` | Output format: `table` or `json`  | `table` |
| `--api-key <key>`   | Override API key for this command | —       |
| `--api-url <url>`   | Override API base URL             | —       |
| `--help`            | Show help for any command         | —       |

## JSON Output for Scripting

Use `--format json` to get machine-readable output:

```bash theme={null}
# Get run status
coval runs get abc123 --format json | jq '.status'

# List agent IDs
coval agents list --format json | jq '.[].id'

# Extract simulation transcript
coval simulations get sim123 --format json | jq '.transcript'
```

## Requirements

* macOS, Linux, or Windows
* Coval API key from [Dashboard Settings](https://app.coval.dev/settings)