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.

---

🚀 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

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 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> [arguments]

Available Commands

VM Control Commands

Command	Description	Syntax
start	Start or resume a virtual machine	vpvm start <vmname>
stop	Force stop a running VM	vpvm stop <vmname>
shutdown	Gracefully shutdown a running VM	vpvm shutdown <vmname>
pause	Pause a running VM	vpvm pause <vmname>
resume	Resume a paused or suspended VM	vpvm resume <vmname>
suspend	Suspend VM to disk	vpvm suspend <vmname>
restart	Restart a running VM	vpvm restart <vmname>

VM Management Commands

Command	Description	Syntax
list all	List all virtual machines	vpvm list all
status	Get current status of a VM	vpvm status <vmname>
clone	Clone an existing VM	vpvm clone <vmname> <newname>
delete	Delete a virtual machine	vpvm delete <vmname>

Snapshot Commands

Command	Description	Syntax
snapshot create	Create a new snapshot	vpvm snapshot create <vmname> <snapshotname>
snapshot list	List all snapshots for a VM	vpvm snapshot list <vmname>
snapshot restore	Restore a VM to a snapshot state	vpvm snapshot restore <vmname> <snapshotname>
snapshot delete	Delete a snapshot	vpvm snapshot delete <vmname> <snapshotname>

Template Commands

Command	Description	Syntax
template create	Create a template from a VM	vpvm template create <vmname> <templatename>
template list	List all available templates	vpvm template list
template delete	Delete a template	vpvm template delete <templatename>
vm create	Create a VM from a template	vpvm vm create <templatename> <vmname>

---

📖 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

---

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

---

📸 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

Shell Scripting

Automate VM management with shell scripts:

#!/bin/bash
# Start development VMs

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

for vm in "${VMS[@]}"; do
    echo "Starting $vm..."
    vpvm start "$vm"
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

Stop all running VMs:

#!/bin/bash
# Get list of all VMs
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"

---

📚 Related Documentation

• VirtualProg Main Documentation
• Snapshots Guide
• Templates Guide
• Dashboard & Statistics
• Log Viewer

---

📬 Support

Need help with the CLI?

• Email: [email protected]
• Email: [email protected]
• Mac App Store

---

📝 Examples Quick Reference

Basic Operations

# List all VMs
vpvm list all

# Start a VM
vpvm start ubuntu-22.04

# Check status
vpvm status ubuntu-22.04

# Graceful shutdown
vpvm shutdown ubuntu-22.04

# 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

# Delete template
vpvm template delete "Old Template"

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

Advanced

# Clone VM
vpvm clone ubuntu-22.04 ubuntu-dev

# Delete VM
vpvm delete test-vm

# Restart VM
vpvm restart ubuntu-22.04

---

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