Generate
Read text from an argument or stdin. Choose voice, speed, language, model variant, output path, and WAV, MP3, Opus, or M4A.
Kokoro CLI
A self-contained, offline-first text-to-speech product for people and agents. Generate a recording, validate its metadata, optionally play it, and return a concrete file—not a promise.
Published on PyPI · 0.3.0
Verified TTS core preserved
Kokoro-82M via ONNX
24 kHz mono
Localhost only
Current capabilities
Play
Optionally play completed audio through afplay or ffplay. Success is reported only after the player exits successfully.
Automate
Emit a proof-carrying JSON receipt with an absolute path, audio metadata, backend, and playback state. A localhost OpenAI-shaped HTTP endpoint supports long-lived agent workflows.
Inspect
List installed voices. Model artifacts are downloaded under a process lock, written atomically, and checked against pinned sizes and SHA-256 hashes.
Diagnose
kokoro doctor is the product-health contract for runtime, model, codecs, playback, writable output, and optional service state.
Compose
Public CLI and HTTP contracts are deliberately small so other products can create speech without importing Kokoro internals.
Commands
# Install the stable release globally from PyPI
uv tool install kokoro-cli
# Prepare and inspect
kokoro setup
kokoro doctor
kokoro voices
# Generate locally or through a healthy optional service
kokoro speak "The build is ready." --format mp3 --json
printf '%s' "$VISIBLE_TEXT" | kokoro speak --play --json
kokoro speak "Strict local run." --service off --json
kokoro speak "Strict service run." --service required --json
# Long-lived localhost service
kokoro serve
curl http://127.0.0.1:8765/healthThe installed kokoro command works from any directory. Contributors can still use ./kokoro inside a checkout.
Execution architecture
Human or agent
Provides only visible, user-facing text to the CLI or HTTP contract.
Transport
CLI checks the optional localhost service, with explicit required/off modes and embedded fallback.
Speech core
Serialized Kokoro ONNX inference, atomic encoding, file/HTTP delivery, optional playback.
Public contracts
| Surface | Contract | Guarantee |
|---|---|---|
| CLI result | Final stdout line is JSON with absolute path, format, voice, speed, timings, backend, and played. | Non-zero exit on generation, validation, required-service, or playback failure. Auto fallback is explicit in JSON. |
| Health | GET /health | Reports service identity, version, active model variant, and readiness. |
| Speech | POST /v1/audio/speech | Accepts input, voice, speed, response_format, plus local lang and play. |
| Voices | GET /voices | Returns voices exposed by the loaded model bundle. |
Verified behavior
Automated checks
31 tests pass across atomic audio and service output, persistent voice and speed defaults, model selection, payload validation, localhost binding, live health and speech requests, CLI naming, service fallback, required-service failure, and playback reporting. CI runs Ruff and pytest on macOS and Linux with Python 3.11 and 3.13, then builds the wheel and source distribution.
Real product checks
The public kokoro-cli==0.3.0 package was installed cache-free from PyPI into a fresh isolated tool environment. A fresh model setup downloaded and verified the pinned int8 assets, kokoro doctor --json passed every required check, and embedded inference produced a valid mono 24 kHz WAV using saved speech defaults.
Boundaries and planned work
Deliberate boundaries
No remote binding, authentication layer, cloud TTS, speech-to-text, hidden reasoning narration, or HTML Drop implementation. This repository only exposes contracts another product can compose with.
Planned, not current
Streaming synthesis, sentence chunking for very long narration, richer install/uninstall helpers, additional platforms, and measured model-quality or latency comparisons.