CLI

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

GitHub Repository

View source, releases, and contribute

Quick Start

Install the CLI

brew install coval-ai/tap/coval

See Installation for all methods.

Authenticate

coval login

Launch an evaluation

coval runs launch \
  --agent-id <agent_id> \
  --persona-id <persona_id> \
  --test-set-id <test_set_id>

Watch progress

coval runs watch <run_id>

Command Reference

Agents

Create, list, update, and delete agent configurations

Runs

Launch evaluations and monitor progress in real time

Simulated Conversations

Inspect individual simulated conversation results and download audio

Uploaded Conversations

Submit and inspect production conversations, audio, and metric results

Test Sets

Organize test cases into collections

Test Cases

Define inputs and expected outputs for evaluations

Personas

Configure simulated callers with voice and language settings

Metrics

Define how simulations are scored and evaluated

Mutations

Test agent variations with config overrides

API Keys

Manage API keys for programmatic access

Run Templates

Save reusable evaluation configurations

Scheduled Runs

Schedule recurring evaluation runs

Human Review

Manage human review projects and annotations

Dashboards

Create dashboards and widgets for tracking results

Reports

Save, merge, and read multi-run comparison reports

Alerts

Manage alerts and their evaluation events

Traces

Search and inspect OpenTelemetry traces

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	—
`--agent`	Agent mode: non-interactive JSON envelope for scripts and coding agents. See Agent Mode	—
`--help`	Show help for any command	—

JSON Output for Scripting

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

# 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 simulated-conversations get sim123 --format json | jq '.transcript'

Requirements

macOS, Linux, or Windows
Coval API key from Dashboard Settings

Getting Started

Resources

GitHub Repository

Quick Start

Command Reference

Agents

Runs

Simulated Conversations

Uploaded Conversations

Test Sets

Test Cases

Personas

Metrics

Mutations

API Keys

Run Templates

Scheduled Runs

Human Review

Dashboards

Reports

Alerts

Traces

Tags

Global Flags

JSON Output for Scripting

Requirements

GitHub Repository

​Quick Start

​Command Reference

Agents

Runs

Simulated Conversations

Uploaded Conversations

Test Sets

Test Cases

Personas

Metrics

Mutations

API Keys

Run Templates

Scheduled Runs

Human Review

Dashboards

Reports

Alerts

Traces

Tags

​Global Flags

​JSON Output for Scripting

​Requirements

Quick Start

Command Reference

Global Flags

JSON Output for Scripting

Requirements