Project Management

The VoiceRun CLI provides commands for the full project lifecycle: creating new agent projects, validating configuration, pushing code, and deploying to environments.

Creating a Project#

Scaffold a new voice agent project with vr init:

vr init my-agent

This creates the following project structure:

my-agent/
├── handler.py              # Main agent code (entry point)
├── requirements.txt        # Python dependencies
├── README.md               # Project documentation
├── .gitignore              # Git ignore rules
└── .voicerun/
    └── agent.yaml          # Agent metadata (name, description)

Options#

Using Templates#

Initialize from a shared template:

vr init my-agent --template restaurant-booking
vr init my-agent --template restaurant-booking --var language=spanish --var region=us

List available templates:

vr get templates

Validating a Project#

Check that your project structure and configuration are correct:

vr validate

Validation checks include:

• handler.py exists and contains async def handler()
• .voicerun/ directory structure is correct
• agent.yaml is valid with required fields

Use --quiet to only show errors.

Pushing Code#

Upload your agent code to VoiceRun:

vr push

The first push creates a new agent and function on the server. Subsequent pushes update the existing function version. Use --new to create a new function version instead of updating.

After pushing, an agent.lock file is created in .voicerun/ to track the agent and function IDs.

.vrignore#

Control which files are excluded from the push with a .vrignore file (works like .gitignore):

# Exclude test files
tests/
*_test.py

# Exclude data directories
data/
*.csv

# Exclude build artifacts
__pycache__/
*.pyc

The following are always excluded: .venv, __pycache__, .git.

Pulling Code#

Download agent code from the server to your local machine:

vr pull                    # Inside a project (uses agent.lock)
vr pull AGENT_ID           # Outside a project
vr pull AGENT_ID -o ./dir  # Specify output directory

Deploying#

Deploy your agent to a specific environment:

vr deploy development
vr deploy production

Push your code first with vr push.

Opening the Dashboard#

Open your agent's page in the VoiceRun web dashboard:

vr open

Requires agent.lock (created after vr push).