Skip to main content

TTS CLI: Convert Text to Audio in One Command

· 4 min read
TTS Buddy Team
TTS Buddy Team

TTSBuddy CLI is a command-line tool for turning text into MP3 audio from your terminal. It works with inline text, local files, Markdown notes, stdin, pipes, and automation scripts.

The CLI is built for people who want audio without opening the web dashboard: students turning notes into study audio, developers wiring TTS into scripts, and AI-agent workflows that produce long text summaries that are easier to listen to than read.

What the CLI Supports​

TTSBuddy CLI uses the TTSBuddy API with API-key authentication. It supports:

  • Inline text: ttsbuddy speak "Hello, world!"
  • File input: ttsbuddy speak -f article.md
  • Stdin and pipes: cat notes.txt | ttsbuddy speak -
  • MP3 output with -o
  • Raw MP3 bytes to stdout with -o -
  • Audio URL output with --no-download
  • JSON output with --json
  • Voice selection with -v
  • Supertonic language selection with -l
  • Speed control from 0.5 to 1.5
  • 30+ language modes using Fast voices and native voice groups

Markdown files (.md and .markdown) are preprocessed before generation so headings, formatting markers, link URLs, images, and code blocks do not get narrated awkwardly. Use --raw when you want to send the file exactly as-is.

Install​

Install with Homebrew:

brew install ngelik/tap/ttsbuddy

Or install with Go:

go install github.com/ngelik/ttsbuddy-cli@latest

You can also download a prebuilt binary from the GitHub Releases page and place it in your $PATH.

Check the installed version:

ttsbuddy version

Set an API Key​

Create an API key in TTSBuddy, then store it locally:

ttsbuddy config set key ttsb_your_key_here

The CLI stores configuration in ~/.ttsbuddy/config.json. You can also use the TTSBUDDY_API_KEY environment variable. Prefer config or environment variables over the -k flag so API keys do not end up in shell history.

Basic Commands​

Convert inline text:

ttsbuddy speak "Hello from the terminal."

Save to a specific file:

ttsbuddy speak "Make this an MP3." -o output.mp3

Convert a Markdown file:

ttsbuddy speak -f study-notes.md -o study-notes.mp3

Pipe text from another tool:

cat research-summary.txt | ttsbuddy speak - -o summary.mp3

Return a JSON response for automation:

ttsbuddy speak "Generate an audio URL." --no-download --json

Play generated audio directly on macOS:

ttsbuddy speak "Quick audio check." -o - | afplay -

Voice and Language Selection​

List available voices:

ttsbuddy voices

Use Fast voices for low-latency CLI and automation workflows:

ttsbuddy speak "Bonjour depuis TTSBuddy." -v st_m1 -l fr -o french.mp3
ttsbuddy speak "안녕하세요." -v st_f2 -l ko -o korean.mp3

Fast voice IDs stay stable across language modes. For example, st_m1 can be used with -l en, -l fr, -l de, -l ja, and other supported Supertonic language codes. The ttsbuddy voices command shows the language name, native display name, code, and type for each voice option.

Automation Examples​

Turn study notes into audio:

ttsbuddy speak -f study-notes.md -v st_m1 -l en -o study-notes.mp3

Practice a short Spanish phrase:

ttsbuddy speak "Repasa esta frase conmigo." -v st_f3 -l es -o spanish-practice.mp3

Pipe an AI-agent summary into Japanese audio:

cat agent-summary.txt | ttsbuddy speak - -v st_m2 -l ja -o summary-ja.mp3

Create a French walking brief at a custom speed:

ttsbuddy speak "Resume rapide pour marcher." -v st_f2 -l fr -s 1.1 -o walking-brief.mp3

Return a German audio URL as JSON:

ttsbuddy speak "Automatischer Audio-Link." -v st_m4 -l de --no-download --json

When to Use the CLI​

TTSBuddy CLI is useful when you want text-to-speech inside an existing workflow:

  • Convert study notes into audio before a commute.
  • Listen to long AI-generated summaries away from the screen.
  • Generate MP3 drafts from scripts or documentation.
  • Add TTS to shell scripts and agent pipelines.
  • Return machine-readable JSON for downstream automation.

For dashboard workflows, saved files, billing, and account settings, use the TTSBuddy web app. For scripts and agents, the CLI keeps the interface small and predictable.

FAQ​

Can TTSBuddy CLI run fully offline?​

No. The CLI is a thin client for the TTSBuddy API and requires an internet connection plus a valid API key.

What audio format does it create?​

The CLI downloads MP3 audio. It can save MP3 files, stream raw MP3 bytes to stdout with -o -, or return an audio URL with --no-download.

Can I use it in scripts or CI?​

Yes. Use stdin, explicit output paths, --quiet, --json, and --no-download for script-friendly workflows. For example:

ttsbuddy speak "Build summary is ready." --no-download --json

Where can I find the full command reference?​

See the CLI Tool docs for install steps, flags, output modes, configuration, exit codes, and troubleshooting.