Utter

A Text-to-Speech CLI using ElevenLabs, designed for humans and AI agents.

Give your AI agent a voice. Utter converts text to speech from the terminal — use it manually, let your agent call it as a tool, or wire it up as a hook so every response is spoken aloud automatically.

Installation

npm install -g utter-cli

Or install from source:

git clone https://github.com/gztomas/utter.git
cd utter
npm install && npm run build
npm install -g .

Setup

Get your API key from ElevenLabs, then:

utter init

Or set it via environment variable:

export ELEVENLABS_API_KEY=your_key_here

Usage

Speak text aloud

utter me "Hello, world!"

Speak from a file

utter me --file article.txt

Save to MP3

utter to hello.mp3 "Hello"

Use a specific voice

utter me --voice Rachel "Hello there!"

Pipe text

echo "Hello from stdin" | utter me
cat document.txt | utter me

List available voices

utter voices

Set default voice

utter voices --set-default <voice-id>

Options

utter me

| Option | Description | |--------|-------------| | -f, --file <path> | Read text from file | | -v, --voice <voice> | Voice ID or name | | -m, --model <model> | Model ID (default: eleven_multilingual_v2) | | -s, --stream | Stream audio chunks as they're ready | | -q, --quiet | Suppress progress output |

utter to <file>

| Option | Description | |--------|-------------| | -f, --file <path> | Read text from file | | -v, --voice <voice> | Voice ID or name | | -m, --model <model> | Model ID (default: eleven_multilingual_v2) | | -q, --quiet | Suppress progress output |

utter voices

| Option | Description | |--------|-------------| | --json | Output as JSON | | --set-default <id> | Set the default voice |

Use with AI agents

There are two ways to give your AI agent a voice with Utter:

1. Tell your agent to use it

Add an instruction to your agent's system prompt (or a CLAUDE.md / rules file) telling it to speak its replies:

Every time you reply, run utter me --quiet "<your reply>" so the user hears it.

The agent will call the command as a tool on each response.

2. Set up a hook (automatic)

With Claude Code, you can add a hook that automatically speaks every response — no agent instructions needed. Add this to your .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "utter me --quiet \"$CLAUDE_TOOL_RESULT\""
          }
        ]
      }
    ]
  }
}

Tips for agent usage

• Use --quiet to suppress progress output and keep the agent's context clean
• Use --json with utter voices for machine-readable voice lists
• Pipe text via stdin: echo "Hello" | utter me --quiet
• Exit codes: 0 = success, 1 = error

Configuration

Configuration is stored in ~/.utter/config.json. You can also use environment variables:

| Variable | Description | |----------|-------------| | ELEVENLABS_API_KEY | Your ElevenLabs API key | | UTTER_DEFAULT_VOICE | Default voice ID |

License

MIT