Skip to content

VirtualProg CLI (vpvm)

Command-Line Interface for VirtualProg Virtual Machine Manager

The vpvm command-line tool provides powerful automation and scripting capabilities for managing your virtual machines in VirtualProg. Control your VMs from the terminal, integrate with scripts, and automate your workflow — locally or on a remote machine.

🚀 Overview

The VirtualProg CLI (vpvm) enables you to:

  • Start, stop, and control virtual machines from the terminal
  • Create and manage snapshots and templates
  • Check VM status and list all available VMs
  • Automate workflows with shell scripts
  • Integrate with CI/CD pipelines and automation tools
  • Control remote instances of VirtualProg over the network

The CLI communicates with the VirtualProg app via a local HTTP API, ensuring seamless integration between GUI and command-line operations.

📥 Installation

  • Download the vpvm cli using Download Command Line from Top Help Menu
  • Download the vpvm cli from https://makeprog.com/Products/VirtualProg/vpvm.zip and place it in a directory of your choice.
  • Unzip the archive and move the vpvm binary to a directory in your $PATH.

Adding to PATH (Optional)

For easier access, you can add vpvm to your system PATH:

# Add to your ~/.zshrc or ~/.bash_profile
export PATH="$PATH:{vpvm cli location}"

📋 Command Reference

General Syntax

vpvm <command> [--server <host>] [--port <port>] [--secure] [--token <token>] [arguments]

The --server, --port, --secure and --token flags are optional and apply per-command. When omitted, vpvm connects to the local machine VirtualProg instance using its configured settings.

Available Commands and Subcommands

  • list — List all virtual machines
  • info <vmname> — Info about VM
  • stats <vmname> — Statistics about VM Usage
  • start <vmname> — Start a VM (comma-separated names to start multiple)
  • stop <vmname> — Force stop a VM (comma-separated names to stop multiple)
  • shutdown <vmname> — Gracefully shutdown a VM (comma-separated names to shutdown multiple)
  • pause <vmname> — Pause a VM (comma-separated names to pause multiple)
  • resume <vmname> — Resume a VM (comma-separated names to resume multiple)
  • suspend <vmname> — Suspend a VM to disk (comma-separated names to suspend multiple)
  • restart <vmname> — Restart a VM (comma-separated names to restart multiple)
  • delete <vmname> — Delete a VM
  • clone <vmname> <newname> — Clone a VM
  • rename <vmname> <newname> — Rename a VM
  • status <vmname> — Get VM status (comma-separated names to check multiple)
  • configure <vmname> [--cpu <count>] [--memory <mb>] — Change CPU count and/or memory of a stopped VM
  • snapshot — Manage VM snapshots (subcommands: list, create, restore, delete)
  • template — Manage VM templates (subcommands: list, info, create, delete)
  • vm — Create a VM from a template (subcommand: create)
  • network — Get info about. custom networks (subcommands: list, info)

Examples

vpvm list
vpvm start ubuntu-22.04
vpvm stop ubuntu-22.04
vpvm snapshot list ubuntu-22.04
vpvm snapshot create ubuntu-22.04 before-update
vpvm template list
vpvm template create ubuntu-22.04 "My Template"
vpvm vm create "My Template" new-vm

🆕 Getting Help

You can view detailed help for any command or subcommand using the --help flag:

vpvm --help
vpvm snapshot --help
vpvm snapshot create --help
vpvm template --help

This will display all available options, arguments, and descriptions for each command.

📖 Detailed Usage

Starting a Virtual Machine

Start a stopped VM or resume a paused/suspended VM:

vpvm start ubuntu-22.04

Output: 

Request completed successfully.
Started ubuntu-22.04

Note: If the VM is paused or suspended, you'll be prompted to use the resume command instead.

Stopping a Virtual Machine

Force stop a running VM (equivalent to pulling the power plug):

vpvm stop ubuntu-22.04

Output: 

Request completed successfully.
Stopped ubuntu-22.04

⚠️ Warning: This performs a hard shutdown. Use shutdown for graceful shutdown.

Graceful Shutdown

Gracefully shutdown a running VM (sends ACPI shutdown signal):

vpvm shutdown ubuntu-22.04

Output: 

Request completed successfully.
Shutdown ubuntu-22.04

✅ Recommended: Always use shutdown instead of stop to avoid data corruption.

Pausing and Resuming

Pause a running VM (freezes execution):

vpvm pause ubuntu-22.04

Resume a paused VM:

vpvm resume ubuntu-22.04

Use Cases: - Temporarily free up CPU resources - Quick pause/resume without full shutdown - Preserve exact VM state

Suspending a Virtual Machine

Suspend VM to disk (saves memory state):

vpvm suspend ubuntu-22.04

Benefits: - Saves RAM contents to disk - Instant resume later - No VM boot time required

Resume: 

vpvm resume ubuntu-22.04

Checking VM Status

Get the current state of a virtual machine:

vpvm status ubuntu-22.04

Possible States: - running - VM is currently running - stopped - VM is stopped - paused - VM is paused - suspended - VM is suspended to disk

Example Output: 

Request completed successfully.
running

Bulk Operations on Multiple VMs

The start, stop, shutdown, pause, resume, suspend, restart, and status commands all accept a comma-separated list of VM names, so you can act on multiple VMs in a single command.

# Start multiple VMs at once
vpvm start ubuntu-22.04,debian-12,macos-sonoma

# Shutdown multiple VMs
vpvm shutdown ubuntu-22.04,debian-12

# Check status of several VMs
vpvm status ubuntu-22.04,debian-12,macos-sonoma

Multi-VM output — each VM is listed on its own line with its result:

ubuntu-22.04: Started ubuntu-22.04
debian-12: Started debian-12
macos-sonoma: error – VM is already running

For status, each line shows the current state:

ubuntu-22.04: running
debian-12: stopped
macos-sonoma: running

VM names with spaces — wrap the whole comma-separated string in quotes:

vpvm start "My Dev VM,Work VM,Test VM"

Note: delete, clone, rename, and configure remain single-VM commands — bulk execution is intentionally not supported for destructive or two-argument operations.

Listing All Virtual Machines

Display all available VMs:

vpvm list all

Output: 

Request completed successfully.
ubuntu-22.04,macos-sonoma,debian-12,test-vm

Cloning a Virtual Machine

Create a copy of an existing VM:

vpvm clone ubuntu-22.04 ubuntu-dev

Output: 

Request completed successfully.
Cloning ubuntu-22.04 to ubuntu-dev

Requirements: - Source VM must be stopped - New VM name must be unique - Sufficient disk space required

Use Cases: - Create development/testing environments - Duplicate VM configurations - Quick VM provisioning

Deleting a Virtual Machine

Permanently delete a VM:

vpvm delete test-vm

Output: 

Request completed successfully.
Deleted test-vm

⚠️ Warning: This action cannot be undone. The VM and all its data will be permanently deleted.

Requirements: - VM must be stopped - VM must not be password protected

Configuring VM Hardware (CPU & Memory)

Adjust the CPU count and/or memory allocation for a stopped VM:

vpvm configure ubuntu-22.04 --cpu 4 --memory 8192

Change only one setting at a time:

# Change CPU only
vpvm configure ubuntu-22.04 --cpu 2

# Change memory only (in MB)
vpvm configure ubuntu-22.04 --memory 4096

Output: 

Request completed successfully.
VM 'ubuntu-22.04' updated: cpu=4 memory=8192MB

Requirements: - VM must be fully stopped (not paused or suspended) - At least one of --cpu or --memory must be provided - Memory is specified in megabytes (MB)

Verify the change: 

vpvm info ubuntu-22.04

📸 Working with Snapshots

Snapshots allow you to capture and restore VM states at specific points in time. Learn more about snapshots in the Snapshots documentation.

Creating a Snapshot

Capture the current state of a VM:

vpvm snapshot create ubuntu-22.04 backup-before-update

Output: 

Request completed successfully.
Creating snapshot backup-before-update for ubuntu-22.04

Requirements: - VM must be stopped (not paused or suspended) - Snapshot name must be unique for that VM - Sufficient disk space required

Best Practices: - Create snapshots before major updates - Use descriptive names (include dates or purposes) - Don't rely on snapshots for long-term backups

Listing Snapshots

View all snapshots for a specific VM:

vpvm snapshot list ubuntu-22.04

Output: 

Request completed successfully.
clean-install,backup-before-update,pre-kernel-upgrade

Restoring a Snapshot

Revert a VM to a previous snapshot state:

vpvm snapshot restore ubuntu-22.04 backup-before-update

Output: 

Request completed successfully.
Restoring snapshot backup-before-update for ubuntu-22.04

⚠️ Warning: This will overwrite the current VM state. Current data will be lost unless you create a snapshot first.

Requirements: - VM must be stopped - Snapshot must exist

Deleting a Snapshot

Remove a snapshot to free up disk space:

vpvm snapshot delete ubuntu-22.04 old-snapshot

Output: 

Request completed successfully.
Deleted snapshot old-snapshot for ubuntu-22.04

📦 Working with Templates

Templates enable quick VM deployment from pre-configured states. Learn more in the Templates documentation.

Creating a Template

Create a reusable template from an existing VM:

vpvm template create ubuntu-22.04 "Ubuntu 22.04 Base"

Output: 

Request completed successfully.
Creating template Ubuntu 22.04 Base from ubuntu-22.04

Requirements: - VM must be stopped (not paused or suspended) - VM must not be password protected - Template name must be unique

Best Practices: - Create templates from clean, configured VMs - Include software and settings you frequently use - Document what's included in template notes (via GUI)

Listing Templates

View all available templates:

vpvm template list

Output: 

Request completed successfully.
Ubuntu 22.04 Base,macOS Sonoma Clean,Debian 12 Dev

Deleting a Template

Remove a template you no longer need:

vpvm template delete "Old Template"

Output: 

Request completed successfully.
Deleted template Old Template

🔧 Advanced Usage

Remote Access

By default, vpvm connects to VirtualProg running on the same Mac. Use the following flags on any command to target a remote VirtualProg instance:

Flag Description Default
--server <host> IP address or hostname of the remote machine 127.0.0.1
--port <port> Port the VirtualProg CLI server is listening on Configured in VirtualProg settings
--token <token> Authentication token Configured in VirtualProg settings

Requirements for remote access:

  • The CLI Server must be enabled in VirtualProg settings on the remote machine
  • External Access must be enabled if connecting from a different machine
  • The token must match the one configured in VirtualProg settings on the remote machine

Examples:

# List VMs on a remote machine
vpvm list --server 192.168.1.10 --port 49152 --token mytoken

# Start a VM on a remote machine
vpvm start my-vm --server 192.168.1.10 --port 49152 --token mytoken

# Check status on a remote machine
vpvm status my-vm --server 192.168.1.10 --token mytoken

When any remote flag is provided, vpvm skips the local VirtualProg auto-launch check — the remote instance is assumed to be already running.

Shell Scripting

Automate VM management with shell scripts. You can use comma-separated names for concise multi-VM commands:

# Start several VMs in one command
vpvm start web-server,database,cache

Or loop when logic per-VM is needed:

#!/bin/bash
# Start development VMs with a delay between each

VMS=("web-server" "database" "cache")

for vm in "${VMS[@]}"; do
    echo "Starting $vm..."
    vpvm start "$vm"
    sleep 2
done

echo "All development VMs started!"

Checking VM State Before Operations

#!/bin/bash
VM_NAME="ubuntu-22.04"

STATUS=$(vpvm status "$VM_NAME" | tail -n 1)

if [ "$STATUS" == "running" ]; then
    echo "VM is already running"
    exit 0
fi

echo "Starting VM..."
vpvm start "$VM_NAME"

Automated Snapshot Workflow

#!/bin/bash
# Create daily snapshot before starting work

VM="dev-machine"
DATE=$(date +%Y-%m-%d)
SNAPSHOT="daily-$DATE"

echo "Creating snapshot: $SNAPSHOT"
vpvm snapshot create "$VM" "$SNAPSHOT"

echo "Starting VM..."
vpvm start "$VM"

Batch VM Operations

Shutdown a known set of VMs in one command:

vpvm shutdown web-server,database,cache

Stop all currently running VMs dynamically:

#!/bin/bash
# Get list of all VMs and shut down any that are running
VMS=$(vpvm list all | tail -n 1 | tr ',' ' ')

for vm in $VMS; do
    STATUS=$(vpvm status "$vm" | tail -n 1)
    if [ "$STATUS" == "running" ]; then
        echo "Shutting down $vm..."
        vpvm shutdown "$vm"
        sleep 5
    fi
done

echo "All VMs shut down!"

📊 Error Handling

Common Errors and Solutions

VM Does Not Exist

Request errored.
VM 'vmname' does not exist

Solution: Check VM name with vpvm list all and ensure correct spelling.

VM Already Running

Request errored.
VM is already running

Solution: Check status with vpvm status <vmname> before starting.

VM Not Running

Request errored.
VM is not running

Solution: Start the VM first with vpvm start <vmname>.

Password Protected VM

Request errored.
VM is password protected

Solution: Remove password protection via VirtualProg GUI before using CLI.

VM Must Be Stopped

Request errored.
Please stop the VM before <operation>

Solution: Use vpvm shutdown <vmname> or vpvm stop <vmname> first.

Template Already Exists

Request errored.
Template with name 'templatename' already exists

Solution: Use a different template name or delete the existing template first.

Snapshot Not Found

Request errored.
Snapshot 'snapshotname' not found

Solution: List available snapshots with vpvm snapshot list <vmname>.

🔄 Integration with VirtualProg GUI

The CLI seamlessly integrates with the VirtualProg GUI:

  • Auto-launch: If VirtualProg is not running, vpvm automatically launches it
  • Live updates: Changes made via CLI are reflected in the GUI
  • Event notifications: Both CLI and GUI operations trigger system notifications
  • Shared state: All operations work on the same VM data

Note: The VirtualProg app must remain running for CLI commands to work (it will auto-launch if not running).

🎯 Best Practices

Do's ✅

  • Always use shutdown instead of stop for graceful VM shutdown
  • Create snapshots before risky operations (updates, configuration changes)
  • Use descriptive names for VMs, snapshots, and templates
  • Check VM status before performing operations
  • Test scripts with non-critical VMs first
  • Keep template names unique and descriptive

Don'ts ❌

  • Don't use stop unless absolutely necessary (risks data corruption)
  • Don't delete snapshots/templates without verification
  • Don't clone or snapshot password-protected VMs (remove protection first)
  • Don't run operations on VMs that are paused/suspended (stop or resume first)
  • Don't rely solely on CLI - use GUI for complex configurations

🛠️ Troubleshooting

VirtualProg Not Responding

If CLI commands hang or don't respond:

  1. Check if VirtualProg is running: ps aux | grep VirtualProg
  2. Restart VirtualProg from Applications
  3. Check system logs for errors
  4. Contact support if issues persist

HTTP Server Not Available

The CLI uses an HTTP server on localhost. If you get connection errors:

  1. Verify VirtualProg is running
  2. Check HTTP port settings in VirtualProg preferences
  3. Ensure no firewall is blocking localhost connections

Performance Issues

If CLI commands are slow:

  1. Close unused VMs to free resources
  2. Check system disk space
  3. Restart VirtualProg to clear cache
  4. Consider upgrading hardware for better performance

💡 Tips and Tricks

Quick Status Check

Create a shell alias for quick VM status:

# Add to ~/.zshrc or ~/.bash_profile
alias vmstatus='vpvm status'

Usage: vmstatus ubuntu-22.04

VM Management Dashboard

Create a simple dashboard script:

#!/bin/bash
echo "=== VirtualProg VM Status ==="
VMS=$(vpvm list all | tail -n 1 | tr ',' ' ')

for vm in $VMS; do
    status=$(vpvm status "$vm" | tail -n 1)
    printf "%-20s : %s\n" "$vm" "$status"
done

Automated Backup Workflow

#!/bin/bash
# Weekly snapshot backup script

VM="production-vm"
WEEK=$(date +%U)
SNAPSHOT="week-$WEEK-backup"

# Stop VM
vpvm shutdown "$VM"
sleep 10

# Create snapshot
vpvm snapshot create "$VM" "$SNAPSHOT"

# Start VM
vpvm start "$VM"

echo "Weekly backup completed: $SNAPSHOT"

📬 Support

Need help with the CLI?

📝 Examples Quick Reference

Basic Operations

# List all VMs
vpvm list

# Start a VM
vpvm start ubuntu-22.04

# Start multiple VMs at once (comma-separated)
vpvm start ubuntu-22.04,debian-12,macos-sonoma

# Check status
vpvm status ubuntu-22.04

# Check status of multiple VMs
vpvm status ubuntu-22.04,debian-12

# Get detailed VM info
vpvm info ubuntu-22.04

# Graceful shutdown
vpvm shutdown ubuntu-22.04

# Shutdown multiple VMs
vpvm shutdown ubuntu-22.04,debian-12

# Stop (force)
vpvm stop ubuntu-22.04

Pause/Resume/Suspend

# Pause VM
vpvm pause ubuntu-22.04

# Resume VM
vpvm resume ubuntu-22.04

# Suspend to disk
vpvm suspend ubuntu-22.04

Snapshots

# Create snapshot
vpvm snapshot create ubuntu-22.04 before-update

# List snapshots
vpvm snapshot list ubuntu-22.04

# Restore snapshot
vpvm snapshot restore ubuntu-22.04 before-update

# Delete snapshot
vpvm snapshot delete ubuntu-22.04 old-snapshot

Templates

# Create template
vpvm template create ubuntu-22.04 "My Template"

# List templates
vpvm template list

# Get template info
vpvm template info "My Template"

# Delete template
vpvm template delete "Old Template"

# Create VM from template
vpvm vm create "My Template" new-vm

Configure Hardware

# Change CPU and memory
vpvm configure ubuntu-22.04 --cpu 4 --memory 8192

# Change CPU only
vpvm configure ubuntu-22.04 --cpu 2

# Change memory only (in MB)
vpvm configure ubuntu-22.04 --memory 4096

Advanced

# Clone VM
vpvm clone ubuntu-22.04 ubuntu-dev

# Delete VM
vpvm delete test-vm

# Restart VM
vpvm restart ubuntu-22.04

Remote Access

# List VMs on a remote machine
vpvm list --server 192.168.1.10 --port 49152 --token mytoken

# Start a VM remotely
vpvm start my-vm --server 192.168.1.10 --port 49152 --token mytoken

# Check remote VM status
vpvm status my-vm --server 192.168.1.10 --token mytoken

# Create a snapshot on a remote machine
vpvm snapshot create my-vm backup --server 192.168.1.10 --token mytoken

VirtualProg CLI empowers developers, sysadmins, and power users with complete command-line control over virtual machines — perfectly integrated with the VirtualProg GUI experience.