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. Prints a deprecation warning on every run. 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#

Launch the Pipeline Debugger, or place an outbound phone call. Behavior depends on the agent's deployment model:

• Legacy (v1) agents — push local code (unless --skip-push) and debug the per-agent debug environment.
• Declarative (v2) agents (deployed with vr release into org-level environments) — do not push or release. Start a debug session against an existing release: choose it with --release, narrow the interactive picker with -e <environment>, or pick from the list. Non-interactive runs (--yes, piped stdin, or --script) require --release.

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.

All vr get subcommands accept --json/-j and --table/-t for output format (on vr get entrypoints, -t belongs to --type, so use the long form --table). With neither flag, output is a table on an interactive terminal and JSON when piped, redirected, or run by a coding agent. JSON output ({"data": [...]}) carries full, untruncated field values and is the machine-parseable source of truth — tables width-truncate long values such as UUIDs. vr get variables --json returns {"data": {"organizationVariables": [...], "environmentVariables": [...]}}, where environmentVariables is null when the agent-environment scope was not queried. In JSON mode the deprecation warning on agentenvironments is suppressed so stdout stays parseable.

vr describe <resource>#

Show detailed information about a resource.

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

All vr describe subcommands accept --json/-j and --table/-t for output format, with the same auto-detection as vr get. JSON output ({"data": {...}}) always carries complete field values regardless of terminal width; in JSON mode the deprecation warning on agentenvironment is suppressed so stdout stays parseable.

Resource Creation#

vr create environment <NAME>#

Create an org-scoped environment.

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

Create a legacy per-agent environment. Preferred: create an org-scoped environment with vr create environment and bind an agent to it via vr release. Prints a deprecation warning and requires a y/N confirmation before creating; pass --yes/-y to skip it (required in non-interactive shells, which otherwise abort).

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.

vr update telephony <NAME_OR_ID>#

Update a telephony provider's name or credentials in place. Credential updates merge into the stored credentials server-side, so a single-field rotation never wipes the fields you don't pass. Credential flags are validated against the provider's type (e.g. --connection-id on a Twilio row is rejected). At least one option is required.

vr update agent <NAME_OR_ID>#

Update an agent's telephony provider — the provider used for agent-initiated outbound calls (vr outbound call and StartSessionEvent spawns). Accepts a provider name or ID; the reserved platform ids (voicerun, voicerun-sbc[:region]) pass through without lookup.

Context Management#

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

A context bundles an API URL, a frontend URL, and an optional pinned organization, stored together in ~/.voicerun/config.json. If you belong to multiple organizations in the same environment, create one context per org with the same URLs and a different --org. A context without a pinned org sends no organization-id header — the API uses your account's default organization.

To run a single command against another context without switching, use the global --context / -c flag instead of vr context switch — e.g. vr --context staging get agents. It leaves current_context untouched.

Session-scoped switching. When the environment identifies a terminal tab or coding-agent session (first of VOICERUN_SESSION_KEY, CLAUDE_CODE_SESSION_ID, ITERM_SESSION_ID, TERM_SESSION_ID, WT_SESSION), vr context switch applies only to that session, so concurrent sessions on one machine never clobber each other's context. Resolution order: --context/VOICERUN_CONTEXT → the session's own switch → the machine-wide current_context. Session entries live in ~/.voicerun/sessions/ and clean themselves up (entries idle >7 days are pruned on the next switch; 100-entry cap). vr context current shows the resolution source: local (session), staging (override), or default (global).

Note: Claude Code subagents share the top-level session's CLAUDE_CODE_SESSION_ID, so they share its pin — a switch inside one subagent changes the context for the parent session and all sibling subagents. Subagents that need their own context should pass --context <name> on every command instead of switching.

vr context switch vs vr context switch --global#

Plain vr context switch <name> picks the narrowest scope available:

• Inside an identifiable session (a Claude Code session, an iTerm/Terminal.app tab, Windows Terminal, or a shell that exports VOICERUN_SESSION_KEY), the switch pins the context for that session only. The machine-wide current_context is untouched, so nothing changes for any other terminal or agent.
• Outside one (no session env var — e.g. a bare SSH shell or CI), the same command sets the machine-wide context, exactly as it always has.

vr context switch <name> --global (or -g) always sets the machine-wide context: the default that every session without its own pin resolves, including sessions opened in the future. It also clears the running session's own pin — otherwise your pin would shadow the global you just set and the switch would appear not to take effect where you ran it.

# Terminal tab A — pins 'local' for this tab only
vr context switch local

# Terminal tab B, concurrently — pins 'staging'; tab A is unaffected
vr context switch staging

# Either tab — sets the machine-wide default for everything un-pinned
# (new tabs, scripts, cron) and re-points this tab at it too
vr context switch development --global

# Check which scope your context came from
vr context current        # e.g. "Context: local (session)" or "development (global)"

Rule of thumb: day-to-day, just use vr context switch — the session scoping makes it safe. Reach for --global when you mean "change the default for this machine," not "change it for me right now."

Unset state. After vr context unset, any command that needs the API prints and exits with code 1:

No context is set.
Pass --context <name>, run 'vr context switch <name>', or set VOICERUN_CONTEXT
Available contexts: local, development, default

This is useful when several sessions or coding agents share one machine and none of them should inherit an ambient context — each invocation must name its target. Fresh installs that never set a context still resolve to default; the fail-closed behavior only applies after an explicit vr context unset.

Session Observability#

vr session list [AGENT]#

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

Both date bounds are inclusive and filter on session creation time. Either can be used alone; when both are provided, --from must be earlier than --to.

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#

Submit bug reports and track them from the CLI: see status, read replies from the VoiceRun team, and respond. You are also notified in the web app (and by email, per your notification preferences) when your ticket gets a reply or changes status.

vr report bug#

Submit a bug report to VoiceRun.

vr report list#

List your submitted bug reports.

vr report show#

Show one bug report with its full conversation — replies (yours and VoiceRun Support's) interleaved with status-change entries.

vr report show <ticket-id>

JSON output bundles the ticket and its conversation as {data, comments}.

vr report reply#

Reply on one of your bug reports. Prompts for the message when it isn't passed as an argument.

vr report reply <ticket-id> "Still happening on the latest version"

Replying to a resolved or closed ticket re-opens it — the command says so in its output, and JSON output carries a reopened flag plus the current ticketStatus.

All vr report read/reply subcommands accept --json / --table.

Configuration Files#

Credentials#

Credentials are stored in ~/.voicerun/: