CLI reference
Every voicegw command, what it does, and where to read more.
CLI reference
VoiceGateway ships a command-line interface called voicegw. It is
the primary way to onboard, run the daemon, inspect gateway state,
and reconcile costs.
Installation
The CLI is installed automatically with the package:
pipx install 'voicegateway[cloud,dashboard]'After installation, the voicegw command is available globally. See
Installation for every install variant
(curl-bash, pipx, uv, Docker, source).
Subcommands
Onboarding and lifecycle
| Command | Description |
|---|---|
onboard | Five-question wizard. Writes config, installs and starts the daemon. |
init | Scaffold a voicegw.yaml from the bundled template. |
serve | Run the daemon in the foreground. |
start | Start the OS-managed daemon. |
stop | Stop the OS-managed daemon. |
restart | Restart the OS-managed daemon. |
daemon-logs | Tail the OS-native daemon log stream. |
uninstall-daemon | Remove the daemon registration (config + db preserved). |
Inspect and verify
| Command | Description |
|---|---|
status | Provider configuration status. |
doctor | Numbered punch list with fix steps. |
smoke-test | Verify the inference pipeline end-to-end without LiveKit. |
logs | Recent request logs. |
costs | Cost summaries per provider, project, and period. |
projects | List configured projects. |
dashboard | Open the dashboard in your browser. |
tui | Launch the terminal UI (status, costs, sessions). |
replay | Print the dashboard replay URL for a session. |
Reconciliation and export
| Command | Description |
|---|---|
reconcile | Diff logged costs against a provider invoice. |
export-costs | Export per-request cost rows to CSV / JSONL. |
MCP server
| Command | Description |
|---|---|
mcp | Run the MCP server (stdio or HTTP/SSE) so coding agents can manage the gateway. |
Global behaviour
- Running
voicegwwith no arguments displays the help menu. - Most commands accept
--config(-c) to specify a custom path tovoicegw.yaml. If omitted, the gateway searches in this order:./voicegw.yaml,~/.config/voicegateway/voicegw.yaml,/etc/voicegateway/voicegw.yaml. TheVOICEGW_CONFIGenvironment variable overrides the search. - Commands that need cost or log data require
cost_tracking.enabled: truein the config (which activates the SQLite backend), or theVOICEGW_DB_PATHenv var pointing at a database path. - The CLI uses Rich for formatted terminal output (tables, panels, coloured text).
Quick start
# 1. Run the wizard
voicegw onboard
# 2. Verify state
voicegw status
voicegw doctor
# 3. Open the dashboard
voicegw dashboardFor the full first-run walkthrough see Get started.