docs.VoiceRun

VoiceRun CLI

The VoiceRun CLI (vr) is a command-line tool for creating, testing, deploying, and managing voice agents. It covers the full developer workflow — from scaffolding a project, to pushing code, to releasing it into an org-scoped environment, to routing traffic through entrypoints.

It also includes tooling for declarative resources (deployments, simulations, evaluators, webhooks), observability (sessions, traces, recordings), custom metrics, A/B experiments, and usage reporting.

Version: 1.6.0

Installation#

Prerequisites#

  • Python 3.10+
  • uv (recommended) or pip
  • Helm for projects that use .voicerun/templates/ (installable via vr setup)
  • Node.js — required by vr debug to launch the Pipeline Debugger

Via uv#

uv tool install voicerun-cli

Via pip#

pip install voicerun-cli

Verify Installation#

vr --version

Setup#

After installing, run the setup command to configure your environment:

vr setup

This installs required dependencies and configures integrations:

  • uv — Python package manager (used for agent projects)
  • Helm — required to render .voicerun/templates/ at vr release time
  • Skills — Claude Code / Codex / OpenClaw skills for AI-assisted development
  • MCP server — Editor integration for Claude Code, Cursor, Codex, and Windsurf

You can skip individual steps or target specific editors:

vr setup --skip-uv                 # Skip uv installation
vr setup --skip-helm               # Skip Helm installation
vr setup --skip-skills             # Skip skills installation
vr setup --skip-mcp                # Skip MCP server configuration
vr setup --claude-code             # Install skills/MCP to Claude Code only
vr setup --codex                   # Install skills/MCP to Codex only
vr setup --openclaw                # Install skills to OpenClaw only
vr setup --cursor                  # Configure MCP for Cursor only
vr setup --windsurf                # Configure MCP for Windsurf only

Authentication#

Sign in to your VoiceRun account:

vr signin

Authentication supports three methods:

  • Browser (default) — Opens a browser window for OAuth sign-in
  • Email/Password — Non-interactive sign-in with --email and --password
  • API Key — Non-interactive sign-in with --api-key. Works with both user-scoped personal access tokens and organization service account tokens (vrst_…).
vr signin --api-key YOUR_API_KEY
vr signin --email user@example.com --password yourpassword

To sign out and clear stored credentials:

vr signout

After signing in, your effective organization context is shown automatically. If you belong to multiple organizations, switch with:

vr context set-org <org-name-or-id>

Updating#

Update the CLI to the latest version and refresh installed skills and MCP configurations:

vr --update

Only the targets that were explicitly chosen during vr setup are refreshed — no extra prompts.

A typical workflow#

vr init my-agent              # Scaffold a project
cd my-agent
vr signin                     # Authenticate
# ...edit handler.py and .voicerun/templates/deployment.yaml...
vr validate                   # Check structure + template specs
vr push                       # Upload code to VoiceRun
vr debug                      # Test interactively in the Pipeline Debugger
vr release production \       # Bind agent + function to an org environment
  --entrypoint support-line   # ...and route traffic via an entrypoint

Next Steps#

overviewcliinstallationsetup