---
name: vois-cli
description: >
  Automate Vois voice AI studio from the command line. Use when generating
  speech from text, managing voice projects, exporting audio, cloning voices,
  switching TTS engines, or integrating Vois into CI/CD and AI agent workflows.
  Requires the Vois desktop app to be running. Covers 15 command groups:
  status, tts, voice, project, script, speaker, export, mastering,
  pronunciation, calendar, platform, rss, model, timeline, settings.
version: "2.0.1"
---

# Vois CLI

Automate the Vois voice AI studio from any terminal, script, or AI agent.

## Overview

Vois is a desktop voice AI studio for creating podcasts, audiobooks, YouTube narration, game dialogue, training content, and more. The `vois-cli` tool lets you control Vois programmatically, enabling automation from AI coding agents (Claude Code, Cursor, OpenCode) and shell scripts.

**Key capabilities:**

- Generate speech from text with library, cloned, or designed voices
- Switch between 4 TTS engines: Fast (English), Expressive (English), Multilingual (legacy, 23 major languages), Omni (646 languages, Pro)
- Clone voices from audio samples (10 to 15 second reference) and list saved designed voices
- Batch generate audio from text files
- Create and manage multi-script projects with speaker assignments
- Export in WAV, MP3, AAC with professional mastering profiles
- Manage pronunciation dictionaries with CSV import/export
- Generate silence files for pacing and dramatic pauses

## Agent Rules

- Always run `vois-cli status` before issuing generation or project commands.
- Use `--format json` when another tool or agent needs to parse output.
- Use the exact voice IDs returned by `vois-cli voice list`; library voices use `category_slug/voice_slug`, cloned voices use `cloned_<slug>`, and designed voices use `designed_<slug>`.
- Use `vois-cli voice list --source all --format json` when selecting voices for a project. JSON output includes the full metadata agents need for casting, not just the short table columns.
- Use `vois-cli voice list --source all` or separate `clone-list` / `design-list` calls before assigning speakers so saved user voices are not missed.
- Pick the engine deliberately. Do not assume the app's visible engine is the one used by a command; pass `--engine omni`, `--engine standard`, `--engine multilingual`, or `--engine fast` when it matters.
- For CLI scripts, write model-native paralinguistic tags. The desktop editor may show friendlier labels, but direct CLI text should use the native tags documented below.
- Respect plan gates. Free is a 7-day trial; export after trial requires remaining export credits. Subscriber keeps the classic paid workflow, but Omni and Voice Design require Pro or Founder Pro.

## License and Plan Rules

Vois 2.0 separates billing plan from feature entitlement.

| Label | Billing / access | CLI behavior |
|-------|------------------|--------------|
| Free | 7-day trial with limited generation. After expiry, access continues only while export credits remain. | Fast, Expressive, and Multilingual trial use; no cloning, no export without credits, no Omni, no Voice Design |
| Subscriber | Existing paid plan: $29/month or $192/year. | Unlimited classic workflow, export and cloning enabled, Omni and Voice Design locked |
| Pro | $49/month or $264/year. | Includes Subscriber features plus Omni, 600+ languages, and Voice Design |
| Founder Pro | Existing Subscriber billing with Pro entitlement for eligible paid customers. | Display label is Founder Pro; feature gates are Pro |

When a command is gated, the desktop app returns a clear error such as “Omni is available on Vois Pro” or “Voice Design is available on Vois Pro.” Do not retry with the same plan; switch to a non-Pro engine or direct the user to upgrade.

## Voice Metadata for Agents

Use JSON output when choosing voices. The CLI returns:

| Field | Meaning |
|-------|---------|
| `id` | Pass this exact value to `--voice` or speaker assignments |
| `name` | User-facing voice name |
| `source` | `library`, `builtin`, `cloned`, or `designed` |
| `category` / `category_name` | Library category slug and display name |
| `gender` | Voice gender label when known |
| `description` | Short user-facing voice description |
| `personality` | Casting summary or design prompt for the voice |
| `voice_design_prompt` | Original production prompt for built-in library voices |
| `sample_speech_prompt` | Text used to create or evaluate the reference voice |
| `reference_text` | Transcript that should travel with the reference voice |
| `supported_engines` | Machine-readable engine support array |
| `avatar_index` | Avatar slot used by the desktop voice library |

For casting decisions, prefer `personality`, `description`, `category_name`, and `sample_speech_prompt`. When generating with saved user voices, use `cloned_<slug>` or `designed_<slug>` exactly as returned. `--engine omni` is accepted as the public CLI name and maps to the Omni engine support field internally.

## Installation

The CLI ships inside the Vois desktop app installer. No separate download needed.

### macOS (Apple Silicon)

```bash
sudo ln -sf "/Applications/Vois.app/Contents/MacOS/vois-cli-aarch64-apple-darwin" /usr/local/bin/vois-cli
```

### Windows 10/11 (64-bit)

The binary is at `%LOCALAPPDATA%\Vois\vois-cli-x86_64-pc-windows-msvc.exe`. Add to PATH or create an alias:

```powershell
New-Alias -Name vois-cli -Value "$env:LOCALAPPDATA\Vois\vois-cli-x86_64-pc-windows-msvc.exe"
```

### Build from Source (development only)

```bash
cd src-tauri/vois-cli && cargo build --release
# Binary at: src-tauri/vois-cli/target/release/vois-cli
```

### Supported Platforms

| Platform | Architecture | Binary Name |
|----------|-------------|-------------|
| macOS | Apple Silicon (ARM64) | `vois-cli-aarch64-apple-darwin` |
| Windows | 64-bit (x86_64) | `vois-cli-x86_64-pc-windows-msvc.exe` |

## Prerequisites

1. **Vois app must be running.** The CLI is a remote control, not a standalone tool. It communicates with the desktop app via IPC (Unix socket on macOS, named pipe on Windows).
2. **vois-cli in PATH.** Symlink from the app bundle or build from source (see Installation).
3. **Licensed copy of Vois.** Voice cloning requires a subscription. Exports require a subscription or export credits.

Check status:

```bash
vois-cli status
```

Expected output:

```
Vois Status
----------------------------------------
  Status: running
  Version: 1.6.8
  License: Valid
  TTS Engine: omni
```

## Quick Start

```bash
# 1. Check Vois is running
vois-cli status

# 2. Generate speech
vois-cli tts generate \
  --text "Welcome to my podcast." \
  --voice narrators_ai_voices/morgan_vale \
  --output welcome.wav

# 3. Export to MP3 with podcast mastering
vois-cli export with-profile \
  --input welcome.wav \
  --output welcome.mp3 \
  --profile apple_podcasts
```

## TTS Engine Management

Vois has four TTS engines. The CLI can switch between them and download models on demand.

| Engine | CLI name | Languages | Tags | Voice creation | Best use |
|--------|----------|-----------|------|----------------|----------|
| Fast | `fast` | English only | None | No cloning/design | Quick previews and simple English |
| Expressive | `standard` or `expressive` | English | 9 native vocal reaction tags | Cloned/library voices | Production English with stable cloning |
| Multilingual (legacy) | `multilingual` | 23 major languages | Tags are stripped | Legacy multilingual projects |
| Omni | `omni` | 646 languages | 14 Omni-native tags | Cloned voices, designed voices, voice design instruct | Pro-only broad language coverage, voice design, Omni tags |

```bash
# List engines and download status
vois-cli model list

# Switch engine
vois-cli model switch --engine omni

# macOS/Windows provider and precision controls
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

# Download a model (fast is bundled, others downloaded on first use)
vois-cli model download --model omni
```

Accepted providers: `auto`, `coreml`, `directml`, `cpu`, `cuda`. Accepted quant profiles: `auto`, `fp16`, `fp32`. The deprecated `q4` / `q4f16` options are rejected.

## Model-Specific Script Rules

**Fast**: English only. Do not include paralinguistic tags; unsupported tags are stripped or ignored.

**Expressive**: English. Supports exactly these native tags: `[laugh]`, `[chuckle]`, `[gasp]`, `[sigh]`, `[groan]`, `[cough]`, `[clear throat]`, `[sniff]`, `[shush]`.

**Multilingual (legacy)**: 23-language legacy engine. Do not include paralinguistic tags; unsupported tags are stripped before generation.

**Omni**: Pro-only 646-language engine. Supports these native tags: `[laughter]`, `[sigh]`, `[sniff]`, `[confirmation-en]`, `[question-en]`, `[question-ah]`, `[question-oh]`, `[question-ei]`, `[question-yi]`, `[surprise-ah]`, `[surprise-oh]`, `[surprise-wa]`, `[surprise-yo]`, `[dissatisfaction-hnn]`.

Avoid unsupported bracket tags such as `[happy]`, `[sad]`, `[excited]`, `[nervous]`, `[warm]`, or `[dramatic]`. Use prose for performance direction, or `--instruct` (expressive engine) for emotion text.

### Omni Voice Design Vocabulary

`--voice-design` and `--voice-design-instruct` do NOT accept free-text descriptions. They take a comma-separated list of attributes from a fixed vocabulary, at most one per category:

| Category | Valid values |
|----------|-------------|
| 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` |

Example: `"female, middle-aged, low pitch, british accent"`. A free-text prompt like "A warm, friendly female voice" fails with an `InstructInvalid` error. Use English commas with a space (`, `) between items.

## Core Workflows

### Generate Speech

```bash
# Basic generation
vois-cli tts generate --text "Hello, world!" --voice narrators_ai_voices/morgan_vale --output hello.wav

# With speed and engine override
vois-cli tts generate --text "Bonjour!" --voice narrators_ai_voices/morgan_vale \
  --engine multilingual --language French --output french.wav --speed 0.9

# With style instruction (expressive engine)
vois-cli tts generate --text "Breaking news!" --voice narrators_ai_voices/morgan_vale \
  --output news.wav --instruct "Speak with urgency"

# With Omni engine (646 languages, Omni-native paralinguistic tags)
vois-cli tts generate --text "Hello [laughter] that was great!" \
  --voice narrators_ai_voices/morgan_vale \
  --engine omni --output omni.wav \
  --diffusion-steps 32 --guidance-scale 2.0

# With Omni voice design instruct (comma-separated attributes, see vocabulary above)
vois-cli tts generate --text "Welcome to the show." \
  --voice voice_design \
  --engine omni --output designed.wav \
  --voice-design-instruct "male, middle-aged, low pitch, british accent"

# Generate from voice design attributes (no preset voice needed)
vois-cli tts generate-voice-design \
  --text "Hello, welcome to the show" \
  --voice-design "female, young adult, moderate pitch, american accent" \
  --output custom.wav \
  --diffusion-steps 32 --guidance-scale 2.0

# Generate silence for pauses and transitions
vois-cli tts silence --duration 500 --output pause.wav
```

### Batch Generation

```bash
# One line per audio file
vois-cli tts batch-file \
  --input lines.txt \
  --output-dir ./audio/ \
  --voice narrators_ai_voices/morgan_vale \
  --prefix "line" \
  --skip-existing

# Batch with Omni explicitly
vois-cli tts batch-file \
  --input lines.txt \
  --output-dir ./audio/ \
  --voice narrators_ai_voices/morgan_vale \
  --engine omni \
  --language English \
  --diffusion-steps 32 \
  --guidance-scale 2.0 \
  --skip-existing
```

### Voice Management

```bash
# List all voices, including library, builtin, cloned, and designed
vois-cli voice list --source all

# List all 100+ production library voices
vois-cli voice list --source library

# Filter by gender or category
vois-cli voice list --gender female
vois-cli voice list --category narrators_ai_voices
vois-cli voice list --engine omni

# Search voices
vois-cli voice search --query "narrator"

# Clone a voice (requires subscription + consent)
vois-cli voice clone \
  --name "Narrator Voice" \
  --audio /path/to/sample.wav \
  --consent-confirmed

# List cloned voices
vois-cli voice clone-list

# List designed Omni voices
vois-cli voice design-list

# Include cloned or designed voices in general voice listing
vois-cli voice list --source cloned
vois-cli voice list --source designed
```

Voice IDs use the format `category_slug/voice_slug` (e.g., `narrators_ai_voices/morgan_vale`).
Cloned and designed voices use the generated IDs shown by `voice list`, for example `cloned_my_voice` or `designed_warm_narrator`.
Designed voices are Omni-oriented reference voices. They can appear in voice selectors and CLI listings after save; use their `designed_<slug>` ID with `--engine omni` for best results.

### Project Workflow

```bash
# Create project
PROJECT_ID=$(vois-cli project create --name "Tech Talk" --format json | jq -r '.id')

# Create script with dialogue
SCRIPT_ID=$(vois-cli script create --project $PROJECT_ID --title "Episode 1" --format json | jq -r '.id')
vois-cli script update --id $SCRIPT_ID --content "[Host]: Welcome to Tech Talk!
[Guest]: Thanks for having me."

# Assign speakers
vois-cli speaker create --script $SCRIPT_ID --name "Host" --voice narrators_ai_voices/morgan_vale
vois-cli speaker create --script $SCRIPT_ID --name "Guest" --voice hosts_ai_voices/alex_bright

# Generate all segments
vois-cli script generate --id $SCRIPT_ID --voice narrators_ai_voices/morgan_vale

# Compile to final audio
vois-cli export compile-script --script $SCRIPT_ID
```

### Export with Mastering

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

# Available profiles
vois-cli export profiles
```

| Profile ID | Platform | Format | LUFS |
|------------|----------|--------|------|
| `acx_audiobook` | ACX/Audible | MP3 192kbps | -20 |
| `apple_podcasts` | Apple Podcasts | AAC 128kbps | -16 |
| `spotify_podcasts` | Spotify | MP3 128kbps | -14 |
| `youtube_video` | YouTube | AAC 256kbps | -14 |
| `generic_high_quality` | Any | WAV | -16 |

### Pronunciation Dictionary

```bash
# Add custom pronunciation
vois-cli pronunciation add --word "nginx" --pronunciation "engine-x"

# Import from CSV (format: word,pronunciation,context)
vois-cli pronunciation import --file tech_terms.csv --scope global

# Export to CSV
vois-cli pronunciation export --output pronunciations.csv
```

## Output Formats

Control output format with `--format`:

| Format | Flag | Use Case |
|--------|------|----------|
| Human | `--format human` (default) | Interactive terminal use |
| JSON | `--format json` | Scripting, AI agent parsing |
| Quiet | `--format quiet` | Pipelines (minimal output) |

```bash
# JSON for scripting
vois-cli voice list --format json | jq '.[0].id'

# Quiet for pipelines
OUTPUT=$(vois-cli tts generate --text "Hello" --voice narrators_ai_voices/morgan_vale --output hello.wav --format quiet)
```

## Error Handling

| Exit Code | Meaning |
|-----------|---------|
| 0 | Success |
| 1 | General error |
| 2 | App not running |
| 3 | Invalid arguments |
| 4 | Resource not found |
| 5 | Generation failed |
| 6 | Export failed |
| 7 | License required |

```bash
if ! vois-cli status > /dev/null 2>&1; then
  echo "Start Vois first"
  exit 1
fi
```

## Provenance and Audit

- All TTS generations using cloned voices are logged locally with timestamps and anonymized hashes
- Exported audio contains embedded provenance metadata identifying it as AI-generated
- Cloned voice exports send a small receipt to the license server (no audio or text content)
- The `--consent-confirmed` flag is required for `voice clone`

## Limitations

- **Vois must be running.** The CLI can't start the app or load models directly.
- **Local only.** Works on the same machine where Vois is installed.
- **License or credits required.** Free is a 7-day trial; export after trial needs remaining export credits or a paid plan.
- **Voice cloning requires a paid plan.** Free tier cannot clone voices.
- **Omni and Voice Design require Pro.** Subscriber can keep using Fast, Expressive, and Multilingual (legacy), but Pro/Founder Pro is required for `--engine omni`, `tts generate-voice-design`, and saved designed voice creation.
- **One generation at a time.** TTS is single-threaded; operations are sequential.

## Command Summary

| Command Group | Subcommands |
|---------------|-------------|
| `status` | Check app status |
| `model` | list, status, download, switch |
| `tts` | generate, silence, batch-file, generate-voice-design, preview, status, cancel |
| `voice` | list, get, search, clone-list, design-list, clone, clone-delete, design-delete |
| `project` | create, list, get, update, delete |
| `script` | create, list, get, update, delete, reorder, generate, segments |
| `speaker` | create, list, update, delete |
| `export` | audio, mp3, with-profile, compile-script, compile-project, profiles, profile |
| `mastering` | get, set, reset |
| `pronunciation` | list, add, update, delete, delete-scope, search, import, export |
| `calendar` | create, list, get, update, schedule, delete |
| `platform` | list, get, disconnect |
| `rss` | generate |
| `timeline` | get, save, delete |
| `settings` | get-consent, set-consent |

## References

For full command documentation with every flag and argument:

- [Command Reference](references/command-reference.md)
- [Script Syntax and Pacing](references/script-syntax.md)

## Support

- Email: support@vois.so
- Website: https://vois.so
- Pricing: https://vois.so/pricing