> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/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

<Steps>
  <Step title="Install">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```

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

  <Step title="Add your API key">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Step>

  <Step title="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. ✅
  </Step>
</Steps>

<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).
</Note>

## Installation

<Tabs>
  <Tab title="pip">
    ```bash theme={"dark"}
    pip install supertone-cli
    ```
  </Tab>

  <Tab title="with streaming">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```
  </Tab>
</Tabs>

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

## Authenticate

<Tabs>
  <Tab title="Environment variable">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Tab>

  <Tab title="Config file">
    ```bash theme={"dark"}
    supertone config init             # interactive setup
    supertone config set api_key Kp9mZ3xQ7v...
    ```

    Stored at `~/.config/supertone/config.toml`.
  </Tab>
</Tabs>

<Accordion title="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
  ```
</Accordion>

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

<AccordionGroup>
  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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'
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

## Reference

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Exit codes">
    | Code  | Meaning                |
    | ----- | ---------------------- |
    | `0`   | Success                |
    | `1`   | API error              |
    | `2`   | Authentication error   |
    | `3`   | Input validation error |
    | `130` | Interrupted (Ctrl-C)   |
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="--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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="MCP" icon="robot" href="/en/docs/developer-tools/mcp">
    Let AI agents call Supertone through the Model Context Protocol.
  </Card>

  <Card title="Python SDK" icon="python" href="/en/docs/developer-tools/python">
    The same API for application code.
  </Card>
</CardGroup>