Resource Management

The VoiceRun CLI provides commands for managing all platform resources: agents, functions, environments, variables, secrets, phone numbers, telephony providers, and templates.

Listing Resources#

Use vr get to list resources:

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 --org                                # List organization variables
vr get variables --agent <agent> --environment <env>  # List agent environment variables
vr get secrets                                        # List organization secrets (evaluator use)
vr get phonenumbers                                   # List organization phone numbers
vr get telephony                                      # List telephony providers
vr get assignments <agent>                            # List phone number assignments
vr get templates                                      # List available templates

The <agent> argument accepts either an agent name or ID.

Viewing Resource Details#

Use vr describe to see detailed information about a specific resource:

vr describe agent <name-or-id>
vr describe function <agent> <name-or-id>
vr describe environment <agent> <name-or-id>
vr describe variable <name-or-id>
vr describe variable <name-or-id> --agent <agent> --environment <env>
vr describe secret <name-or-id>
vr describe phonenumber <id>
vr describe telephony <name-or-id>
vr describe assignment <phone-number>

The <phone-number> argument for vr describe assignment accepts a phone number ID, the phone number itself (e.g. +14155551234), or the friendly name.

Creating Resources#

Variables#

Variables are the values your agent reads at runtime via context.variables.get(NAME). They're merged from two scopes at session start: organization-level (visible to every agent) and agent environment-level (scoped to a specific environment like production or staging).

# Organization-level variable (visible to every agent in the org)
vr create variable SUPPORT_EMAIL help@acme.com --org

# Environment-scoped variable for a specific agent + environment
vr create variable ANTHROPIC_API_KEY sk-ant-... \
    --agent my-agent --environment production --masked

# Inside a voicerun project, --agent defaults to agent.lock
vr create variable ANTHROPIC_API_KEY sk-ant-... --environment production --masked

Use --masked for sensitive values like API keys. The runtime still receives the real value, so context.variables.get("ANTHROPIC_API_KEY") works as expected; only listings and the UI redact it.

In your handler:

async def handler(event, context):
    api_key = context.variables.get("ANTHROPIC_API_KEY")
    support_email = context.variables.get("SUPPORT_EMAIL", "help@example.com")

See the Context Reference for the full runtime behavior including scope merge precedence.

Secrets#

Secrets are currently evaluator-only. They are not yet injected into context.variables at runtime — if you want a value readable from an agent handler, use variables with --masked instead. Runtime injection of agent-scoped secrets is on the roadmap.

Create organization-level secrets for use by evaluators:

vr create secret API_KEY sk-abc123    # Organization secret (evaluator use)

Passing --agent to vr create secret exits non-zero with a redirect to vr create variable --masked.

Phone Numbers#

Register an existing phone number or purchase a new one:

vr create phonenumber --phone-number +15551234567           # Register existing number
vr create phonenumber --purchase --area-code 415            # Purchase new number
vr create phonenumber <telephony-id> --purchase -a 212 -c US  # From specific provider

Phone Number Assignments#

Assign a phone number to an agent environment:

vr create assignment <agent> <environment> <phone-number-id>
vr create assignment <agent> <environment> <phone-number-id> --configure

Under the hood, this updates agentId and agentEnvironmentId on the phone number. There is no separate assignment record — a phone number is its assignment.

The --configure flag also configures the phone number with the telephony provider after assignment, so incoming calls actually route to the agent. Without --configure, the assignment exists in the VoiceRun database but the provider side is not wired up.

If you omit the <agent> argument, the agent is resolved from .voicerun/agent.lock in the current directory.

List assignments for an agent:

vr get assignments <agent>

View assignment details for a specific phone number:

vr describe assignment <phone-number>

Telephony Providers#

Connect a Twilio or Telnyx account:

vr create telephony

Without flags, this runs interactively. You can also provide all values via flags:

vr create telephony --name "My Twilio" --provider-type twilio \
  --account-sid AC123 --api-key-sid SK123 --api-key-secret secret123

vr create telephony --name "My Telnyx" --provider-type telnyx --api-key KEY123

Templates#

Create a reusable template from your current project:

vr create template my-template
vr create template my-template --description "Restaurant booking agent" --category booking --public

Deleting Resources#

Use vr delete to remove resources:

vr delete agent <name-or-id>
vr delete function <agent> <name-or-id>
vr delete environment <agent> <name-or-id>
vr delete variable <name-or-id> --org
vr delete variable <name-or-id> --agent <agent> --environment <env>
vr delete secret <name-or-id>
vr delete phonenumber <name-or-id>
vr delete phonenumber <name-or-id> --release    # Release back to provider
vr delete telephony <name-or-id>
vr delete assignment <phone-number>
vr delete assignment <phone-number> --skip-unconfigure

The --release flag on vr delete phonenumber releases the number back to the telephony provider instead of just removing it from VoiceRun.

vr delete assignment unconfigures the phone number with the telephony provider, then clears agentId and agentEnvironmentId. The phone number itself is preserved in your organization and can be reassigned to another agent. Pass --skip-unconfigure to skip the provider-side unconfigure step (useful if the provider is already in a clean state).