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

Flag	Description
`--skip-uv`	Skip uv installation
`--skip-helm`	Skip Helm 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`)

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 variables`	List organization and agent environment variables
`vr get secrets`	List organization secrets (evaluator use)
`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 variables supports --agent/-a, --environment/-e, and --org. Agent environment variables are only listed when both an agent (from the flag or .voicerun/agent.lock) and an environment are resolvable.

`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 variable <name-or-id>`	Variable details (masked values show as `••••••••`)
`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 <phone-number>`	Assignment details

vr describe variable supports --agent/-a, --environment/-e, and --org to locate an agent environment variable.

Resource Creation#

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

Create a variable readable via context.variables.get(NAME) in agent handlers. Defaults to an agent environment variable; pass --org for an organization-level variable.

Flag	Description
`--agent`, `-a`	Agent name or ID (defaults to `.voicerun/agent.lock`)
`--environment`, `-e`	Environment name or ID (required unless `--org`)
`--org`	Create an organization-level variable
`--masked`	Hide the value in CLI listings and the web UI (runtime still receives the real value)

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

Create an organization-level secret for use by evaluators. Agent-scoped runtime injection is not yet supported — use vr create variable --masked when you need a value readable via context.variables.get().

Flag	Description
`--agent`, `-a`	(Unsupported) Exits non-zero with a redirect to `vr create variable --masked`

`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. Sets agentId and agentEnvironmentId on the phone number via PATCH /v1/organization-phone-numbers/:id.

Flag	Description
`--configure`	After assigning, configure the number with the telephony provider so incoming calls route to the agent

`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 variable <name-or-id>`	Delete a variable
`vr delete secret <name-or-id>`	Delete an organization secret
`vr delete phonenumber <name-or-id>`	Delete a phone number
`vr delete telephony <name-or-id>`	Delete a telephony provider
`vr delete assignment <phone-number>`	Unassign a phone number from its agent environment

vr delete variable supports --agent/-a, --environment/-e, and --org. vr delete phonenumber supports --release to release back to the telephony provider. vr delete assignment supports --skip-unconfigure to skip the telephony provider unconfigure step.

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)

Session Observability#

`vr session list [AGENT]`#

List sessions for an agent. If AGENT is omitted, the CLI resolves the agent from .voicerun/agent.lock in the current project.

Flag	Description
`--status`, `-s`	Filter by status
`--direction`, `-d`	Filter by call direction
`--limit`, `-l`	Limit number of results
`--page`, `-p`	Page number
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force table output

`vr session info <SESSION_ID>`#

Show detailed information for a session.

Flag	Description
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force rich/table output

`vr session trace <SESSION_ID>`#

Show session trace as a span tree.

Flag	Description
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force tree output

`vr session span <SESSION_ID> <SPAN_ID>`#

Show detailed information for a specific span in a session trace.

Flag	Description
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force rich/table output

`vr session transcript <AGENT> <SESSION_ID>`#

Show transcript events for a session.

Flag	Description
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force conversation/table output

`vr session events <AGENT> <SESSION_ID>`#

Show raw session events.

Flag	Description
`--page`, `-p`	Page number
`--limit`, `-l`	Limit number of results
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force table output

Evaluations#

`vr evaluation list [AGENT]`#

List evaluations for an agent, or for a specific session via --session.

Flag	Description
`--session`, `-S`	Session ID to get evaluations for
`--status`, `-s`	Filter by status (`pending`, `complete`, `error`)
`--type`, `-T`	Filter by eval type (`judge`, `extraction`, `script`)
`--limit`, `-l`	Limit number of results
`--page`, `-p`	Page number
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force table output

`vr evaluation info <EVALUATION_ID>`#

Show detailed information about an evaluation.

Flag	Description
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force rich/table output

Usage Reporting#

`vr usage report`#

Show usage report for a date range (defaults to last 30 days).

Flag	Description
`--start`, `-s`	Start date (`YYYY-MM-DD`)
`--end`, `-e`	End date (`YYYY-MM-DD`)
`--by-tags`	Break down usage by session tags
`--tags`	Filter by tags as JSON (for example `'{"team":"sales"}'`)
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force table output

`vr usage monthly`#

Show usage report for a specific month.

Flag	Description
`--year`, `-y`	Year (defaults to current year)
`--month`, `-m`	Month 1-12 (defaults to current month)
`--by-tags`	Break down usage by session tags
`--tags`	Filter by tags as JSON (for example `'{"team":"sales"}'`)
`--json`, `-j`	Output as JSON
`--table`, `-t`	Force table output

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