# CLI (/reference/cli)

`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 [#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` [#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](/default-agent).

## `cuelo init [dir]` [#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` [#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` [#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` [#cuelo-call]

Opens the dashboard's call page against the running agent, starting the
dashboard if needed. Flags: `--ui-port`, `--no-open`.

## `cuelo doctor` [#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]

```bash
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](/build/voices).

## `cuelo models` [#cuelo-models]

```bash
cuelo models [--role r] [--all]
cuelo models info <name>
cuelo models pull <name...> | --all
```

See [Models](/reference/models).

## `cuelo machine check` [#cuelo-machine-check]

| Flag        | Default |                                       |
| ----------- | ------- | ------------------------------------- |
| `--seconds` | `8`     | audio per load level                  |
| `--single`  | `false` | one process only (skip worker sizing) |

See [Deploy](/ship/deploy).

## Python entry points [#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 [#exit-codes]

`0` success, `1` failure (for example a check that didn't pass), `2` invalid
input or config.