Command Reference

Complete reference for all VoiceRun CLI commands.

Global Options#

Flag	Description
`--version`, `-V`	Show the installed CLI version
`--update`, `-U`	Update CLI and refresh skills/MCP configs

Setup & Authentication#

`vr setup`#

Configure the CLI environment and install dependencies.

Flag	Description
`--skip-uv`	Skip uv installation
`--skip-skills`	Skip skills installation
`--skip-mcp`	Skip MCP server configuration
`--claude-code`	Install skills to Claude Code only
`--codex`	Install skills to Codex CLI only
`--openclaw`	Install skills to OpenClaw only
`--cursor`	Configure MCP for Cursor only
`--windsurf`	Configure MCP for Windsurf only

Flag	Description
`--api-key`, `-k`	API key for non-interactive sign-in
`--email`, `-e`	Email for non-interactive sign-in
`--password`, `-p`	Password (requires `--email`)

`vr signout`#

Sign out and clear stored credentials.

Project Lifecycle#

`vr init [PROJECT_NAME]`#

Create a new voice agent project.

Flag	Description
`--yes`, `-y`	Skip prompts and use defaults
`--force`, `-f`	Overwrite existing files
`--template`, `-t`	Initialize from a remote template
`--var`	Template variable as `key=value` (repeatable)

`vr validate`#

Validate project structure and configuration.

Flag	Description
`--quiet`, `-q`	Only output errors

`vr push`#

Push agent code to VoiceRun.

Flag	Description
`--name`	Name for the function version
`--new`, `-n`	Create a new function version
`--yes`, `-y`	Skip confirmation prompts

`vr pull [AGENT_ID]`#

Pull agent code from the server.

Flag	Description
`--output`, `-o`	Output directory
`--yes`, `-y`	Skip confirmation prompt

`vr deploy <ENVIRONMENT>`#

Deploy agent to an environment.

Flag	Description
`--yes`, `-y`	Skip confirmation prompts

`vr open`#

Open the agent's page in the VoiceRun web dashboard.

Development#

`vr debug`#

Push code and start an interactive debug session.

Flag	Description
`--skip-push`, `-s`	Skip pushing code
`--environment`, `-e`	Environment to debug (default: `debug`)
`--verbose`, `-v`	Show verbose debug output
`--outbound`, `-o`	Start an outbound phone call
`--to-phone-number`	Phone number to call
`--from-phone-number`	Caller ID phone number

`vr test [TEST_PATH]`#

Run tests for the agent project.

Flag	Description
`--environment`, `-e`	Environment to fetch secrets from
`--verbose`, `-v`	Run pytest in verbose mode
`--coverage`, `-c`	Run with coverage reporting
`--skip-install`	Skip dependency installation

Pass additional pytest arguments after --:

vr test -- -k "test_greeting" --tb=short

Resource Queries#

`vr get <resource>`#

List resources.

Command	Description
`vr get agents`	List all agents
`vr get functions <agent>`	List functions for an agent
`vr get environments <agent>`	List environments for an agent
`vr get secrets`	List organization secrets
`vr get phonenumbers`	List phone numbers
`vr get telephony`	List telephony providers
`vr get assignments <agent>`	List phone number assignments
`vr get templates`	List available templates

vr get secrets supports --agent, -a to include agent-level secrets.

`vr describe <resource>`#

Show detailed information about a resource.

Command	Description
`vr describe agent <name-or-id>`	Agent details
`vr describe function <agent> <name-or-id>`	Function details
`vr describe environment <agent> <name-or-id>`	Environment details
`vr describe secret <name-or-id>`	Secret details
`vr describe phonenumber <id>`	Phone number details
`vr describe telephony <name-or-id>`	Telephony provider details
`vr describe assignment <agent> <id>`	Assignment details

vr describe secret supports --agent, -a to search agent-level secrets.

Resource Creation#

`vr create secret <NAME> <VALUE>`#

Create a secret.

Flag	Description
`--agent`, `-a`	Agent name or ID (omit for organization secret)

`vr create phonenumber [TELEPHONY_ID]`#

Create or purchase a phone number.

Flag	Description
`--purchase`	Purchase a new number from the provider
`--area-code`, `-a`	Area code
`--country-code`, `-c`	Country code (default: US)
`--friendly-name`, `-n`	Friendly name
`--phone-number`, `-p`	Phone number to register

`vr create assignment <AGENT> <ENVIRONMENT> <PHONE_NUMBER_ID>`#

Assign a phone number to an agent environment.

Flag	Description
`--configure`	Configure the number with the telephony provider

`vr create telephony`#

Create a telephony provider.

Flag	Description
`--name`, `-n`	Provider name
`--provider-type`, `-p`	Type: `twilio` or `telnyx`
`--account-sid`	Twilio Account SID
`--api-key-sid`	Twilio API Key SID
`--api-key-secret`	Twilio API Key Secret
`--api-key`	Telnyx API Key

`vr create template <NAME>`#

Create a reusable template from the current project.

Flag	Description
`--description`, `-d`	Template description
`--category`, `-c`	Template category
`--public` / `--private`	Visibility (default: public)

Resource Deletion#

`vr delete <resource>`#

Delete a resource.

Command	Description
`vr delete agent <name-or-id>`	Delete an agent
`vr delete function <agent> <name-or-id>`	Delete a function
`vr delete environment <agent> <name-or-id>`	Delete an environment
`vr delete secret <name-or-id>`	Delete a secret
`vr delete phonenumber <name-or-id>`	Delete a phone number
`vr delete telephony <name-or-id>`	Delete a telephony provider
`vr delete assignment <agent> <id>`	Delete an assignment

vr delete secret supports --agent, -a. vr delete phonenumber supports --release to release back to the telephony provider.

Context Management#

Manage API contexts for different environments or organizations.

Command	Description
`vr context list`	List all contexts and show current
`vr context current`	Show current context details
`vr context switch <name>`	Switch to a different context
`vr context create <name> <api-url> <frontend-url>`	Create a custom context
`vr context delete <name>`	Delete a custom context
`vr context set-url <api-url>`	Set a custom API URL for the session
`vr context set-org <org-id>`	Set organization ID (empty string to clear)

Configuration Files#

File	Description
`handler.py`	Agent entry point, must contain `async def handler()`
`.voicerun/agent.yaml`	Agent metadata (name, description)
`.voicerun/agent.lock`	Auto-generated after `vr push` (agent/function IDs)
`.vrignore`	Files to exclude from `vr push` (gitignore syntax)
`requirements.txt`	Python dependencies

Credentials#

Credentials are stored in ~/.voicerun/:

File	Description
`~/.voicerun/cookie`	Session cookie
`~/.voicerun/apikey`	API key
`~/.voicerun/config.json`	CLI configuration and contexts