voicerun-cli 1.5.18

VoiceRun command-line interface

VoiceRun CLI

A command-line interface for building and deploying voice agents on the VoiceRun platform.

Table of Contents

• Installation
• Quick Start
• Authentication
• Global Options
  • --version
  • --update
• Commands
  • setup
  • signin
  • signout
  • init
  • validate
  • pull
  • push
  • deploy
  • debug
  • open
  • render
  • test
  • get
  • describe
  • create
  • delete
  • context
  • metrics
  • experiments
  • report
• .vrignore
• Project Structure
• Templates
• Values Files
• Configuration
• Environment Variables

Installation

Prerequisites

• Python 3.10 or higher

Install from PyPI

pip install voicerun-cli

Install from Source

git clone https://github.com/VoiceRun/voicerun-cli.git
cd voicerun-cli
pip install -e .

Install a Specific Version

uv tool install voicerun-cli==1.0.0 --force

Install Local Version

To install a local checkout as a CLI tool (useful for testing changes):

uv tool install --force -e .

Quick Start

# 1. Set up the CLI
vr setup

# 2. Create a new voice agent project
vr init my-agent

# 3. Navigate to the project directory
cd my-agent

# 4. Sign in to VoiceRun
vr signin

# 5. Edit handler.py to customize your agent logic

# 6. Validate your project
vr validate

# 7. Deploy to VoiceRun
vr push

# 8. Debug visually or open the web UI
vr debug      # Launch Pipeline Debugger
vr open       # Open web UI

Authentication

VoiceRun CLI supports three authentication methods:

Browser Authentication (Recommended)

vr signin

Opens your default browser for secure OAuth-style authentication.

Email/Password

vr signin
# Then select option 2 when prompted

API Key

vr signin
# Then select option 3 when prompted

Sign Out

vr signout

Credentials are stored in ~/.voicerun/:

• Cookie: ~/.voicerun/cookie
• API Key: ~/.voicerun/apikey
• Config: ~/.voicerun/config.json

Global Options

vr --version

Show the installed CLI version and exit.

vr --version
vr -V

---

vr --update

Update the VoiceRun CLI to the latest version from PyPI and refresh all installed skills and MCP server configurations.

vr --update
vr -U

What it does:

1. Upgrades the voicerun-cli package to the latest version via pip
2. Reinstalls skills to the targets selected during vr setup (e.g., Claude Code, Codex, OpenClaw)
3. Refreshes MCP server configuration for the targets selected during vr setup (e.g., Claude Code, Cursor, Windsurf)

Only targets that were explicitly chosen during vr setup are updated — no interactive prompts are shown. If vr setup has not been run, the update will skip skills and MCP configuration.

Example:

# Update everything
vr --update

# Short form
vr -U

---

Commands

Agent auto-resolution: Many commands that take an AGENT argument can infer it automatically when run inside a voicerun project directory (i.e., one with .voicerun/agent.lock). In those cases, the AGENT argument is optional. These commands are marked with [AGENT] in their usage.

vr setup

Set up the VoiceRun CLI environment by installing required dependencies.

vr setup

Example:

vr setup

---

vr signin

Sign in to the VoiceRun API.

vr signin

Prompts for authentication method:

1. Web browser (default) - Opens browser for OAuth authentication
2. Email/Password - Enter credentials directly
3. API Key - Use an API key for authentication

Example:

vr signin
# Select authentication method when prompted

---

vr signout

Sign out and clear stored credentials.

vr signout

---

vr init

Create a new voice agent project from templates.

vr init [PROJECT_NAME]

Options:

Option	Description
--yes, -y	Skip prompts and use defaults
--force, -f	Overwrite existing files
--template, -t	Initialize from a remote template (name or ID)
--var	Template variable as key=value (can be repeated)

Example:

# Interactive mode
vr init

# Non-interactive with project name
vr init my-agent --yes

# Initialize from a remote template
vr init my-agent --template customer-support

# Initialize from template with variables
vr init my-agent -t customer-support --var greeting="Hello" --var language="en"

---

vr validate

Validate project structure and configuration.

vr validate

Options:

Option	Description
--environment, -e	Environment to render templates for
--quiet, -q	Only output errors

Validation Checks:

• handler.py exists and contains async def handler()
• .voicerun/ directory structure is correct
• agent.yaml is valid with required fields
• YAML syntax in all template files
• Deployment spec contains only allowed fields

Example:

# Validate with specific environment
vr validate -e production

# Quiet mode (errors only)
vr validate -q

---

vr pull

Pull agent code from the VoiceRun server to your local machine.

vr pull [AGENT_ID]

Arguments:

Argument	Description
AGENT_ID	Agent ID to pull (not required if inside a voicerun project)

Options:

Option	Description
--output, -o	Output directory (defaults to agent name)
--yes, -y	Skip confirmation prompt

Behavior:

• Inside a voicerun project: Pulls code using the agent ID from agent.lock and overwrites local files
• Outside a voicerun project: Requires an agent ID, creates a new directory with the pulled code and initializes .voicerun/agent.lock

Example:

# Pull inside an existing project
vr pull

# Pull a specific agent into a new directory
vr pull 550e8400-e29b-41d4-a716-446655440000

# Pull into a custom directory
vr pull 550e8400-e29b-41d4-a716-446655440000 -o ./my-agent

# Skip confirmation
vr pull --yes

---

vr push

Deploy your agent code to the VoiceRun server.

vr push

Options:

Option	Description
--name	Name for the function version
--new, -n	Create a new function version instead of updating
--yes, -y	Skip confirmation prompts

Behavior:

• Validates the project before pushing
• Packages code as a zip archive (excludes .venv, __pycache__, .git, etc. and files matching .vrignore)
• Creates or updates agent.lock with agent and function IDs
• First push creates a new agent; subsequent pushes update the existing version

Example:

# Push with confirmation
vr push

# Push without confirmation
vr push --yes

# Create a new version
vr push --new --name "v2.0"

---

vr deploy

Deploy the latest pushed function version to an environment.

vr deploy <ENVIRONMENT>

Arguments:

Argument	Description
ENVIRONMENT	Target environment name or ID (e.g., development, production). If not specified, you'll be prompted to select.

Options:

Option	Description
--yes, -y	Skip confirmation prompt

Prerequisites:

• Run vr push first to create an agent and generate agent.lock

What it does:

1. Validates the project structure
2. Loads the agent ID and function ID from agent.lock
3. Resolves the target environment
4. Deploys the function version to the environment

Example:

# Deploy interactively (select environment from list)
vr deploy

# Deploy to development environment
vr deploy development

# Deploy to production without confirmation
vr deploy production --yes

---

vr debug

Push local code and launch the Pipeline Debugger — a visual Electron app for real-time agent testing. Can also place outbound phone calls directly from the CLI.

vr debug

Options:

Option	Description
--skip-push, -s	Skip pushing code, use the existing deployment
--environment, -e	Environment name (default: debug)
--headless	Run without GUI (for CI / coding agents). Streams JSONL events to stdout, reads text input from stdin, and exports session JSON on exit
--output, -o	Output file path for headless session JSON (auto-generated if omitted)
--script	Path to a JSON file with scripted messages (array of strings). Each message is sent one-per-turn automatically
--outbound	Place an outbound phone call instead of launching the debugger
--to-phone-number	Destination phone number in E.164 format (required with --outbound)
--from-phone-number	Caller ID / originating phone number in E.164 format (optional)

Prerequisites:

• Node.js must be installed for the debugger (not required for --outbound mode)

What it does:

• Inside a voicerun project: Pushes your local code to the VoiceRun server (unless --skip-push), installs debugger dependencies if needed, and launches the Pipeline Debugger connected to your agent.
• Outside a project: Opens the Pipeline Debugger with no prefilled agent info, so you can connect manually.
• Headless mode: Runs the debugger without a GUI window — streams JSONL events to stdout and accepts text input on stdin (one message per line). Useful for CI pipelines and coding agents.
• Outbound mode: Pushes your code and places an outbound phone call to the specified number. Returns a telephonyCallId for tracking. Does not launch the debugger GUI.

Example:

# Push and debug (inside a project)
vr debug

# Debug without pushing (use existing deployment)
vr debug --skip-push
vr debug -s

# Debug specific environment
vr debug -e staging

# Open the debugger standalone (from any directory)
vr debug

# Headless mode (CI / coding agents)
vr debug --headless
vr debug --headless --output session.json

# Run a scripted conversation
vr debug --script test-messages.json
vr debug --headless --script test-messages.json -o results.json

# Place an outbound phone call
vr debug --outbound --to-phone-number "[phone]"

# Outbound call with caller ID and custom environment
vr debug --outbound --to-phone-number "[phone]" --from-phone-number "[phone]" -e production

# Outbound call without pushing (use existing deployment)
vr debug --outbound --to-phone-number "[phone]" --skip-push

---

vr open

Open the web interface to your deployed agent.

vr open

Requires agent.lock to exist (created after vr push). Opens your default browser to the agent's function page.

---

vr render

Render VoiceRun templates and display the output.

vr render

Options:

Option	Description
--values, -f	Custom values file path
--set, -s	Override values (can be used multiple times)
--output, -o	Output format: yaml (default) or json
--quiet, -q	Only output templates, no validation messages

Example:

# Render with default values
vr render

# Render with specific values file
vr render -f .voicerun/values.yaml

# Override specific values
vr render --set stt.model=deepgram-flux --set environment=production

# Output as JSON
vr render -o json

---

vr test

Run tests for the voice agent project.

vr test

Options:

Option	Description
--environment, -e	Environment to fetch secrets from (e.g., development, production)
--verbose, -v	Run pytest in verbose mode
--coverage, -c	Run with coverage reporting
--skip-install	Skip dependency installation

What it does:

1. Validates project structure
2. Installs project dependencies (unless --skip-install)
3. Optionally fetches secrets from the specified environment
4. Runs pytest with the specified options

Example:

# Run all tests
vr test

# Run specific test file
vr test tests/test_handler.py

# Run tests with development secrets
vr test -e development

# Run with verbose output and coverage
vr test -v -c

# Skip dependency installation
vr test --skip-install

# Pass extra arguments to pytest
vr test -- -k "test_name" -x

---

vr get

List resources by type.

vr get agents

List all agents in your account.

vr get agents

Displays a table with agent name, ID, description, voice, and transport.

vr get functions

List all functions for a specific agent.

vr get functions [AGENT]

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)

Example:

# Inside a voicerun project (uses agent.lock)
vr get functions

# Explicit agent
vr get functions my-agent
vr get functions 550e8400-e29b-41d4-a716-446655440000

vr get environments

List all environments for a specific agent.

vr get environments [AGENT]

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)

Example:

# Inside a voicerun project (uses agent.lock)
vr get environments

# Explicit agent
vr get environments my-agent

vr get variables

List variables that agents can read via context.variables.get(NAME) at runtime. Always lists organization-level variables. If an agent and environment are both resolvable (via --agent/agent.lock and --environment), also lists that environment's variables.

vr get variables

Options:

Option	Description
--agent, -a	Agent name or ID (defaults to agent.lock)
--environment, -e	Environment name or ID (required to list agent variables)
--org	Only list organization-level variables

Example:

# List organization variables
vr get variables --org

# Inside a voicerun project, list both org + environment variables
vr get variables --environment production

# Explicit agent
vr get variables --agent my-agent --environment production

Masked values render as •••••••• in the output.

vr get secrets

List organization-level secrets used by evaluators. Agent-scoped secrets are not yet supported for runtime injection — use vr create variable with --masked when you need a value readable via context.variables.get().

vr get secrets

Options:

Option	Description
--agent, -a	Agent name or ID (for listing existing legacy agent-scoped secret records)

Example:

# List organization secrets
vr get secrets

vr get phonenumbers

List organization phone numbers.

vr get phonenumbers

Displays a table with phone number, friendly name, ID, area code, and country code.

vr get telephony

List organization telephony providers.

vr get telephony

Displays a table with provider name, ID, and provider type.

vr get assignments

List all phone number assignments for an agent.

vr get assignments [AGENT]

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)

Example:

# Inside a voicerun project (uses agent.lock)
vr get assignments

# Explicit agent
vr get assignments my-agent

Displays a table with phone number ID, environment ID, assignment ID, and created at timestamp.

vr get templates

List available agent templates.

vr get templates

Displays a table with template name, ID, category, description, and public/private status.

---

vr describe

Show detailed information about a specific resource.

vr describe assignment

Show detailed information about a phone number assignment.

vr describe assignment [AGENT] <ASSIGNMENT_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
ASSIGNMENT_ID	Assignment UUID

Example:

# Inside a voicerun project (uses agent.lock)
vr describe assignment 550e8400-e29b-41d4-a716-446655440000

# Explicit agent
vr describe assignment my-agent 550e8400-e29b-41d4-a716-446655440000

Output includes:

• Assignment details (ID, environment ID, phone number ID)
• Timestamps

vr describe agent

Show detailed information about an agent.

vr describe agent [NAME_OR_ID]

Arguments:

Argument	Description
NAME_OR_ID	Agent name or UUID (defaults to agent.lock)

Example:

# Inside a voicerun project (uses agent.lock)
vr describe agent

# Explicit agent
vr describe agent my-agent

Output includes:

• Basic information (ID, name, description)
• Voice & transport configuration
• Organization details
• Debug & tracing settings
• Timestamps

vr describe function

Show detailed information about a function.

vr describe function [AGENT] <NAME_OR_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
NAME_OR_ID	Function name, display name, or UUID

Example:

# Inside a voicerun project (uses agent.lock)
vr describe function main-handler

# Explicit agent
vr describe function my-agent main-handler

Output includes:

• Basic information (ID, name, display name)
• Code configuration (language, strategy, multifile)
• Code preview (if available)
• Test data (if configured)
• Timestamps

vr describe environment

Show detailed information about an environment.

vr describe environment [AGENT] <NAME_OR_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
NAME_OR_ID	Environment name or UUID

Example:

# Inside a voicerun project (uses agent.lock)
vr describe environment production

# Explicit agent
vr describe environment my-agent production

Output includes:

• Basic information (ID, name, phone number, debug flag)
• Speech-to-text (STT) configuration
• Recording settings
• Error handling configuration
• Audio processing settings
• VAD & advanced settings
• Timestamps

vr describe variable

Show detailed information about a variable. Searches organization-level variables by default, and agent environment variables when --agent and --environment are provided.

vr describe variable <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Variable name or UUID

Options:

Option	Description
--agent, -a	Agent name or ID (defaults to agent.lock)
--environment, -e	Environment name or ID (required to search agent variables)
--org	Only search organization-level variables

Example:

vr describe variable ANTHROPIC_API_KEY
vr describe variable ANTHROPIC_API_KEY --agent my-agent --environment production

Masked values render as •••••••• in the output.

vr describe secret

Show detailed information about an organization-level secret (evaluator-only).

vr describe secret <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Secret name or UUID

Options:

Option	Description
--agent, -a	Agent name or ID (searches organization secrets first, then agent secrets)

Example:

vr describe secret MY_API_KEY

vr describe phonenumber

Show detailed information about a phone number.

vr describe phonenumber <ID>

Arguments:

Argument	Description
ID	Phone number ID

Example:

vr describe phonenumber 550e8400-e29b-41d4-a716-446655440000

Output includes:

• Phone number, friendly name, area code, country code
• Telephony provider ID
• Timestamps

vr describe telephony

Show detailed information about a telephony provider.

vr describe telephony <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Telephony provider name or UUID

Example:

vr describe telephony my-twilio

Output includes:

• Provider name, type, and ID
• Organization ID
• Timestamps

---

vr create

Create resources.

vr create assignment

Assign a phone number to an agent environment.

vr create assignment [AGENT] <ENVIRONMENT> <PHONE_NUMBER_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
ENVIRONMENT	Environment name or ID
PHONE_NUMBER_ID	Organization phone number ID

Options:

Option	Description
--configure	Configure the phone number with the telephony provider after assignment

Example:

# Inside a voicerun project (uses agent.lock)
vr create assignment production 550e8400-e29b-41d4-a716-446655440000

# Explicit agent
vr create assignment my-agent production 550e8400-e29b-41d4-a716-446655440000
vr create assignment my-agent production 550e8400-e29b-41d4-a716-446655440000 --configure

vr create environment

Create an environment for an agent.

vr create environment [AGENT] <NAME>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
NAME	Environment name

Options:

Option	Description
--stt-model	Speech-to-text model (e.g. nova-3)
--stt-language	STT language code (e.g. en)
--stt-endpointing	STT endpointing timeout in ms
--recording/--no-recording	Enable or disable call recording

Example:

# Inside a voicerun project (uses agent.lock)
vr create environment production

# Explicit agent
vr create environment my-agent production

# Create with STT and recording options
vr create environment my-agent staging --stt-model nova-3 --stt-language en --recording

vr create variable

Create a variable that an agent handler can read via context.variables.get(NAME). By default creates a variable scoped to a specific agent environment; pass --org to create an organization-level variable visible to every agent in the org.

Use --masked for sensitive values like API keys — the value is still delivered to the agent at runtime, but hidden from CLI listings and UI reads.

vr create variable <NAME> <VALUE>

Arguments:

Argument	Description
NAME	Variable name (use the same key in context.variables.get(NAME))
VALUE	Variable value

Options:

Option	Description
--agent, -a	Agent name or ID (defaults to agent.lock)
--environment, -e	Environment name or ID (required unless --org)
--org	Create an organization-level variable instead of an agent environment variable
--masked	Mask the value in listings and describe output

Examples:

# Create an environment variable inside a voicerun project
vr create variable ANTHROPIC_API_KEY sk-ant-... --environment production --masked

# Explicit agent
vr create variable ANTHROPIC_API_KEY sk-ant-... --agent my-agent --environment production --masked

# Organization-level variable available to every agent
vr create variable SUPPORT_EMAIL [e-mail] --org

In the Python handler:

def handler(context):
    api_key = context.variables.get("ANTHROPIC_API_KEY")
    ...

vr create secret

Create an organization-level secret for use by evaluators. Agent-scoped secrets are not yet supported for runtime injection — if you need a value readable via context.variables.get() at runtime, use vr create variable with --masked instead.

vr create secret <NAME> <VALUE>

Arguments:

Argument	Description
NAME	Secret name
VALUE	Secret value

Options:

Option	Description
--agent, -a	(Unsupported) Rejects with a redirect to vr create variable --masked

Example:

# Create an organization secret for evaluator usage
vr create secret MY_API_KEY sk-1234567890

vr create phonenumber

Create or purchase a phone number for the organization.

vr create phonenumber <TELEPHONY_ID>

Arguments:

Argument	Description
TELEPHONY_ID	Telephony provider ID

Options:

Option	Description
--purchase	Purchase a new number from the telephony provider
--area-code, -a	Area code for the phone number
--country-code, -c	Country code (defaults to US)
--friendly-name, -n	Friendly name for the phone number
--phone-number, -p	Phone number to register (without --purchase)

Example:

# Purchase a new phone number
vr create phonenumber <telephony-id> --purchase --area-code 415

# Register an existing phone number
vr create phonenumber <telephony-id> --phone-number "[phone]" --friendly-name "Support Line"

vr create template

Create a reusable template from the current project files. All text files in the project directory are collected and uploaded. Binary files are skipped automatically. Files matching patterns in .vrignore are excluded.

vr create template <NAME>

Arguments:

Argument	Description
NAME	Template name

Options:

Option	Description
--description, -d	Template description
--category, -c	Template category
--public/--private	Make template public or private to org (default: public)

Example:

# Create a public template
vr create template my-agent-template

# Create a private template with metadata
vr create template my-agent-template --private -d "Customer support agent" -c "support"

---

vr create telephony

Create a telephony provider for the organization. Missing options will be prompted interactively.

vr create telephony

Options:

Option	Description
--name, -n	Name for the telephony provider
--provider-type, -p	Provider type (e.g., twilio, 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

Example:

# Interactive mode
vr create telephony

# Non-interactive with all options
vr create telephony --name "My Twilio" --provider-type twilio \
  --account-sid AC123 --api-key-sid SK123 --api-key-secret secret123

---

vr delete

Delete resources.

vr delete assignment

Delete a phone number assignment from an agent.

vr delete assignment [AGENT] <ASSIGNMENT_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
ASSIGNMENT_ID	Assignment ID

Example:

# Inside a voicerun project (uses agent.lock)
vr delete assignment 550e8400-e29b-41d4-a716-446655440000

# Explicit agent
vr delete assignment my-agent 550e8400-e29b-41d4-a716-446655440000

vr delete agent

Delete an agent.

vr delete agent <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Agent name or ID

Example:

vr delete agent my-agent

vr delete function

Delete a function from an agent.

vr delete function [AGENT] <NAME_OR_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
NAME_OR_ID	Function name, display name, or ID

Example:

# Inside a voicerun project (uses agent.lock)
vr delete function main-handler

# Explicit agent
vr delete function my-agent main-handler

vr delete environment

Delete an environment from an agent.

vr delete environment [AGENT] <NAME_OR_ID>

Arguments:

Argument	Description
AGENT	Agent name or ID (defaults to agent.lock)
NAME_OR_ID	Environment name or ID

Example:

# Inside a voicerun project (uses agent.lock)
vr delete environment staging

# Explicit agent
vr delete environment my-agent staging

vr delete variable

Delete a variable. Searches organization-level variables first, then agent environment variables when --agent and --environment are both provided.

vr delete variable <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Variable name or ID

Options:

Option	Description
--agent, -a	Agent name or ID (defaults to agent.lock)
--environment, -e	Environment name or ID (required to delete agent variables)
--org	Only search organization-level variables

Example:

vr delete variable SUPPORT_EMAIL --org
vr delete variable ANTHROPIC_API_KEY --agent my-agent --environment production

vr delete secret

Delete an organization-level secret (evaluator usage). Searches organization secrets first, then legacy agent-scoped secret records.

vr delete secret <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Secret name or ID

Options:

Option	Description
--agent, -a	Agent name or ID

Example:

vr delete secret MY_API_KEY

vr delete phonenumber

Delete or release an organization phone number.

vr delete phonenumber <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Phone number ID, phone number, or friendly name

Options:

Option	Description
--release	Release the number back to the telephony provider

Example:

# Delete from VoiceRun only
vr delete phonenumber "[phone]"

# Release back to the telephony provider
vr delete phonenumber "[phone]" --release

vr delete telephony

Delete an organization telephony provider.

vr delete telephony <NAME_OR_ID>

Arguments:

Argument	Description
NAME_OR_ID	Telephony provider name or ID

Example:

vr delete telephony my-twilio

---

vr context

Manage API contexts for different environments (development, staging, production).

vr context list

List all available contexts and show the current one.

vr context list

vr context current

Show the current context with API and frontend URLs.

vr context current

vr context switch

Switch to a different context.

vr context switch <NAME>

vr context create

Create a new user-defined context.

vr context create <NAME> <API_URL> <FRONTEND_URL>

Example:

vr context create staging https://api.staging.voicerun.com https://app.staging.voicerun.com

vr context delete

Delete a user-defined context.

vr context delete <NAME>

vr context set-url

Set a custom API URL for the current session.

vr context set-url <API_URL>

vr context set-org

Set the organization ID to operate under. Useful when your account belongs to multiple organizations.

vr context set-org <ORGANIZATION_ID>

Arguments:

Argument	Description
ORGANIZATION_ID	Organization ID to use (pass empty string to clear)

Example:

# Set organization ID
vr context set-org org_123456

# Clear organization override (use default from session)
vr context set-org ""

vr metrics

Query custom metrics for agents. Supports listing metric names, discovering tags, fetching time-series data, and viewing per-session metrics. Commands that accept an agent filter will resolve from --agent (or positional argument) first, falling back to agent.lock if run inside a voicerun project.

vr metrics names

List available custom metric names.

vr metrics names [AGENT]

Arguments:

Argument	Description
AGENT	Agent name or ID (optional, filters by agent; uses agent.lock if omitted)

Options:

Option	Description
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# List all metric names
vr metrics names

# List metric names for a specific agent
vr metrics names my-agent

vr metrics tags

Discover available tag keys and their values for filtering.

vr metrics tags

Options:

Option	Description
--metric, -m	Filter tags by metric name
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# List all tags
vr metrics tags

# List tags for a specific metric
vr metrics tags --metric my_custom_metric

# List tags for a specific agent
vr metrics tags --agent my-agent

vr metrics timeseries

Fetch time-series data for a custom metric with type-appropriate aggregation.

vr metrics timeseries <METRIC_NAME> --start <START> --end <END>

Arguments:

Argument	Description
METRIC_NAME	The metric name to query

Options:

Option	Description
--start, -s	Start date (ISO 8601, e.g. 2026-03-15T00:00:00Z) (required)
--end, -e	End date (ISO 8601, e.g. 2026-03-16T00:00:00Z) (required)
--step	Time interval for aggregation (e.g. 30m, 1h, 1d). Default: 1h
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--environment, -E	Environment ID
--tags	Tag filters as JSON (e.g. '{"channel":"phone"}')
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# Fetch timeseries for a metric over a day
vr metrics timeseries call_duration --start 2026-03-15T00:00:00Z --end 2026-03-16T00:00:00Z

# With hourly aggregation for a specific agent
vr metrics timeseries call_duration -s 2026-03-15T00:00:00Z -e 2026-03-16T00:00:00Z --step 1h --agent my-agent

# Filter by tags
vr metrics timeseries call_duration -s 2026-03-15T00:00:00Z -e 2026-03-16T00:00:00Z --tags '{"channel":"phone"}'

vr metrics session

Fetch all custom metrics for a specific session.

vr metrics session <SESSION_ID>

Arguments:

Argument	Description
SESSION_ID	Session ID

Options:

Option	Description
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

vr metrics session 550e8400-e29b-41d4-a716-446655440000

Output includes:

• Metric name, type, value, and timestamp for each metric recorded in the session

---

vr experiments

View experiments and A/B test results for agents. All subcommands resolve the agent from --agent or from agent.lock if run inside a voicerun project.

vr experiments list

List all experiments for an agent.

vr experiments list

Options:

Option	Description
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# List experiments for the current project
vr experiments list

# List experiments for a specific agent
vr experiments list --agent my-agent

vr experiments describe

Show detailed results for a specific experiment, including variant performance, conversion rates, and statistical significance.

vr experiments describe <EXPERIMENT_NAME>

Arguments:

Argument	Description
EXPERIMENT_NAME	Experiment name

Options:

Option	Description
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# Describe an experiment in the current project
vr experiments describe greeting_style

# Describe an experiment for a specific agent
vr experiments describe greeting_style --agent my-agent

Output includes:

• Session count and completion status
• Conversion metrics being tracked
• Stop conditions (iterations and confidence thresholds)
• Variant breakdown with per-metric conversion rates
• Statistical significance results (confidence, p-value)

vr experiments timeseries

Fetch time-series data for an experiment metric, broken down by variant.

vr experiments timeseries <EXPERIMENT_NAME> --metric <METRIC> --start <START> --end <END>

Arguments:

Argument	Description
EXPERIMENT_NAME	Experiment name

Options:

Option	Description
--metric, -m	Metric/outcome name to query (required)
--start, -s	Start date (ISO 8601, e.g. 2026-03-15T00:00:00Z) (required)
--end, -e	End date (ISO 8601, e.g. 2026-03-16T00:00:00Z) (required)
--step	Time interval for aggregation (e.g. 30m, 1h, 1d). Default: 1h
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# Fetch daily timeseries for a conversion metric
vr experiments timeseries greeting_style --metric booking_completed \
  --start 2026-03-01T00:00:00Z --end 2026-03-15T00:00:00Z --step 1d

# Hourly breakdown for a specific agent
vr experiments timeseries greeting_style -m call_duration \
  -s 2026-03-15T00:00:00Z -e 2026-03-16T00:00:00Z --agent my-agent

vr experiments funnel

Show the conversion funnel for an experiment, comparing variant performance across each conversion metric with lift calculations.

vr experiments funnel <EXPERIMENT_NAME>

Arguments:

Argument	Description
EXPERIMENT_NAME	Experiment name

Options:

Option	Description
--agent, -a	Agent name or ID (uses agent.lock if omitted)
--json, -j	Output as JSON
--table, -t	Output as table (default for interactive terminals)

Example:

# View conversion funnel for the current project
vr experiments funnel greeting_style

# View funnel for a specific agent
vr experiments funnel greeting_style --agent my-agent

Output includes:

• Total sessions and conversion metrics
• Per-variant breakdown: sessions, conversions, conversion rate, and lift vs baseline

---

.vrignore

You can create a .vrignore file in your project root to exclude files and directories from uploads. It works like .gitignore and applies to both vr push and vr create template.

Example .vrignore:

# Ignore log files
*.log

# Ignore data directory
data/

# Ignore build artifacts
build/**

# Ignore a specific file at root only
/config.local.yaml

# Ignore all .csv files
*.csv

Supported syntax:

Pattern	Description
*.log	Glob pattern — matches any .log file at any depth
secret.txt	Exact name — matches secret.txt in any directory
data/	Trailing / — matches directories only
/config.yaml	Leading / — anchored to project root only
build/**	Globstar — matches everything under build/
**/test.py	Globstar prefix — matches test.py at any depth
# comment	Lines starting with # are ignored

---

vr report

Report issues to VoiceRun.

vr report bug

Subcommands:

Subcommand	Description
bug	Submit a bug report

Options (bug):

Option	Description
--title, -t	Bug title/summary
--description, -d	Bug description
--include-system-info	Include CLI version and OS info (default: true)
--no-system-info	Exclude system information
--dry-run	Show what would be submitted without sending

Examples:

# Interactive mode - prompts for title and description
vr report bug

# Provide title and description inline
vr report bug --title "Login error" --description "Can't log in with SSO"

# Exclude system information
vr report bug --no-system-info

# Dry run - preview what would be submitted
vr report bug --title "Test bug" --dry-run

---

Project Structure

After running vr init, your project will have this structure:

my-agent/
├── handler.py                      # Main agent code (entry point)
├── README.md                       # Project documentation
├── requirements.txt                # Python dependencies
└── .voicerun/                      # Configuration directory
    ├── agent.yaml                  # Agent metadata and configuration
    ├── agent.lock                  # Created after vr push (tracks agent/function IDs)

Templates

agent.yaml

Defines your agent's metadata:

apiVersion: voicerun/v1
name: my-agent
description: "My voice agent description"

handler.py

The main entry point for your agent. Must contain an async def handler() function:

from primfunctions.events import (
    Event, StartEvent, TextEvent, StopEvent, InterruptEvent, TextToSpeechEvent
)
from primfunctions.context import Context

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(text="Hello! How can I help you?")
    elif isinstance(event, TextEvent):
        # Handle user speech transcription
        user_text = event.data.get("text", "")
        yield TextToSpeechEvent(text=f"You said: {user_text}")
    elif isinstance(event, StopEvent):
        pass
    elif isinstance(event, InterruptEvent):
        pass

Links

• VoiceRun Documentation
• Report Issues

License

MIT License

Git Worktrees (Parallel Agent Development)

This repo supports running multiple coding agents in parallel using git worktrees. Each agent gets an isolated working directory with its own branch while sharing the same git object store.

Worktrees are stored in .worktrees/ (gitignored).

Create a worktree

git worktree add .worktrees/feature-xyz -b feature-xyz

List active worktrees

git worktree list

Remove a worktree

git worktree remove .worktrees/feature-xyz

Clean up stale worktrees

git worktree prune