New in Vocello 3.0
Command line and agents.
vocello brings the Mac app's features to the terminal: generate in all three modes, long-form and line by line included; manage saved voices and models; read and export History; read and change settings. It uses the app's models, saved voices and settings, so both see the same library.
Install the package
Vocello-macos26-cli.pkginstallsvocelloin/usr/local/lib/vocelloand links/usr/local/bin/vocelloand its zsh completion. It is signed with Developer ID and notarized, asks for an administrator password, and runs on Apple Silicon (arm64) Macs with macOS 26 or later.vocello --helpThe installer adds links only in folders that root alone can change. If your
/usr/local/binbelongs to your user, as some older Homebrew setups leave it, the command is installed but not linked there: run/usr/local/lib/vocello/vocelloor link it into your path yourself.Or copy the folder
Open Vocello-macos26-cli.dmg and copy the complete Vocello CLI folder to a folder you own, keeping its executable and resource bundles together, then run
vocelloby its full path. No administrator password is needed.Update
Vocello > Check for Updates updates only the app. To update the command line, install the newer
Vocello-macos26-cli.pkgfrom the releases page: it replaces the previous install. For a copied folder, replace it with the newer Vocello CLI folder.Uninstall
The package's uninstaller removes the command line and leaves your models, voices and History untouched.
sudo sh /usr/local/lib/vocello/uninstall.shIf users other than root can change
/usr/local/lib, the uninstaller removes nothing: it prints the commands that make that folder root's alone. Run them, then run the uninstaller again. If a tool you installed since then needs that folder to stay yours, remove/usr/local/lib/vocello,/usr/local/bin/vocelloand/usr/local/share/zsh/site-functions/_vocelloyourself, then runsudo pkgutil --forget com.qwenvoice.cli.
First commands
Model files are not bundled. Install one once, in the app or from the terminal, and both use it. These commands list the speakers and models, download the Built-in Voice Speed model (about 2 GB, once), and save a first take to your Desktop.
vocello speakers listvocello models listvocello models install pro_custom_speedvocello generate --mode custom --variant speed --text "The train left at dawn." --out ~/Desktop/hello.wavVoice Design and Voice Cloning each use their own model. vocello models install-recommended --plan lists the model each mode uses and its download size, and downloads nothing.
Built for scripts
--json and --ndjson give every command a stable machine contract: one envelope, typed error codes, documented exit statuses and progress events. Text output is for people and is not a contract. These commands pipe a script in for the JSON envelope, describe every command, option, error code and exit status, and send a JSON request on standard input; both takes use the Built-in Voice Speed model installed above.
echo "Hello there." | vocello generate --variant speed --text - --jsonvocello capabilities --jsonecho '{"mode":"custom","variant":"speed","text":"Good evening."}' | vocello run --request - --json| Exit | Category | Meaning |
|---|---|---|
| 0 | ok | Success. |
| 2 | usage | The invocation or its input was refused before any work. |
| 69 | precondition | A model is not installed, or speech recognition is unavailable. |
| 75 | transient | The engine or a store is busy, memory is short, or the network is unavailable: retry later. |
| 77 | permission | Voice-cloning consent is missing, or a path is not allowed. |
| 130 | cancelled | Interrupted by Control-C (SIGINT). |
For AI agents
vocello mcp serves Claude Code, Claude Desktop and other MCP clients over stdio. An agent can:
- List voices, models, speakers and languages
- Generate speech, with progress and cancellation
- Enroll and delete saved voices
- Read History and export takes
This adds Vocello to Claude Code for every project:
claude mcp add --scope user vocello -- /usr/local/bin/vocello mcpThe command names the installer package's link. With a copied folder, or when the installer added no link, use the path to your vocello executable instead: run mcp --print-config claude-code from that copy, for example /usr/local/lib/vocello/vocello mcp --print-config claude-code, and it prints the command with that copy's own path. --print-config claude-desktop prints the Claude Desktop setup the same way.
Limits to know
- Not in History yet
- Command-line takes are saved as files and do not appear in History yet; a 3.0 update adds that. Reading History from the command line needs the Mac app closed for now.
- Consent every time
- Cloning or saving a voice needs
--confirm-consenton each command, orconfirmConsentin each MCP request. It is never inherited from the app's Settings. - Files stay in Vocello
- The MCP server reads and writes audio only inside Vocello's output folder, unless you start it with
--allow-dirand name the folders it may use. - One engine on 8 GB
- On an 8 GB Mac, one engine runs at a time and a running Vocello app counts: a second is refused as busy (exit 75), and
--wait-for-enginewaits for the other to exit.
Local by design. Yours to keep.
Vocello 3.0.0 for macOS 26 and Apple Silicon, free and open source. Three ways in, one local engine.
- Download for Mac
Mac app
Open the DMG and drag Vocello to Applications. From 3.0 on, the app updates itself: choose Vocello > Check for Updates.
- Download the package
Command line
The installer package links
vocelloin /usr/local/bin and asks for an administrator password; install a newer package to update it. Or copy the Vocello CLI folder from the folder DMG. - Join on TestFlight
iPhone
The public TestFlight beta runs version 2.4. The iPhone app's 3.0 version, on the same engine, follows in the coming days through TestFlight and then the App Store.
Models are not bundled: each downloads once from Hugging Face, so installing one needs an internet connection. Check the model sizes and your free storage first. The three Speed models take about 4.8 GB together, because they share one speech tokenizer, stored once. Generation then runs locally.