CLI Reference
studio.py subcommands and backend.cli flags.
studio.py (launcher)
The cross-platform launcher orchestrates setup and running. It's stdlib-only and bootstraps the virtual environment, so you run it with your system Python.
| Command | What it does |
|---|---|
setup | One-time: venv, deps, PyTorch/CUDA auto-detect, system-dep checks, model picker |
start | Run backend + frontend (auto dev/prod) |
start --dev | Force dev (uvicorn :8880 + Vite :5173, hot reload) |
start --prod | Force prod (single server :8880 serving UI + API) |
start --device cpu | Forward a device to the backend (cuda / cpu / mps / auto) |
models | Re-open the interactive model picker |
install-chatterbox | Build the isolated Chatterbox env (also install-omnivoice / install-voxcpm / install-qwen) |
optimize-venvs | Rebuild engine venvs via uv to reclaim disk (--include-main to also rebuild the base venv) |
update --tag vX.Y.Z | Check out a release tag, sync deps, rebuild the frontend |
python studio.py setup
python studio.py start --prodstart forwards its flags (--device, --port, …) to the backend.
backend.cli (backend directly)
For finer control, run the FastAPI backend yourself from the repo root:
python -m backend.cli --engine kokoro --device cuda --port 8880
python -m backend.cli --help| Flag | Description |
|---|---|
--engine | Engine to activate on startup (persists across restarts) |
--model | HF model id or local path (VibeVoice only) |
--device | auto (default) / cuda / cpu / mps |
--kokoro-lang | Kokoro lang_code: a (US English) / b (British) / j (Japanese) / z (Mandarin) |
--chatterbox-lang | Default Chatterbox language_id (one of its 23 codes) |
--no-chatterbox-watermark | Disable Chatterbox's Perth watermark |
--models-dir | Where HF weights are cached (default backend/models/) |
--host | Bind host (default 0.0.0.0) |
--port | Bind port (default 8880) |
--voices-dir / --uploads-dir | Voice directories |
--log-level | debug / info / warning / error |
--reload | Autoreload (dev only) |
Once frontend/dist exists, the backend serves the built UI too, so
backend.cli alone runs the full app on one port — this is what the
VPS deployment service uses. CLI flags map onto the
same settings you can set via env vars — see Configuration.