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[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.
`check`	Verify metering and storage end to end (drives one synthetic request).
`livekit`	Diagnostics against a LiveKit server: agents, latency, SFU health, combined check.
`logs`	Recent request logs.
`costs`	Cost summaries per provider, project, and period.
`projects`	List configured projects.
`dashboard`	Open the dashboard in your browser.
`replay`	Print the dashboard replay URL for a session.

Reconciliation and export

Command	Description
`reconcile`	Diff logged costs against a provider invoice.
`prices`	Inspect the billing rate card and reconcile rated revenue against cost per tenant.
`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 voicegw with no arguments displays the help menu.
Most commands accept --config (-c) to specify a custom path to voicegw.yaml. If omitted, the gateway searches in this order: ./voicegw.yaml, ~/.config/voicegateway/voicegw.yaml, /etc/voicegateway/voicegw.yaml. The VOICEGW_CONFIG environment variable overrides the search.
Commands that need cost or log data require cost_tracking.enabled: true in the config (which activates the SQLite backend), or the VOICEGW_DB_PATH env 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 dashboard

For the full first-run walkthrough see Get started.

​CLI reference

​Installation

​Subcommands

​Onboarding and lifecycle

​Inspect and verify

​Reconciliation and export

​MCP server

​Global behaviour

​Quick start