07Reference
CLI
Every cuelo command and flag.
cuelo is a single Go binary with the dashboard embedded. Inside a project it
reads config.cuelo from the current directory. Run cuelo <command> --help
for the full text of any command.
Quick reference
| Command | What |
|---|---|
cuelo start | Run the default agent and open the dashboard. No project needed. |
cuelo init [dir] | Create a voice agent project. |
cuelo generate | Generate the Python project from config.cuelo. |
cuelo dev | Run locally: regenerate on config changes, reload on code changes. |
cuelo serve | Serve the agent's Realtime API, no reload. |
cuelo call | Talk to the running agent in your browser. |
cuelo doctor | Check config, credentials, generated code and imports. |
cuelo voices [provider] | Browse, preview and pick TTS voices. |
cuelo models | Browse and download turn-taking and backchannel models. |
cuelo machine check | Measure how many concurrent calls this machine handles in real time. |
cuelo start
| Flag | Default | |
|---|---|---|
--host | 127.0.0.1 | listen address. A non-loopback host needs CUELO_API_KEY. |
--port | 4141 | port |
--no-open | false | don't open the browser |
Reads .env in the current directory. See Default endpoint.
cuelo init [dir]
Creates config.cuelo, .env, a voice profile, and everything cuelo generate
makes from them.
| Flag | Default | |
|---|---|---|
--name | dir name | agent name |
--stt | smallest | STT provider |
--llm | cerebras | LLM provider |
--model | per provider | LLM model (anthropic claude-sonnet-5-5, cerebras qwen-3.8-27b) |
--tts | smallest | TTS provider |
--voice | provider default | TTS voice ID for config/voices/default.yaml |
--engine-path | — | use a local engine checkout instead of the git URL |
--no-actions | false | skip the sample lookup_order tool |
cuelo generate
| Flag | |
|---|---|
--check | exit 1 if generated files are out of date. Writes nothing. For CI. |
--diff | show what would change. Writes nothing. |
--force | overwrite hand edits in generated files |
--engine-path | use a local engine checkout (editable) instead of the git URL |
--git | switch back to the engine's git URL |
cuelo dev / cuelo serve
dev regenerates when config.cuelo or the voice profile changes, restarts
the server when Python files change, and serves the dashboard. serve does
neither and runs serve.workers processes.
| Flag | Default | |
|---|---|---|
--host | serve.host | listen address |
--port | serve.port | port |
--ui-port | 4142 | dashboard port (dev; for serve, setting it enables the dashboard) |
--no-ui | false | don't serve the dashboard |
cuelo call
Opens the dashboard's call page against the running agent, starting the
dashboard if needed. Flags: --ui-port, --no-open.
cuelo doctor
Checks the config against the schema, required credentials in .env, that
generated/ is up to date, and that the project imports. --no-import skips
the import step (faster, works offline).
cuelo voices
cuelo voices [provider] [-s query] [-l language] [--gender g] [--accent a] [--mine] [--library] [-n 40] [--all]
cuelo voices preview <voice-id> [--text "..."] [--save out.wav]
cuelo voices use <voice-id> [--force]Shared flags: --provider, --model, --refresh. See Voices.
cuelo models
cuelo models [--role r] [--all]
cuelo models info <name>
cuelo models pull <name...> | --allSee Models.
cuelo machine check
| Flag | Default | |
|---|---|---|
--seconds | 8 | audio per load level |
--single | false | one process only (skip worker sizing) |
See Deploy.
Python entry points
The engine package also installs:
| Command | |
|---|---|
cuelo-serve [agent.py] | Serve an agent file (default: the built-in agent). Flags: --host, --port, --workers, --reload, --env-file, --log-level. |
cuelo-bench | The benchmark behind machine check. Flags: --single, --json, --controllers module:function. |
Exit codes
0 success, 1 failure (for example a check that didn't pass), 2 invalid
input or config.