Skip to content

Latest commit

 

History

History

tts-cli

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
skill
skill
 
 
README.md
README.md
 
 
index.js
index.js
 
 
package.json
package.json
 
 

README.md

@fionoble/tts-cli

A CLI tool for generating speech using OpenAI's TTS API. Comes with a Claude Code skill for seamless AI-assisted speech generation.

Install

npm install -g @fionoble/tts-cli

Or use without installing:

npx @fionoble/tts-cli -t "Hello world" -o hello.mp3

Prerequisites

export OPENAI_API_KEY="sk-..."

Environment Variables

Variable Description
OPENAI_API_KEY Required. Your OpenAI API key.
OPENAI_BASE_URL Custom API base URL (for proxies).
TTS_VOICE Default voice. Overridden by -v flag.
TTS_MODEL Default model. Overridden by -m flag.
TTS_FORMAT Default output format. Overridden by --format flag.
TTS_SPEED Default speed. Overridden by --speed flag.

Example — set your preferred defaults in your shell profile:

export TTS_VOICE="nova"
export TTS_MODEL="tts-1-hd"
export TTS_FORMAT="wav"

Then just run tts -t "Hello" and it uses those defaults. Pass a flag to override for a single run.

CLI Usage

tts [options]

Options

Flag Description Default
-t, --text <text> Text to speak (required unless -f) -
-f, --file <path> Read text from a file -
-o, --output <path> Output file path speech-<timestamp>.mp3
-v, --voice <voice> Voice (see below) alloy
-m, --model <model> gpt-4o-mini-tts, tts-1, tts-1-hd gpt-4o-mini-tts
--format <fmt> mp3, opus, aac, flac, wav, pcm mp3
--speed <n> Speed 0.25–4.0 1.0
--instructions <text> Voice style instructions (gpt-4o-mini-tts only) -
--install-skill Install the Claude Code skill -
--uninstall-skill Remove the Claude Code skill -

Voices

alloy, ash, ballad, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse, cedar

Examples

Generate speech:

tts -t "Hello world" -v nova -o hello.mp3

Read a file aloud:

tts -f article.txt -v sage --format wav -o article.wav

Use voice style instructions:

tts -t "Breaking news today" --instructions "Speak like a news anchor, clear and authoritative" -o news.mp3

Claude Code Skill

Install the skill so Claude Code can generate speech for you:

tts --install-skill
# or
npx @fionoble/tts-cli --install-skill

Once installed, the /tts skill is available in Claude Code. You can either:

  • Invoke it directly: /tts say hello world
  • Or just ask naturally: "read this text aloud" or "generate speech for this paragraph"

To remove the skill:

tts --uninstall-skill

License

ISC