# Vois CLI Command Reference

Full documentation for all 15 command groups.

## Status

```bash
vois-cli status                    # Check if Vois is running
vois-cli status --format json      # JSON output for scripting
```

## TTS (Text-to-Speech)

### generate

```bash
vois-cli tts generate \
  --text "Hello, world!" \
  --voice narrators_ai_voices/morgan_vale \
  --output hello.wav \
  --speed 1.0 \
  --quality standard \
  --engine standard \
  --language English \
  --instruct "Speak with warmth"
```

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--text`, `-t` | Yes | | Text to convert to speech |
| `--voice`, `-v` | No | `narrators_ai_voices/morgan_vale` | Voice ID (category/slug format) |
| `--output`, `-o` | Yes | | Output file path |
| `--speed`, `-s` | No | `1.0` | Playback speed (0.5-2.0) |
| `--quality`, `-q` | No | `standard` | Quality mode: fast, standard, multilingual, omni |
| `--engine` | No | | Explicit engine override: fast, standard, multilingual, omni |
| `--language`, `-l` | No | | Language (for multilingual or omni engine) |
| `--instruct` | No | | Style instruction. Most useful for Expressive and Omni |
| `--diffusion-steps` | No | `32` | Number of diffusion steps (omni engine only, range 4-64). Higher = better quality, slower |
| `--guidance-scale` | No | `2.0` | Classifier-free guidance scale (omni engine only). Higher = stronger adherence to voice |
| `--voice-design-instruct` | No | | Comma-separated voice attributes from the Omni voice-design vocabulary (omni engine only). E.g. "male, middle-aged, low pitch, american accent" |

Omni flags require a Pro or Founder Pro entitlement. Free and Subscriber licenses should use `fast`, `standard`, or `multilingual`.

### generate-voice-design

Generate speech from voice-design attributes (no preset voice needed). This command routes through the Pro-only Omni engine. The attributes come from a fixed vocabulary, at most one per category: gender (`male`, `female`); age (`child`, `teenager`, `young adult`, `middle-aged`, `elderly`); pitch (`very low pitch`, `low pitch`, `moderate pitch`, `high pitch`, `very high pitch`); style (`whisper`); accent (`american accent`, `british accent`, `australian accent`, `chinese accent`, `canadian accent`, `indian accent`, `korean accent`, `portuguese accent`, `russian accent`, `japanese accent`). Free-text descriptions fail with `InstructInvalid`.

```bash
vois-cli tts generate-voice-design \
  --text "Hello, welcome to the show" \
  --voice-design "female, young adult, moderate pitch, american accent" \
  --output custom.wav \
  --speed 1.0 \
  --language English \
  --diffusion-steps 32 \
  --guidance-scale 2.0
```

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--text`, `-t` | Yes | | Text to convert |
| `--voice-design`, `-d` | Yes | | Comma-separated attributes from the voice-design vocabulary (see above) |
| `--output`, `-o` | Yes | | Output file path |
| `--speed`, `-s` | No | `1.0` | Playback speed (0.5-2.0) |
| `--language`, `-l` | No | `English` | Language |
| `--diffusion-steps` | No | `32` | Number of diffusion steps (omni engine only, range 4-64). Higher = better quality, slower |
| `--guidance-scale` | No | `2.0` | Classifier-free guidance scale (omni engine only). Higher = stronger adherence to voice design |

### batch-file

Generate audio for each line in a text file.

```bash
vois-cli tts batch-file \
  --input lines.txt \
  --output-dir ./audio/ \
  --voice narrators_ai_voices/morgan_vale \
  --speed 1.0 \
  --quality standard \
  --engine standard \
  --prefix "line" \
  --language English \
  --instruct "Speak clearly" \
  --skip-existing
```

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--input`, `-i` | Yes | | Input text file (one line per output) |
| `--output-dir`, `-o` | Yes | | Output directory |
| `--voice`, `-v` | No | `narrators_ai_voices/morgan_vale` | Voice ID |
| `--speed`, `-s` | No | `1.0` | Playback speed |
| `--prefix`, `-p` | No | `line` | Output filename prefix |
| `--language`, `-l` | No | | Language |
| `--quality`, `-q` | No | `standard` | Quality mode: fast, standard, multilingual, omni |
| `--engine` | No | | Explicit engine override: fast, standard, multilingual, omni |
| `--instruct`, `-I` | No | | Style instruction. For Omni, use this for voice/style design instructions |
| `--diffusion-steps` | No | `32` | Number of diffusion steps (omni engine only, range 4-64) |
| `--guidance-scale` | No | `2.0` | Classifier-free guidance scale (omni engine only) |
| `--voice-design-instruct` | No | | Voice design instruction for the Omni engine |
| `--skip-existing` | No | | Skip lines with existing audio files |

Output files: `{prefix}_0001.wav`, `{prefix}_0002.wav`, ...

### silence

Generate a silent audio file of specified duration.

```bash
vois-cli tts silence --duration 500 --output pause.wav    # Save to file
vois-cli tts silence --duration 1000                       # Returns cache path
```

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--duration`, `-d` | Yes | | Duration in milliseconds |
| `--output`, `-o` | No | | Output file path (omit for cache path) |

### preview

Preview a voice (plays audio, doesn't save to disk).

```bash
vois-cli tts preview --voice narrators_ai_voices/morgan_vale --text "Testing voice preview"
```

### status

```bash
vois-cli tts status              # Current TTS engine status
```

### cancel

```bash
vois-cli tts cancel              # Cancel in-progress generation
```

## Voice

### list

```bash
vois-cli voice list                          # All voices
vois-cli voice list --source library         # Library voices only
vois-cli voice list --source cloned          # Cloned voices only
vois-cli voice list --source designed        # Designed Omni voices only
vois-cli voice list --source all             # Library + builtin + cloned + designed
vois-cli voice list --gender female          # Filter by gender
vois-cli voice list --category narrators_ai_voices  # Filter by category
vois-cli voice list --engine omni            # Filter library voices by engine
vois-cli voice list --source all --format json       # Full casting metadata for agents
```

Voice IDs returned by this command are valid for `--voice`. Library voices use `category_slug/voice_slug`; cloned voices use `cloned_<slug>`; designed voices use `designed_<slug>`.

JSON output returns full voice records. Use `personality`, `description`, `category_name`, `sample_speech_prompt`, and `reference_text` when selecting a voice for a speaker. The `--engine` filter accepts public names: `fast`, `standard`, `expressive`, `multilingual`, and `omni`.

### get

```bash
vois-cli voice get --id narrators_ai_voices/morgan_vale
```

Returns the full voice record for one ID, including voice personality, reference transcript, supported engines, source, category, and avatar metadata when available.

### search

```bash
vois-cli voice search --query "warm conversational"
```

Search matches names, descriptions, category labels, personality prompts, reference text, cloned voice notes, and designed voice instructions.

### clone

Clone a voice from a reference audio sample. Requires an active paid plan.

```bash
vois-cli voice clone \
  --name "My Custom Voice" \
  --audio /path/to/reference.wav \
  --consent-confirmed
```

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | Yes | Display name for the cloned voice |
| `--audio` | Yes | Path to reference audio (10-15s, WAV/MP3/FLAC/M4A/OGG) |
| `--consent-confirmed` | Yes | Confirms you have the voice owner's permission |

### clone-list

```bash
vois-cli voice clone-list          # List all cloned voices
```

### design-list

```bash
vois-cli voice design-list         # List all saved designed Omni voices
```

Saved designed voices are Pro/Founder Pro-oriented Omni reference voices. They can be listed on any licensed app, but creating or generating with them through Omni requires Pro entitlement.

### clone-delete

```bash
vois-cli voice clone-delete --slug my_custom_voice
```

### design-delete

```bash
vois-cli voice design-delete --slug warm_narrator
```

## Project

```bash
vois-cli project create --name "My Podcast"
vois-cli project list
vois-cli project get --id 1
vois-cli project update --id 1 --name "New Name" --description "Updated"
vois-cli project delete --id 1 --force
```

## Script

Scripts are content units within a project (episodes, chapters, etc.).

```bash
vois-cli script create --project 1 --title "Episode 1"
vois-cli script create --project 1 --title "Episode 1" --content "[Host]: Welcome!"
vois-cli script list --project 1
vois-cli script get --id 1
vois-cli script update --id 1 --content "[Host]: Updated content"
vois-cli script delete --id 1 --force
vois-cli script reorder --project 1 --ids "2,1,3"
vois-cli script segments --id 1
vois-cli script generate --id 1 --voice narrators_ai_voices/morgan_vale --speed 1.1
```

## Speaker

Speakers are voice assignments within a script.

```bash
vois-cli speaker create --script 1 --name "Host" --voice narrators_ai_voices/morgan_vale
vois-cli speaker create --script 1 --name "Guest" --voice hosts_ai_voices/alex_bright --color "#22c55e"
vois-cli speaker list --script 1
vois-cli speaker update --id 1 --voice broadcasters_ai_voices/lisa_chen
vois-cli speaker delete --id 1
```

## Export

### audio

```bash
vois-cli export audio --input audio.wav --output audio.mp3 --audio-format mp3 --bitrate 256
vois-cli export audio --input audio.wav --output audio.m4a --audio-format aac --bitrate 128
vois-cli export audio --input audio.wav --output normalized.mp3 --normalize --target-lufs -16.0
```

### mp3

```bash
vois-cli export mp3 --input audio.wav --output audio.mp3 --bitrate 192
```

### with-profile

```bash
vois-cli export with-profile --input audio.wav --output podcast.mp3 --profile apple_podcasts
```

### compile-script / compile-project

```bash
vois-cli export compile-script --script 1
vois-cli export compile-project --project 1
```

### profiles / profile

```bash
vois-cli export profiles                     # List all profiles
vois-cli export profile --id acx_audiobook   # Get profile details
```

## Mastering

```bash
vois-cli mastering get                                      # Current config
vois-cli mastering set --target-lufs -16.0                   # Set LUFS target
vois-cli mastering set --enabled true                        # Enable mastering
vois-cli mastering set --peak-ceiling -1.0                   # Peak ceiling
vois-cli mastering set --de-esser true --de-esser-freq 7000  # De-esser
vois-cli mastering set --limiter true --limiter-threshold -1.0
vois-cli mastering reset                                     # Reset to defaults
```

## Pronunciation

```bash
vois-cli pronunciation add --word "nginx" --pronunciation "engine-x" --context "web server"
vois-cli pronunciation add --word "API" --pronunciation "A P I" --scope "project_123"
vois-cli pronunciation list
vois-cli pronunciation list --scope global
vois-cli pronunciation search --query "tech"
vois-cli pronunciation update --id 1 --pronunciation "new pronunciation"
vois-cli pronunciation delete --id 1
vois-cli pronunciation delete-scope --scope "project_123" --force
vois-cli pronunciation import --file pronunciations.csv --scope global
vois-cli pronunciation export --output pronunciations.csv
```

**CSV format:** `word,pronunciation,context`

## Model

```bash
vois-cli model list                          # List engines + download status
vois-cli model status                        # Current engine info
vois-cli model switch --engine fast           # Switch engine
vois-cli model switch --engine standard       # Expressive English
vois-cli model switch --engine multilingual   # Legacy 23-language model
vois-cli model switch --engine omni           # 646 languages
vois-cli model switch --engine omni --provider auto --quant auto
vois-cli model switch --engine expressive --provider coreml --quant fp16
vois-cli model switch --engine expressive --provider directml --quant fp16
vois-cli model download --model standard      # Download model
vois-cli model download --model multilingual
vois-cli model download --model omni
```

`model switch` flags:

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--engine`, `-e` | Yes | | fast, standard/expressive, multilingual, omni |
| `--provider` | No | `auto` | auto, coreml, directml, cpu, cuda |
| `--quant` | No | `auto` | auto, fp16, fp32. Deprecated q4/q4f16 values are rejected |

## Calendar

```bash
vois-cli calendar create --script 1 --title "Episode Release"
vois-cli calendar list
vois-cli calendar list --status scheduled
vois-cli calendar get --id "abc123"
vois-cli calendar update --id "abc123" --title "New Title" --status draft
vois-cli calendar schedule --id "abc123" --time "2026-03-15T10:00:00Z"
vois-cli calendar delete --id "abc123" --force
```

## Platform

```bash
vois-cli platform list                       # Connected platforms
vois-cli platform get --platform spotify
vois-cli platform disconnect --platform buzzsprout --force
```

Supported: `spotify` (OAuth), `buzzsprout` (API Key), `transistor` (API Key).

## RSS

Generate iTunes-compliant RSS feeds.

```bash
vois-cli rss generate \
  --title "My Podcast" \
  --description "A podcast about technology" \
  --link "https://example.com/podcast" \
  --author "Jane Doe" \
  --output feed.xml \
  --owner-name "Jane Doe" \
  --owner-email "jane@example.com" \
  --image-url "https://example.com/cover.jpg" \
  --category "Technology" \
  --episodes-file episodes.json
```

## Timeline

```bash
vois-cli timeline get --script 1
vois-cli timeline save --script 1 --data '{"tracks": [...]}'
vois-cli timeline delete --script 1
```

## Settings

```bash
vois-cli settings get-consent                # Sentry error tracking status
vois-cli settings set-consent --enabled true
```