---
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: "1.4.2"
---

# 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 63 library voices or voice design prompts
- Switch between 3 TTS engines: Fast (English), Expressive (English), Multilingual (23 languages)
- Clone voices from audio samples (5-60 second reference)
- 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

## 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
```

### macOS (Intel)

```bash
sudo ln -sf "/Applications/Vois.app/Contents/MacOS/vois-cli-x86_64-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` |
| macOS | Intel (x86_64) | `vois-cli-x86_64-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 is running
Version: 1.4.1
License: Subscriber
Engine: standard
```

## 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 three TTS engines. The CLI can switch between them and download models on demand.

| Engine | CLI Name | Languages | Speed | Use Case |
|--------|----------|-----------|-------|----------|
| Fast | `fast` | English only | 3-6x real-time | Quick previews, English content |
| Expressive | `standard` | Expressive English | 2x real-time | Voice cloning, production audio |
| Multilingual | `multilingual` | 23 languages | 1x real-time | Non-English, best quality |

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

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

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

## 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"

# Generate from a voice design prompt (no preset voice needed)
vois-cli tts generate-voice-design \
  --text "Hello, welcome to the show" \
  --voice-design "A warm, friendly female voice with a slight Southern accent" \
  --output custom.wav

# 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
```

### Voice Management

```bash
# List all 63 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

# 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
```

Voice IDs use the format `category_slug/voice_slug` (e.g., `narrators_ai_voices/morgan_vale`).

### 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.** Export needs a subscription or export credits (purchase at vois.so/pricing).
- **Voice cloning requires subscription.** Free tier can't clone voices.
- **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, clone, clone-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