Skip to main content
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.

​
Quick start

1

Install

pip install "supertone-cli[stream]"
Requires Python 3.12+. The [stream] extra adds real-time playback.
2

Add your API key

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
3

Hear it

supertone tts "My first words from the terminal." \
  --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
If you hear audio, you’re all set. ✅
Building into application code instead? Use the Python or TypeScript SDK. For AI agents, see MCP.

​
Installation

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

​
Authenticate

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
Save defaults once and omit the matching flags on every call:
Config keyUsed when omittedDefault
api_keyalways—
default_voice--voice not passed—
default_model--model not passedsona_speech_2
default_lang--lang not passedko
supertone config set default_voice 20160a4c5ba38967330c84
supertone config set default_lang en

​
Synthesize speech

# 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

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. 
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

Drop your .txt files in one directory and synthesize them all at once:
supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
Pipe any command’s text straight into real-time speech:
my-llm "Summarize today's headlines" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
--format json makes any read command scriptable:
supertone voices list --type custom --format json | jq '.[].name'
Loop over inputs and sum predicted durations before spending credits:
for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done

​
Reference

sona_speech_1, sona_speech_2, sona_speech_2_flash, sona_speech_2t, supertonic_api_1, supertonic_api_3. See Models for capabilities and trade-offs.
CodeMeaning
0Success
1API error
2Authentication error
3Input validation error
130Interrupted (Ctrl-C)

​
Troubleshooting

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.
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.
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.
Synthesis stops when your balance runs out. Check it with supertone usage balance and top up in the Developer Console.

MCP

Let AI agents call Supertone through the Model Context Protocol.

Python SDK

The same API for application code.