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.
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 globally from GitHub
uv tool install "git+https://github.com/yoav0gal/kokoro-cli.git"
# 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, 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
19 tests pass across atomic WAV/service output, model selection, payload validation, localhost binding, live health and speech requests, CLI naming, auto fallback, required-service failure, and playback reporting. Ruff lint and formatting plus Python compilation also pass.
Real product checks
A built wheel installed as kokoro 0.2.0 in an isolated Python 3.11 environment. Embedded synthesis produced and played a 3.968 s MP3; live required-service synthesis produced a 2.347 s WAV; both probed as mono 24 kHz. A stopped service triggered a real embedded fallback. The receipt-based Agent Skill passes the official validator and an independent forward test produced a valid 2.368 s MP3 without falsely claiming playback.
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.