Personas

create and update also accept --input-json (inline JSON, @file, or - for stdin); explicit flags override fields from the JSON. See Input JSON.

List Personas

coval personas list [OPTIONS]

Option	Type	Default	Description
`--filter`	string	—	Filter expression (supports `name`, `create_time`, `update_time`)
`--page-size`	number	50	Results per page (1-100)
`--order-by`	string	`-create_time`	Sort field, prefix with `-` for descending

Output columns: ID, NAME, VOICE, LANGUAGE, CREATED

coval personas list

Get Persona

coval personas get <persona_id>

Argument	Type	Required	Description
`persona_id`	string	Yes	The persona ID

coval personas get per_abc123

Create Persona

coval personas create [OPTIONS]

The CLI does not enforce any flag on its own, because every field can also arrive through --input-json. The API requires name, voice, and language.

Option	Type	Required	Description
`--name`	string	No	Persona name (1-200 characters)
`--voice`	string	No	Voice name for speech synthesis (see `coval personas voices`)
`--language`	string	No	Language code in BCP-47 format (e.g., `en-US`)
`--prompt`	string	No	Persona behavior instructions
`--background`	string	No	Background sound (e.g., `office`, `cafe`, `airport`, or a custom sound ID)
`--background-sound-volume`	number	No	Background sound volume multiplier (>= 0.0)
`--voice-volume`	number	No	Voice gain multiplier (0.0 silent, 1.0 unchanged, 2.0 double)
`--voice-speed`	number	No	Voice speed multiplier (0.25-2.0, 1.0 unchanged)
`--wait-seconds`	number	No	Seconds to wait before speaking (0.1-2.0)
`--hold-music-timeout-seconds`	number	No	Disconnect after this many seconds of no speech (5-300)
`--interruption-rate`	string	No	Timer-driven interruption of agent speech (`NONE`, `LOW`, `MEDIUM`, or `HIGH`)
`--multi-language-stt[=true\|false]`	boolean	No	Enable multilingual speech recognition; passing the flag without a value enables it
`--situate-speaker`	string	No	Placement preset (`speakerphone-easy` or `speakerphone-hard`); conflicts with `--audio-degradation`
`--audio-degradation`	string	No	Channel degradation preset (`landline`, `cell-poor`, `cell-handoff`) or a JSON object; conflicts with `--situate-speaker`
`--tags`	string	No	Comma-separated tag names; pass an empty value to clear all tags

# Create a basic persona
coval personas create \
  --name "Frustrated Customer" \
  --voice "Aria" \
  --language "en-US"

# Create with full configuration
coval personas create \
  --name "Impatient Caller" \
  --voice "Callum" \
  --language "en-US" \
  --prompt "You are an impatient customer who wants quick answers" \
  --background "office" \
  --background-sound-volume 0.4 \
  --voice-speed 1.2 \
  --wait-seconds 1.5 \
  --interruption-rate HIGH \
  --multi-language-stt

# Simulate a poor cell connection
coval personas create \
  --name "Cell Caller" \
  --voice "Aria" \
  --language "en-US" \
  --audio-degradation cell-poor

Use --multi-language-stt when the agent may speak more than one language in the same conversation. To set it explicitly, pass --multi-language-stt=true or --multi-language-stt=false. JSON input accepts either multi_language_stt or multiLanguageStt and sends the canonical multi_language_stt field. Explicit command-line flags override values from --input-json.

coval personas create \
  --input-json '{"name":"Bilingual Caller","voice_name":"marina","language_code":"en-US","multi_language_stt":true}'

Update Persona

coval personas update <persona_id> [OPTIONS]

Argument	Type	Required	Description
`persona_id`	string	Yes	The persona ID to update

Option	Type	Description
`--name`	string	New name (1-200 characters)
`--voice`	string	New voice name
`--language`	string	New language code (BCP-47)
`--prompt`	string	New behavior instructions
`--background`	string	New background sound
`--background-sound-volume`	number	New background sound volume multiplier (>= 0.0)
`--voice-volume`	number	New voice gain multiplier (0.0-2.0)
`--voice-speed`	number	New voice speed multiplier (0.25-2.0)
`--wait-seconds`	number	New wait time before speaking (0.1-2.0)
`--hold-music-timeout-seconds`	number	New no-speech disconnect timeout (5-300)
`--interruption-rate`	string	New interruption rate (`NONE`, `LOW`, `MEDIUM`, or `HIGH`)
`--multi-language-stt[=true\|false]`	boolean	Enable or disable multilingual speech recognition
`--situate-speaker`	string	Placement preset (`speakerphone-easy` or `speakerphone-hard`); conflicts with `--audio-degradation`
`--audio-degradation`	string	Channel degradation preset (`landline`, `cell-poor`, `cell-handoff`) or a JSON object; conflicts with `--situate-speaker`
`--tags`	string	Comma-separated tag names; pass an empty value to clear all tags

coval personas update per_abc123 --voice "Brynn" --wait-seconds 2.0

# Disable multilingual speech recognition
coval personas update per_abc123 --multi-language-stt=false

Delete Persona

coval personas delete <persona_id>

Argument	Type	Required	Description
`persona_id`	string	Yes	The persona ID to delete

Voices

List the voices available for --voice, with the languages each one supports.

coval personas voices

Output columns: VOICE NAME, SUPPORTED LANGUAGES

# Find voices that support German
coval personas voices --format json | jq '.[] | select(.supported_languages | index("de-DE"))'

Phone Numbers

List the phone numbers available for voice simulations with their index mappings. Use these indices when configuring a persona’s caller phone number.

coval personas phone-numbers

Output columns: INDEX, PHONE NUMBER

Background Sounds

Custom background sounds are audio files you upload once and then reference from --background when creating or updating a persona. All commands are nested under coval personas background-sounds.

List Background Sounds

coval personas background-sounds list [OPTIONS]

Option	Type	Description
`--include-archived`	flag	Include archived custom background sounds

Output columns: ID, VALUE, SOURCE, STATUS, DISPLAY NAME, VOLUME

Upload Background Sound

coval personas background-sounds upload <file> [OPTIONS]

Argument	Type	Required	Description
`file`	path	Yes	Local WAV or MP3 file to upload

Option	Type	Description
`--display-name`	string	Display name for the sound. Defaults to the filename stem
`--content-type`	string	Audio content type. Defaults from the file extension (`.mp3` or `.wav`)
`--default-volume`	number	Default volume multiplier for simulations (0.0-1.0)
`--acoustic-source-type`	string	Acoustic rendering behavior: `ambient` or `point_source`
`--metadata`	`key=value`	Metadata to attach. Repeat for multiple

coval personas background-sounds upload ./call-center.wav \
  --display-name "Busy call center" \
  --default-volume 0.3 \
  --acoustic-source-type ambient

Update Background Sound

coval personas background-sounds update <background_sound_id> [OPTIONS]

Argument	Type	Required	Description
`background_sound_id`	string	Yes	Custom background sound ID. Accepts either `sound_id` or `custom:sound_id`

Option	Type	Description
`--display-name`	string	New display name
`--default-volume`	number	New default volume multiplier (0.0-1.0)
`--acoustic-source-type`	string	New acoustic rendering behavior: `ambient` or `point_source`
`--status`	string	`active` or `archived` — archive or restore the sound

# Archive a sound
coval personas background-sounds update bgs_abc123 --status archived

Getting Started

Resources

List Personas

Get Persona

Create Persona

Update Persona

Delete Persona

Voices

Phone Numbers

Background Sounds

List Background Sounds

Upload Background Sound

Update Background Sound

​List Personas

​Get Persona

​Create Persona

​Update Persona

​Delete Persona

​Voices

​Phone Numbers

​Background Sounds

​List Background Sounds

​Upload Background Sound

​Update Background Sound

List Personas

Get Persona

Create Persona

Update Persona

Delete Persona

Voices

Phone Numbers

Background Sounds

List Background Sounds

Upload Background Sound

Update Background Sound