CLI reference

The docs build generates this page from the voicebench argument parser, so it always matches the released command.

Exit codes: 0 when every assertion passes, 1 when an assertion fails, 2 for a usage or scenario error, and 3 when the adapter cannot load or connect.

voicebench

usage: voicebench [-h] [--version] {run,validate,example,mock-server,synth} ...

Benchmark real-time voice agents: latency, barge-in, and turn-taking.

positional arguments:
  {run,validate,example,mock-server,synth}
    run                 run a scenario against an agent
    validate            check scenario files without running them
    example             print or save a bundled example scenario (omit NAME to list them)
    mock-server         serve the mock agent over the WebSocket protocol
    synth               write a synthetic test signal to a WAV file

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

voicebench run

usage: voicebench run [-h] [-a ADAPTER] [--url URL] [-o KEY=VALUE] [-n REPEAT] [--realtime]
                      [--out OUT] [--format FORMAT] [--no-write] [-q]
                      scenario

positional arguments:
  scenario              path to a scenario YAML file

options:
  -h, --help            show this help message and exit
  -a ADAPTER, --adapter ADAPTER
                        adapter to use (mock, websocket, livekit, pipecat, or module:Class);
                        overrides the scenario
  --url URL             agent URL (sets the adapter's 'url' option)
  -o KEY=VALUE, --option KEY=VALUE
                        adapter option; VALUE is parsed as YAML (repeatable)
  -n REPEAT, --repeat REPEAT
                        number of sessions (default 1)
  --realtime            run the mock adapter on the wall clock instead of virtual time
  --out OUT             output directory (default: voicebench-results/<scenario>-<timestamp>)
  --format FORMAT       comma-separated report formats: json, md, html (default: all)
  --no-write            print the summary only
  -q, --quiet           do not print the summary

voicebench validate

usage: voicebench validate [-h] scenarios [scenarios ...]

positional arguments:
  scenarios

options:
  -h, --help  show this help message and exit

voicebench example

usage: voicebench example [-h] [-O OUTPUT] [name]

positional arguments:
  name                  example name, for example mock-conversation

options:
  -h, --help            show this help message and exit
  -O OUTPUT, --output OUTPUT
                        write the scenario to this file

voicebench mock-server

usage: voicebench mock-server [-h] [--host HOST] [--port PORT] [--sample-rate SAMPLE_RATE]
                              [-o KEY=VALUE]

options:
  -h, --help            show this help message and exit
  --host HOST
  --port PORT
  --sample-rate SAMPLE_RATE
  -o KEY=VALUE, --option KEY=VALUE

voicebench synth

usage: voicebench synth [-h] [--kind {speech,tone,noise,silence}] [--duration-ms DURATION_MS]
                        [--level-db LEVEL_DB] [--sample-rate SAMPLE_RATE]
                        output

positional arguments:
  output

options:
  -h, --help            show this help message and exit
  --kind {speech,tone,noise,silence}
  --duration-ms DURATION_MS
  --level-db LEVEL_DB
  --sample-rate SAMPLE_RATE