> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Generate, stream, batch, and manage voices from your terminal with the Supertone CLI — quickstart, commands, recipes, and troubleshooting.

Convert text to speech right from your terminal — no code required. The Supertone CLI synthesizes from strings, files, or stdin, streams to your speakers in real time, batches whole directories, and manages voices, usage, and credits.

Source: [supertone-inc/supertone-cli](https://github.com/supertone-inc/supertone-cli).

## Quick start

**1. Install**

```bash theme={"dark"}
pip install "supertone-cli[stream]"
```

Requires Python 3.12+. The `[stream]` extra adds real-time playback.

**2. Add your API key**

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

**3. Hear it**

```bash theme={"dark"}
supertone tts "My first words from the terminal." \
  --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
```

If you hear audio, you're all set. ✅

> [!NOTE]
>
> Building into application code instead? Use the [Python](/en/docs/developer-tools/python) or [TypeScript](/en/docs/developer-tools/typescript) SDK. For AI agents, see [MCP](/en/docs/developer-tools/mcp).

## Installation

**pip**

```bash theme={"dark"}
pip install supertone-cli
```

**with streaming**

```bash theme={"dark"}
pip install "supertone-cli[stream]"
```

Requires Python 3.12+. The `[stream]` extra enables real-time playback to your system speakers via `--stream`.

## Authenticate

**Environment variable**

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

**Config file**

```bash theme={"dark"}
supertone config init             # interactive setup
supertone config set api_key Kp9mZ3xQ7v...
```

Stored at `~/.config/supertone/config.toml`.

> **Set defaults to type less**
>
> Save defaults once and omit the matching flags on every call:
>
> | Config key | Used when omitted | Default |
> | - | - | - |
> | `api_key` | always | — |
> | `default_voice` | `--voice` not passed | — |
> | `default_model` | `--model` not passed | `sona_speech_2` |
> | `default_lang` | `--lang` not passed | `ko` |
>
> ```bash theme={"dark"}
> supertone config set default_voice 20160a4c5ba38967330c84
> supertone config set default_lang en
> ```

## Synthesize speech

```bash theme={"dark"}
# From a string
supertone tts "Hello from the terminal." --voice VOICE_ID -o output.wav

# From a file
supertone tts -i input.txt -v VOICE_ID -o output.wav

# From stdin (pipe-friendly)
echo "Piped text." | supertone tts -v VOICE_ID -o output.wav

# Play in real time instead of saving (needs the [stream] extra)
supertone tts "This plays back live." -v VOICE_ID -m sona_speech_1 --stream

# Tune format and voice settings
supertone tts "Slower and lower." -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# Batch a whole folder — one audio file per input
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID
```

## Manage voices

```bash theme={"dark"}
supertone voices list                                  # preset voices provided by Supertone
supertone voices list --type custom                    # only your cloned voices
supertone voices search --lang en --gender female      # filter presets
supertone voices get VOICE_ID                         # full detail
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yes skips confirmation
```

## Predict duration & track usage

`tts-predict` estimates duration and credit cost **without** spending credits — handy before a large batch.

```bash theme={"dark"}
supertone tts-predict "How long will this be?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30
```

## Recipes

> **Narrate a folder of scripts**
>
> Drop your `.txt` files in one directory and synthesize them all at once:
>
> ```bash theme={"dark"}
> supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
> ```

> **Speak an LLM's output live**
>
> Pipe any command's text straight into real-time speech:
>
> ```bash theme={"dark"}
> my-llm "Summarize today's headlines" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
> ```

> **Find your custom voices with jq**
>
> `--format json` makes any read command scriptable:
>
> ```bash theme={"dark"}
> supertone voices list --type custom --format json | jq '.[].name'
> ```

> **Estimate cost before a batch**
>
> Loop over inputs and sum predicted durations before spending credits:
>
> ```bash theme={"dark"}
> for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done
> ```

## Reference

> **Supported models**
>
> `sona_speech_1`, `sona_speech_2`, `sona_speech_2_flash`, `sona_speech_2t`, `supertonic_api_1`, `supertonic_api_3`. See [Models](/en/docs/core-concepts/models) for capabilities and trade-offs.

> **Exit codes**
>
> | Code | Meaning |
> | - | - |
> | `0` | Success |
> | `1` | API error |
> | `2` | Authentication error |
> | `3` | Input validation error |
> | `130` | Interrupted (Ctrl-C) |

## Troubleshooting

> **command not found: supertone**
>
> The install directory isn't on your `PATH`, or you installed inside a virtual environment that isn't active. Re-activate the venv, or reinstall with `pip install --user supertone-cli` and ensure the user scripts directory is on your `PATH`.

> **Authentication error (exit code 2)**
>
> Your API key is missing or invalid. Check `echo $SUPERTONE_API_KEY`, or run `supertone config set api_key your-api-key`. Get a key from the [Developer Console](https://console.supertoneapi.com).

> **--stream produces no audio**
>
> Real-time playback requires the streaming extra (`pip install "supertone-cli[stream]"`) **and** the `sona_speech_1` model — pass `-m sona_speech_1`. Other models return *"Streaming requires sona\_speech\_1"*; to use them, save to a file with `-o output.wav` instead.

> **Out of credits (402)**
>
> Synthesis stops when your balance runs out. Check it with `supertone usage balance` and top up in the [Developer Console](https://console.supertoneapi.com).

## Related

> **[MCP](/en/docs/developer-tools/mcp)**
>
> Let AI agents call Supertone through the Model Context Protocol.

> **[Python SDK](/en/docs/developer-tools/python)**
>
> The same API for application code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.