Command Reference

Complete reference for all VoiceRun CLI commands.

Agent auto-resolution: commands that take an AGENT argument can infer it automatically when run inside a project directory (one with .voicerun/agent.lock). In those cases the AGENT argument is optional and marked [AGENT].

Global Options#

Setup & Authentication#

vr setup#

Configure the CLI environment and install dependencies.

vr signin#

Sign in to VoiceRun. Validates against /v1/auth/principal so the same flow works for user-scoped tokens and organization service account tokens (vrst_…).

vr signout#

Sign out and clear stored credentials.

Project Lifecycle#

vr init [PROJECT_NAME]#

Create a new voice agent project. Runs an interactive wizard unless --yes is supplied.

vr validate#

Validate project structure, configuration, and (optionally) rendered templates.

vr render#

Render .voicerun/templates/ with Helm and print the result. Also runs spec validation on the output.

vr push#

Push agent code to VoiceRun. If the function recorded in .voicerun/agent.lock has already been deployed, the push creates a new function version automatically and updates agent.lock; deployed environments continue serving the old immutable version until you release or deploy the new one.

vr pull [AGENT_ID]#

Pull agent code from the server.

vr release [AGENT] <ENVIRONMENT>#

Bind an agent + function to an org-scoped environment with a snapshotted manifest. The latest release for (agent, environment) is implicitly active.

vr deploy <ENVIRONMENT> (legacy)#

Deploy a function to a legacy per-agent environment. Preserved for agents created before the release/entrypoint migration — new projects should use vr release. The command waits while the API prewarms the sandbox module and shows a Deploying and prewarming sandbox... spinner; if prewarm fails, the first call builds on demand.

vr open#

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

Development#

vr debug#

Push code and launch the Pipeline Debugger, or place an outbound phone call.

vr test [TEST_PATH]#

Run tests for the agent project.

Pass additional pytest arguments after --:

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

vr simulate [AGENT] <ENVIRONMENT>#

Run a Simulation resource against the active release.

Outbound Calls#

vr outbound call <ENTRYPOINT>#

Originate an outbound call from a phone-type entrypoint with direction set to outbound or both. The session is created up-front and a TwiML stream is built inline so the call connects straight to the agents service on pickup with no intermediate API round-trip.

The handler reads the task spec via context.input_data and, before session end, builds a structured result via context.set_output(...) / context.update_output(...). The result lives on the session as outputData and is retrievable via vr session info, --wait, or the session-end webhook.

The from-number is always the entrypoint's configured phoneNumber — the entrypoint is the persona for the number, and the API does not accept a per-call override.

--input and --input-file are mutually exclusive. The payload must be a JSON object at the top level (not an array or scalar) and is capped at 64KB.

# Fire-and-forget — returns immediately with sessionId.
vr outbound call ep_outbound_callback \
    --to +15553334444 \
    --input '{"task_id":"t-7","objective":"Confirm 7pm reservation"}'

# Wait for the call to finish and print the handler's outputData.
vr outbound call ep_outbound_callback \
    --to +15553334444 \
    --input-file ./task.json \
    --wait --timeout 180

# Pin a specific release for testing.
vr outbound call ep_outbound_callback \
    --to +15553334444 \
    --release rel_abc123 \
    --wait

Exit codes:

• 0 — call originated successfully (no --wait), or session completed (with --wait).
• 1 — origination failed, or the session ended in failed status.
• 2 — --wait timed out before the session reached a terminal state.

Resource Queries#

vr get <resource>#

List resources. Every command takes an optional positional filter that narrows the table to one matching row.

vr get releases accepts --agent/-a and --environment/-e. vr get entrypoints accepts --type/-t (phone, web, native). vr get variables accepts --agent/-a, --environment/-e, and --org.

vr describe <resource>#

Show detailed information about a resource.

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

Resource Creation#

vr create environment <NAME>#

Create an org-scoped environment.

vr create agentenvironment [AGENT] <NAME> (legacy)#

Create a legacy per-agent environment.

vr create entrypoint phone|web|native|update#

Create an entrypoint that routes traffic to one or more releases. Each create variant accepts --release <releaseId>[:<weight>] (repeatable, optional — defaults to weight 1; omit entirely to create a release-less entrypoint).

vr create entrypoint phone <NAME>

vr create entrypoint web <NAME>

vr create entrypoint native <NAME>

vr create entrypoint update <ENTRYPOINT_ID> (deprecated)

Deprecated alias for vr update entrypoint. Prints a warning and forwards to the new command — switch over when you can.

vr create variable <NAME> <VALUE>#

Create a variable readable via context.variables.get(NAME) in agent handlers.

vr create secret <NAME> <VALUE>#

Create an organization-scoped secret in GCP Secret Manager. Reference it from .voicerun/templates/ as {{ Secrets.organization.NAME }} — Helm leaves the placeholder intact and the API resolves it at session start. Passing --agent is rejected with a redirect to vr create variable --masked.

vr create phonenumber [TELEPHONY_ID]#

Create or purchase a phone number.

vr create assignment [AGENT] <ENVIRONMENT> <PHONE_NUMBER_ID> (legacy)#

Assign a phone number to a legacy per-agent environment. Sets agentId and agentEnvironmentId on the phone number.

vr create telephony#

Create a telephony provider. Missing fields are prompted interactively.

vr create template <NAME>#

Create a reusable template from the current project. agent.lock is excluded automatically.

Resource Deletion#

vr delete <resource>#

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.

Resource Updates#

vr update is the home for in-place resource mutations that don't fit a create/delete flow. (The global vr --update flag still upgrades the CLI itself.)

vr update entrypoint <ENTRYPOINT_ID>#

Update an existing entrypoint's routing or metadata in place. Passing --release replaces the entire routing list (it is not an append). At least one of --release, --name, or --status must be provided.

Context Management#

vr context with no subcommand prints the current context, signed-in user, organization, and admin status.

Session Observability#

vr session list [AGENT]#

List sessions for an agent. Resolves the agent from .voicerun/agent.lock when omitted.

vr session info <SESSION_ID>#

Show detailed information for a session.

vr session trace <SESSION_ID>#

Show session trace as a span tree.

vr session span <SESSION_ID> <SPAN_ID>#

Show detailed information for a specific span.

vr session transcript [AGENT] <SESSION_ID>#

Show transcript events for a session. The AGENT argument is optional when run from inside a project directory — the agent is inferred from .voicerun/agent.lock.

vr session events [AGENT] <SESSION_ID>#

Show raw session events. The AGENT argument is optional when run from inside a project directory — the agent is inferred from .voicerun/agent.lock.

vr session recording <SESSION_ID>#

Download the WAV recording for a session.

All vr session subcommands accept --json/-j and --table/-t for output format.

Evaluations#

vr evaluation list [AGENT]#

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

vr evaluation info <EVALUATION_ID>#

Show detailed information about an evaluation. Renders one of four result panels depending on the row:

• Judge Result — success flag, ruling JSON, success criteria
• Extraction Result — the extracted payload
• Deterministic Result — success flag, assertion predicate, structured details ({ matched, failedPath?, reason? })
• Skipped — the precondition reason; no per-type result panel since the eval never ran

Custom Metrics#

vr metrics names [AGENT]#

List available custom metric names.

vr metrics tags#

Discover available tag keys and their values for filtering.

vr metrics timeseries <METRIC_NAME>#

Fetch time-series data for a custom metric.

vr metrics session <SESSION_ID>#

Fetch all custom metrics for a specific session.

A/B Experiments#

vr experiments list#

List all experiments for an agent.

vr experiments describe <EXPERIMENT_NAME>#

Show detailed results for a specific experiment (session count, variants, conversion rates, statistical significance).

vr experiments timeseries <EXPERIMENT_NAME>#

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

vr experiments funnel <EXPERIMENT_NAME>#

Show the conversion funnel for an experiment, comparing variants with per-metric lift.

All vr metrics and vr experiments subcommands accept --json / --table.

Usage Reporting#

vr usage report#

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

vr usage monthly#

Show usage report for a specific month.

Documentation Browser#

vr docs topics#

List all available documentation topics.

vr docs topic <NAME>#

List pages within a documentation topic.

vr docs read <SLUG>#

Read the full content of a documentation page.

vr docs search "<QUERY>"#

Search documentation using natural language.

All vr docs subcommands accept --json / --table.

Bug Reports#

vr report bug#

Submit a bug report to VoiceRun.

Configuration Files#

Credentials#

Credentials are stored in ~/.voicerun/: