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.

Tip: Every command listed in this documentation is also available directly in the Web Dashboard CLI Terminal — click the ⌨ CLI button in the dashboard header to open it without leaving the browser. See the Web Dashboard documentation for details.

📥 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
watch [--interval <s>] — Real-time VM monitor (auto-refreshes, press q to quit)
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)
screenshot <vmname> [--format png|jpeg] [--quality <0.1-1.0>] [--output <path>] — Capture a screenshot of a running VM
logs <vmname> [--limit <n>] — Show recent log entries for a VM
logs clear <vmname> — Clear all logs for a VM
unlock <vmname> [--password <password>] — Unlock a password-protected VM to allow config changes
lock <vmname> — Re-lock a password-protected VM
images list — List ISO and IPSW image files available in the VirtualProg directory
images browse — Show all available macOS IPSW and Linux ISO images (built-in and custom) with download status
images get <alias|name> — Download an image by alias or display name
images status — Show active image downloads and their progress
images add --name <n> --url <u> --type <linux|macos> — Add a custom download entry to the catalog
images remove <alias|name> [--delete-file] — Remove a custom catalog entry
images cancel [<alias|name>] — Cancel an active download; omit argument to list active downloads
images delete <alias|name> — Delete a downloaded ISO or IPSW file from disk
create <vmname> --os <linux|macos> --cpu <n> --memory <mb> --disk <gb> --image <alias|name|filename> — Create a new VM from scratch
snapshot — Manage VM snapshots (subcommands: list, info, create, restore, delete, update, createvm, createtemplate)
template — Manage VM templates (subcommands: list, info, create, clone, update, createvm, delete, config)
network — Manage host networks (subcommands: list, info, sources, add, update, delete)
balloon — Query or adjust memory balloon for a running Linux VM (subcommands: info, set)
servermode --enable | --disable | --info — Enable, disable, or query Server Mode
config — Configure all VM settings (subcommands: info, general, cpu, display, sound, input, startup, security, schedule, auto-snapshot, rosetta, restore-image, boot-disk, webhook, disk, network, cd, serial, nbd)

Examples

vpvm list
vpvm watch
vpvm watch --interval 5
vpvm start ubuntu-22.04
vpvm stop ubuntu-22.04
vpvm info ubuntu-22.04
vpvm stats ubuntu-22.04
vpvm status ubuntu-22.04
vpvm clone ubuntu-22.04 ubuntu-dev
vpvm rename ubuntu-22.04 ubuntu-lts
vpvm screenshot ubuntu-22.04
vpvm logs ubuntu-22.04
vpvm logs ubuntu-22.04 --limit 100
vpvm logs clear ubuntu-22.04
vpvm images list
vpvm images browse
vpvm images get ubuntu
vpvm images get sequoia
vpvm images add --name "My ISO" --url "https://example.com/custom.iso" --type linux
vpvm images remove AlpineVirtual --delete-file
vpvm images delete ubuntu
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu
vpvm create "My Mac" --os macos --cpu 4 --memory 8192 --disk 80 --image sequoia
vpvm snapshot list ubuntu-22.04
vpvm snapshot info ubuntu-22.04 before-update
vpvm snapshot create ubuntu-22.04 before-update
vpvm snapshot createvm ubuntu-22.04 before-update my-new-vm
vpvm template list
vpvm template info "My Template"
vpvm template create ubuntu-22.04 "My Template"
vpvm template clone "My Template" "My Template Copy"
vpvm template createvm "My Template" new-vm
vpvm network sources
vpvm network add "My Network" --type Shared --subnet 192.168.50.0
vpvm network update "My Network" --new-name "Fast Network" --mtu 9000
vpvm network delete "My Network"
vpvm config info general ubuntu-22.04
vpvm config info startup ubuntu-22.04
vpvm config cpu ubuntu-22.04 --cpu 4 --memory 8192
vpvm config general ubuntu-22.04 --new-name "dev-server" --headless true
vpvm config security ubuntu-22.04 --password "mypass"
vpvm config disk list ubuntu-22.04
vpvm config disk add ubuntu-22.04 --size 50
vpvm config disk resize ubuntu-22.04 --disk "Disk 1" --size 128
vpvm config network add ubuntu-22.04 --type "Default (NAT)"
vpvm template config cpu "My Template" --cpu 8 --memory 16384
vpvm servermode --enable
vpvm servermode --disable
vpvm servermode --info

🆕 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

Restarting a Virtual Machine

Restart a running VM:

vpvm restart ubuntu-22.04

Output:

Request completed successfully.
Restarted ubuntu-22.04

Locking and Unlocking Password-Protected VMs

When a VM has a password set, it is locked by default. Locked VMs reject all control operations (start, stop, clone, etc.) and all configuration changes until explicitly unlocked.

Unlocking a VM

vpvm unlock ubuntu-22.04

If --password is omitted, vpvm prompts for the password securely (input is hidden):

Password for 'ubuntu-22.04': 
Request completed successfully.
VM unlocked

You can also supply the password inline for scripting:

vpvm unlock ubuntu-22.04 --password "mypassword"

The unlock is held in memory by VirtualProg for the current session. It is automatically cleared when the VM stops.

Locking a VM

To re-lock a VM before the session ends:

vpvm lock ubuntu-22.04

Request completed successfully.
VM 'ubuntu-22.04' locked successfully

Only VMs that have a password configured can be locked. Attempting to lock a VM with no password returns an error.

Typical Workflow

# Unlock the VM
vpvm unlock ubuntu-22.04

# Make configuration changes
vpvm config cpu ubuntu-22.04 --cpu 4 --memory 8192

# Re-lock when done
vpvm lock 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

Output:

running

Getting VM Info

Show full configuration and runtime details for a VM:

vpvm info ubuntu-22.04

Output:

  Name          : ubuntu-22.04
  OS            : Linux
  Distro        : Ubuntu
  CPU           : 4
  Memory        : 8192 MB
  State         : running
  Disks         : disk0: 64 GB
  Networks      : net0: Default (NAT)
  Port Forwarding: host:2222 → guest:22
  Favorite      : No
  Tag Color     : -
  Headless      : No
  Auto Start    : No
  Schedule      : -
  Description   : Development server
  Created At    : 2025-01-15

Getting VM Stats

Show usage statistics for a VM:

vpvm stats ubuntu-22.04

Output:

  Name           : ubuntu-22.04
  Total Uptime   : 12h 34m
  Last Started   : 2025-06-01 09:00
  Last Stopped   : 2025-06-01 21:34
  Total Sessions : 5

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, and rename 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

Output:

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

Renaming a Virtual Machine

Rename an existing VM:

vpvm rename ubuntu-22.04 ubuntu-dev

Output:

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

Requirements: - VM must be stopped - New name must be unique

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 a VM

The config command group lets you change any setting on a VM. Each sub-command targets a specific settings panel. The VM does not need to be stopped for most settings — hardware changes (CPU, memory, display) typically require a stop/start.

Syntax

vpvm config <sub-command> <vmname> [options]

Use vpvm config <sub-command> --help to see all options for a specific sub-command.

Inspecting Current Values

Before modifying a setting, use config info to see the current values for any section:

vpvm config info <section> <vmname>

Supported sections: general, cpu, display, sound, input, startup, security, schedule, auto-snapshot, rosetta, boot-disk, restore-image

Examples:

# See current general settings before renaming
vpvm config info general ubuntu-22.04

# Check startup and autopause settings
vpvm config info startup ubuntu-22.04

# Review security flags before changing them
vpvm config info security ubuntu-22.04

# Check current schedule
vpvm config info schedule ubuntu-22.04

Sample output (config info startup):

  Auto Start           : false
  Startup Delay (s)    : 0
  Sleep Behavior       : Do Nothing
  Shutdown Behavior    : Shutdown
  Window Close         : Ask
  Auto Pause           : false
  Auto Pause Minutes   : 30
  Auto Pause Action    : Pause
  Battery Pause        : false
  Battery Level (%)    : 20
  Battery Pause Action : Pause

The same command works for templates:

vpvm template config info startup "My Template"

General settings

# Rename a VM
vpvm config general ubuntu-22.04 --new-name "dev-server"

# Set a description and enable headless mode
vpvm config general ubuntu-22.04 --descr "CI build machine" --headless true

# Enable nested virtualisation
vpvm config general ubuntu-22.04 --nested-virt true

Option	Description
`--new-name`	New VM name
`--descr`	Description / notes
`--distro`	Distro / version (e.g. `Ubuntu`, `Debian`, `Sequoia`)
`--headless true\\|false`	Start without opening a display window
`--fullscreen true\\|false`	Open in fullscreen on start
`--nested-virt true\\|false`	Enable nested virtualisation
`--entropy true\\|false`	Enable VirtIO entropy device

CPU & Memory

vpvm config cpu ubuntu-22.04 --cpu 4 --memory 8192
vpvm config cpu ubuntu-22.04 --balloon true

Option	Description
`--cpu`	Number of CPU cores
`--memory`	RAM in MB
`--balloon true\\|false`	Enable memory balloon device

Display

vpvm config display ubuntu-22.04 --auto false --width 1920 --height 1080 --ppi 96

Option	Description
`--active true\\|false`	Show or hide the display window
`--auto true\\|false`	`true` = auto resolution (follows host); `false` = force resolution
`--width` / `--height`	Resolution in pixels (used when `--auto false`)
`--ppi`	Pixels per inch

Sound & Input

vpvm config sound ubuntu-22.04 --input true --output true
vpvm config input ubuntu-22.04 --keyboard Mac --mouse Mac

Startup & Shutdown

vpvm config startup ubuntu-22.04 --auto-start true --sleep-behavior Pause
vpvm config startup ubuntu-22.04 --auto-pause true --auto-pause-minutes 30 --auto-pause-action Suspend

Option	Values
`--auto-start`	`true\\|false`
`--startup-delay`	Seconds
`--sleep-behavior`	`"Do Nothing"`, `Pause`, `Suspend`, `Shutdown`, `Stop`
`--shutdown-behavior`	`"Do Nothing"`, `Suspend`, `Shutdown`, `Stop`
`--window-close`	`Ask`, `Suspend`, `Shutdown`, `Stop`, `Background`
`--auto-pause`	`true\\|false`
`--auto-pause-minutes`	Minutes of inactivity
`--auto-pause-action`	`"Do Nothing"`, `Pause`, `Suspend`, `Shutdown`, `Stop`
`--auto-pause-battery`	`true\\|false`
`--auto-pause-battery-level`	Battery percentage threshold
`--auto-pause-battery-action`	`"Do Nothing"`, `Pause`, `Suspend`, `Shutdown`, `Stop`

Security

# Set a password (plain text — hashed automatically)
vpvm config security ubuntu-22.04 --password "mypassword"

# Remove the password
vpvm config security ubuntu-22.04 --clear-password

# Disable clipboard sharing
vpvm config security ubuntu-22.04 --clipboard false

Option	Description
`--password`	Set a new password (plain text, hashed before sending)
`--clear-password`	Remove the existing password
`--clipboard true\\|false`	Allow clipboard access
`--screenshot true\\|false`	Allow screenshots
`--screen-record true\\|false`	Allow screen recording
`--stats true\\|false`	Allow stats access

Schedule

vpvm config schedule ubuntu-22.04 --enabled true --days "1,2,3,4,5" --start-time "09:00" --stop-time "18:00"

Option	Description
`--enabled true\\|false`	Enable the schedule
`--days`	Comma-separated day numbers: 1=Mon … 7=Sun
`--start-time`	Start time in HH:mm
`--stop-time`	Stop time in HH:mm
`--clear-start-time`	Remove the scheduled start time
`--clear-stop-time`	Remove the scheduled stop time

Auto Snapshots

vpvm config auto-snapshot ubuntu-22.04 --enabled true --type Daily --max 7 --prefix "auto"

Option	Values
`--enabled`	`true\\|false`
`--type`	`On Start`, `Daily`, `Weekly`, `Monthly`, `On Shutdown`
`--max`	Maximum snapshots to keep
`--prefix`	Snapshot name prefix

Rosetta (Linux VMs only)

vpvm config rosetta ubuntu-22.04 --enabled true --mount-name "rosetta"

Boot Disk & Restore Image

# Set boot device by name (disk, CD/DVD, or NBD name), Auto, or Recovery (macOS only)
vpvm config boot-disk ubuntu-22.04 --device "Disk 1"

# Set macOS restore image
vpvm config restore-image my-macos-vm --image sequoia

Webhooks

# Add a webhook URL
vpvm config webhook ubuntu-22.04 --add "https://hooks.example.com/vm-state"

# Remove a webhook URL
vpvm config webhook ubuntu-22.04 --remove "https://hooks.example.com/vm-state"

# List current webhook URLs
vpvm config webhook ubuntu-22.04 --list

# Remove all webhook URLs
vpvm config webhook ubuntu-22.04 --clear

Disk Management

# List disks (name, UUID, size, type, interface)
vpvm config disk list ubuntu-22.04

# Add a new disk
vpvm config disk add ubuntu-22.04 --size 50 --interface VirtIo --type Dynamic

# Remove a disk (by name or UUID)
vpvm config disk remove ubuntu-22.04 --disk "Disk 2"

# Update disk settings
vpvm config disk update ubuntu-22.04 --disk "Disk 1" --cache-mode Auto --read-only false

# Resize a disk (VM must be stopped; shrinking is not supported)
vpvm config disk resize ubuntu-22.04 --disk "Disk 1" --size 128

# Relocate macOS recovery partition after resizing a fixed disk
vpvm config disk relocate-recovery macos-vm --disk "Disk 1"

Option	Description
`--disk`	Disk name (e.g. `"Disk 1"`) or UUID
`--size`	Size in GB
`--interface`	`VirtIo\\|NVME`
`--type`	`Dynamic\\|Fixed`
`--cache-mode`	`Auto\\|Cached\\|Uncached`
`--sync-mode`	`Full\\|FSync\\|None`
`--read-only`	`true\\|false`

Network Adapter Management

# List network adapters (different from host networks)
vpvm config network list ubuntu-22.04

# Add a network adapter
vpvm config network add ubuntu-22.04 --type "Default (NAT)"

# Remove a network adapter
vpvm config network remove ubuntu-22.04 --net "Network 1"

# Update adapter settings
vpvm config network update ubuntu-22.04 --net "Network 1" --type "en0"

# Add a port forwarding rule
vpvm config network pf-add ubuntu-22.04 --net "Network 1" --host-port 2222 --guest-port 22

# Remove a port forwarding rule
vpvm config network pf-remove ubuntu-22.04 --net "Network 1" --rule "SSH"

# List port forwarding rules
vpvm config network pf-list ubuntu-22.04 --net "Network 1"

Run vpvm network sources to see all valid network type values.

CD/DVD Management

vpvm config cd list ubuntu-22.04
vpvm config cd add ubuntu-22.04 --image ubuntu
vpvm config cd remove ubuntu-22.04 --cd "CD/DVD 1"
vpvm config cd update ubuntu-22.04 --cd "CD/DVD 1" --image alpine

Serial Port Management

vpvm config serial list ubuntu-22.04
vpvm config serial add ubuntu-22.04 --mode Console --theme Dark
vpvm config serial remove ubuntu-22.04 --serial "Serial Port 1"

Network Block Device (NBD) Management

vpvm config nbd list ubuntu-22.04
vpvm config nbd add ubuntu-22.04 --url nbd://192.168.1.5/disk0
vpvm config nbd remove ubuntu-22.04 --nbd "Network Block Device 1"

Listing Available Boot Images

Before creating a VM, list the ISO and IPSW files available in the VirtualProg directory:

vpvm images list

Output:

ISO images (Linux):

  ubuntu-22.04-server.iso
  debian-12.iso

IPSW images (macOS):

  (none)

Place your ISO or IPSW files directly in the VirtualProg data directory to make them available here.

Creating a VM from Scratch

Create a new VM with the same parameters as Quick Create in the GUI:

# Create a Linux VM — using a catalog alias (recommended)
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu

# Create a Linux VM — using the full catalog name
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image "Ubuntu 26.04 LTS"

# Create a Linux VM — using a raw filename (still works)
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu.iso

# Create a macOS VM (arm64 only)
vpvm create "My Mac" --os macos --cpu 4 --memory 8192 --disk 80 --image sequoia

Output:

Request completed successfully.
VM 'My Ubuntu' creation started (Linux, 2 CPU, 4096 MB, 64 GB, image: Ubuntu_26.04_arm64.iso). Use 'vpvm info My Ubuntu' to check when ready.

Parameters:

Option	Required	Description
`<vmname>`	✅	Name for the new VM
`--os`	✅	`linux` or `macos`
`--cpu`	✅	Number of CPU cores
`--memory`	✅	RAM in MB (e.g. `4096` for 4 GB)
`--disk`	✅	Disk size in GB
`--image`	✅	Catalog alias, full name, or filename (e.g. `ubuntu`, `"Ubuntu 26.04 LTS"`, `Ubuntu_26.04_arm64.iso`). Run `vpvm images browse` to see all available aliases.

Requirements: - VirtualProg must be running - The image must be downloaded — use vpvm images get <alias> first if needed - Linux VMs require an .iso file; macOS VMs require an .ipsw file - VM name must be unique

Downloading Boot Images

Download macOS IPSW or Linux ISO images directly to the VirtualProg directory. The download happens inside the VirtualProg app, so it works for both local and remote connections.

Browsing the Catalog

Show all available images — built-in and custom — with their current download status:

vpvm images browse

Output:

TYPE    ALIAS               NAME                      FILE                             STATUS
────────────────────────────────────────────────────────────────────────────────────────────
macOS   latest              Latest Supported          RestoreImage.ipsw                Not Downloaded
macOS   tahoe               Tahoe (26.4.1)            Tahoe_26.4.1.ipsw               Not Downloaded
macOS   sequoia             Sequoia (15.6.1)          Sequoia_15.6.1.ipsw             ✓ Downloaded
Linux   ubuntu              Ubuntu 26.04 LTS          Ubuntu_26.04_arm64.iso           Not Downloaded
Linux   ubuntu-server       Ubuntu Server 26.04 LTS   Ubuntu_Server_26.04_arm64.iso   Not Downloaded
...
Linux   custom-a1b2c3d4     My Custom ISO             my_custom_iso.iso                Not Downloaded  [custom]

Custom entries are shown inline alongside built-in ones, marked with a [custom] tag.

Downloading an Image

Use vpvm images get with an alias or display name to start a download. Both built-in and custom entries are supported — there is no separate command for each type.

# Download by alias
vpvm images get ubuntu
vpvm images get sequoia
vpvm images get latest

# Download by display name (quote names with spaces)
vpvm images get "Ubuntu 26.04 LTS"
vpvm images get "Sequoia (15.6.1)"
vpvm images get "My Custom ISO"

Available macOS aliases:

Alias	macOS Version
`latest`	Latest Supported (auto-detected)
`tahoe`	Tahoe 26.4.1
`sequoia`	Sequoia 15.6.1
`sonoma`	Sonoma 14.6.1
`ventura`	Ventura 13.6
`monterey`	Monterey 12.6.1

Available Linux aliases:

Alias	Distribution
`ubuntu`	Ubuntu 26.04 LTS
`ubuntu-server`	Ubuntu Server 26.04 LTS
`fedora`	Fedora 43 Workstation
`opensuse-leap`	openSUSE Leap 16.0
`opensuse-tumbleweed`	openSUSE Tumbleweed
`alpine`	Alpine 3.23.4
`kali`	Kali 2026.1
`popos`	Pop!_OS 24.04
`debian`	Debian 13.4.0
`nixos`	NixOS 25.11
`rocky`	Rocky 10.1

Note: macOS IPSW downloads are only supported on Apple Silicon (arm64).

Live Download Progress

While downloading, the CLI shows an inline progress bar with speed and ETA:

Downloading Ubuntu_26.04_arm64.iso   63% [============>       ]  2.1 GB / 3.3 GB  18.2 MB/s  ETA 1m 04s

When complete:

✅ Ubuntu_26.04_arm64.iso — Complete (3.3 GB)

Checking Download Status

Use vpvm images status to see all currently active downloads and their progress:

vpvm images status

Example output:

ubuntu-26.04-live-server-arm64.iso  [downloading]   42%

Cancelling a Download

Press Ctrl+C during an active vpvm images get command to cancel gracefully. Or cancel by alias or name from another terminal:

# Cancel by alias
vpvm images cancel ubuntu

# Cancel by display name
vpvm images cancel "Ubuntu 26.04 LTS"

# Run with no argument to see all active downloads and their identifiers
vpvm images cancel

Deleting a Downloaded Image

Remove a downloaded ISO or IPSW from the VirtualProg directory. Any active download for the file is cancelled automatically before deletion.

# Delete by alias
vpvm images delete sequoia
vpvm images delete ubuntu

# Delete by display name
vpvm images delete "Sequoia (15.6.1)"
vpvm images delete "Ubuntu 26.04 LTS"

Typical Workflow

# 1. See what's available and what's already downloaded
vpvm images browse

# 2. Download the image you need (alias or name, your choice)
vpvm images get ubuntu

# 3. Create the VM using the alias — no need to type the full filename
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu

# 4. Clean up the ISO after creating the VM
vpvm images delete ubuntu

Custom Image Catalog

In addition to the built-in images, you can add your own ISO or IPSW download URLs to the catalog. Custom entries appear alongside built-in ones in both the GUI and vpvm images browse.

Adding a Custom Entry

vpvm images add --name "Ubuntu Nightly" \
  --url "https://cdimage.ubuntu.com/daily-live/current/noble-desktop-arm64.iso" \
  --type linux

# macOS IPSW example
vpvm images add --name "My IPSW" \
  --url "https://example.com/custom.ipsw" \
  --type macos

--type must be linux or macos
The alias (e.g. custom-a1b2c3d4) is auto-generated and shown in vpvm images browse
The filename is auto-detected from the URL; use --file to override it

Downloading a Custom Entry

Custom entries use the same get command as built-in images — just pass the alias or name:

# Use the auto-generated alias
vpvm images get custom-a1b2c3d4

# Or use the display name
vpvm images get "Ubuntu Nightly"

Removing a Custom Entry

# Remove the catalog entry only (downloaded file kept on disk)
vpvm images remove AlpineVirtual

# Remove the catalog entry AND delete the downloaded ISO/IPSW from disk
vpvm images remove AlpineVirtual --delete-file

# Also works with the auto-generated alias
vpvm images remove custom-a1b2c3d4 --delete-file

You can pass the entry name (e.g. AlpineVirtual) or the auto-generated alias (e.g. custom-a1b2c3d4)
Without --delete-file, the downloaded file is left on disk
With --delete-file, the file is deleted immediately with no confirmation

Taking a Screenshot

Capture the current display of a running VM and save it as an image file:

vpvm screenshot ubuntu-22.04

Output:

✅ Screenshot saved: ubuntu-22.04-1746700800.png

By default, the screenshot is saved as a PNG file in the current directory, named <vmname>-<timestamp>.png.

Options

Option	Description	Default
`--output <path>`	File path to save the screenshot	`<vmname>-<timestamp>.png` in current directory
`--format png\\|jpeg`	Image format	`png`
`--quality <0.1-1.0>`	JPEG compression quality (jpeg only)	`0.85`

Examples

# PNG screenshot saved to the current directory
vpvm screenshot ubuntu-22.04

# Save to a specific path
vpvm screenshot ubuntu-22.04 --output ~/Desktop/vm.png

# JPEG at default quality
vpvm screenshot ubuntu-22.04 --format jpeg

# JPEG at reduced quality (smaller file size)
vpvm screenshot ubuntu-22.04 --format jpeg --quality 0.6 --output ~/Desktop/vm.jpg

# Screenshot from a remote VirtualProg instance
vpvm screenshot ubuntu-22.04 --server 192.168.1.10 --port 49152

Requirements: - The VM must be running - The VM window must be open in VirtualProg, or Background Screenshots must be enabled in Settings

Viewing VM Logs

Display the most recent log entries for a VM:

vpvm logs ubuntu-22.04

Output:

  50 log entries

  2026-01-01 12:00:00  INFO   VM started successfully
  2026-01-01 12:00:05  ERROR  Disk mount failed

By default, the last 50 entries are shown. Use --limit to adjust:

vpvm logs ubuntu-22.04 --limit 100

Options

Option	Description	Default
`--limit <n>`	Maximum number of log entries to display	`50`

Requirements: - Logging must be enabled in VirtualProg (Settings > Logging)

Clearing VM Logs

Remove all stored log entries for a specific VM:

vpvm logs clear ubuntu-22.04

Output:

Logs cleared for 'ubuntu-22.04'

Requirements: - Logging must be enabled in VirtualProg (Settings > Logging)

Monitoring VMs in Real Time

Display a live, auto-refreshing table of all VMs and their current state:

vpvm watch

Output:

VirtualProg Monitor                    Updated: 2026-01-01 12:00:05
────────────────────────────────────────────────────────────────────
 Name            State        OS       CPU    Memory
────────────────────────────────────────────────────────────────────
 ubuntu-22.04    ● running    linux      4    8192 MB
 macos-sequoia   ○ stopped    macOS      2    4096 MB
 dev-server      ◐ paused     linux      2    2048 MB
────────────────────────────────────────────────────────────────────
 3 VMs                            Press q to quit · interval: 2s

State indicators: ● running · ○ stopped · ◐ paused or suspended

Options

Option	Description	Default
`--interval <s>`	Refresh interval in seconds	`2`

Examples

# Monitor with default 2-second refresh
vpvm watch

# Slower refresh for low-bandwidth remote connections
vpvm watch --interval 10

# Monitor a remote VirtualProg instance
vpvm watch --server 192.168.1.10 --port 49152 --token <token>

Press q, Q, or ESC to exit.

📸 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

To include optional notes:

vpvm snapshot create ubuntu-22.04 backup-before-update --notes "Before kernel upgrade"

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) - Use --notes to record the reason or context for the snapshot - 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:

clean-install
backup-before-update
pre-kernel-upgrade

Snapshot Details

Get detailed information about a specific snapshot, including its hardware configuration captured at the time of creation:

vpvm snapshot info ubuntu-22.04 backup-before-update

Output:

  Name             : backup-before-update
  VM               : ubuntu-22.04
  Auto             : No
  Created At       : 2025-04-10T14:32:00Z
  OS Distro        : Ubuntu
  CPU              : 4
  Memory           : 8192 MB
  Disks            : 64 GB (Dynamic)
  Networks         : Default (NAT)
  Port Forwarding  : None
  Headless         : No
  Auto Start       : No
  Schedule         : Disabled

Notes: The Notes field is shown only if notes were added when the snapshot was created.

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

Updating a Snapshot

Rename a snapshot or update its notes without creating a new one:

vpvm snapshot update ubuntu-22.04 backup-before-update --new-name "pre-kernel-upgrade"

To update notes only:

vpvm snapshot update ubuntu-22.04 pre-kernel-upgrade --notes "Kernel 6.8, clean state"

To update both at once:

vpvm snapshot update ubuntu-22.04 pre-kernel-upgrade --new-name "kernel-6.8-base" --notes "Kernel 6.8, clean state"

Output:

Request completed successfully.
Snapshot updated successfully

Notes: - Both --new-name and --notes are optional — omit either to leave it unchanged - The new name must be unique among snapshots for that VM - Passing --notes "" clears the existing notes

Creating a VM from a Snapshot

Deploy a new VM directly from a snapshot — no need to restore it first:

vpvm snapshot createvm ubuntu-22.04 before-update my-new-vm

Output:

Request completed successfully.
Creating VM my-new-vm from snapshot before-update of ubuntu-22.04

Requirements: - New VM name must be unique - Snapshot must exist for the specified VM

Creating a Template from a Snapshot

Create a reusable template directly from a snapshot — no need to restore it into a VM first:

vpvm snapshot createtemplate ubuntu-22.04 before-update "Ubuntu 22.04 Clean"

To include optional notes:

vpvm snapshot createtemplate ubuntu-22.04 before-update "Ubuntu 22.04 Clean" --notes "Clean install, no extra packages"

Output:

Request completed successfully.
Creating template 'Ubuntu 22.04 Clean' from snapshot 'before-update' of 'ubuntu-22.04'

Requirements: - VM must not be password protected - Template name must be unique - Snapshot must exist for the specified VM

📦 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"

To include optional notes:

vpvm template create ubuntu-22.04 "Ubuntu 22.04 Base" --notes "Base install with dev tools"

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 - Use --notes to document what's included in the template

Listing Templates

View all available templates:

vpvm template list

Output:

Ubuntu 22.04 Base
macOS Sonoma Clean
Debian 12 Dev

Getting Template Info

Show full details for a template:

vpvm template info "Ubuntu 22.04 Base"

Output:

  Name           : Ubuntu 22.04 Base
  Source VM      : ubuntu-22.04
  OS             : Linux
  Distro         : Ubuntu
  CPU            : 4
  Memory         : 8192 MB
  Disks          : disk0: 64 GB
  Networks       : net0: Default (NAT)
  Port Forwarding: host:2222 → guest:22
  Headless       : No
  Auto Start     : No
  Schedule       : -
  Notes          : Base install with dev tools
  Created At     : 2025-01-15

Cloning a Template

Create a copy of an existing template under a new name:

vpvm template clone "Ubuntu 22.04 Base" "Ubuntu 22.04 Staging"

To include optional notes:

vpvm template clone "Ubuntu 22.04 Base" "Ubuntu 22.04 Staging" --notes "Staging copy"

Output:

Request completed successfully.
Cloning template 'Ubuntu 22.04 Base' as 'Ubuntu 22.04 Staging'

Requirements: - Source template must exist - New template name must be unique

Creating a VM from a Template

Deploy a new VM from a template:

vpvm template createvm "Ubuntu 22.04 Base" my-new-vm

Output:

Request completed successfully.
Creating VM my-new-vm from template Ubuntu 22.04 Base

Requirements: - New VM name must be unique

Deleting a Template

Remove a template you no longer need:

vpvm template delete "Old Template"

Output:

Request completed successfully.
Deleted template Old Template

Updating a Template

Rename a template or update its notes without recreating it:

vpvm template update "My Template" --new-name "Ubuntu 24.04 Base"

To update notes only:

vpvm template update "Ubuntu 24.04 Base" --notes "Clean install, SSH enabled"

To update both at once:

vpvm template update "Ubuntu 24.04 Base" --new-name "ubuntu-base" --notes "Clean install, SSH enabled"

Output:

Request completed successfully.
Template updated successfully

Notes: - Both --new-name and --notes are optional — omit either to leave it unchanged - The new name must be unique among all templates - Passing --notes "" clears the existing notes

🌐 Managing Custom Networks

macOS Tahoe 26 or later required. The network add, network update, and network delete commands require VirtualProg to be running on macOS 26 (Tahoe) or newer.

Custom networks let you define shared (NAT) or host-only networks with a specific subnet, mask, and MTU — giving VMs a stable, predictable IP range and isolating traffic as needed.

Listing Networks

vpvm network list

Output:

Default (NAT)
Dev Network
Isolated

Viewing Network Details

vpvm network info "Dev Network"

Output:

  Name           : Dev Network
  Type           : Shared
  Enabled        : Yes
  Subnet         : 192.168.50.0
  Mask           : 255.255.255.0
  MTU            : 1500
  IPv6           : No
  IPv6 Prefix    : -
  Ext. Interface : -

Creating a Network

vpvm network add <name> [options]

Option	Description	Default
`--type`	`Shared` (NAT) or `Host` (host-only)	`Shared`
`--subnet`	Network address ending in `.0` (e.g. `192.168.50.0`). Random if omitted	(random)
`--mask`	Subnet mask	`255.255.255.0`
`--mtu`	MTU value 1280–9000	`1500`
`--interface`	Physical interface ID for Shared type (e.g. `en0`). Omit for Automatic	(Automatic)
`--ipv6`	Enable IPv6 (Shared type only)	off
`--ipv6-prefix`	IPv6 ULA prefix starting with `fd` (required when `--ipv6` is set)	—
`--disabled`	Create the network in disabled state	(enabled)

Examples:

# Shared network with a specific subnet
vpvm network add "Dev Network" --type Shared --subnet 192.168.50.0

# Host-only network
vpvm network add "Isolated" --type Host --subnet 10.99.0.0 --mask 255.255.0.0

# Shared network with IPv6
vpvm network add "IPv6 Net" --type Shared --subnet 172.20.10.0 --ipv6 --ipv6-prefix "fd12:3456::"

# Large MTU for high-performance workloads
vpvm network add "Jumbo" --type Host --subnet 10.10.10.0 --mtu 9000

Updating a Network

vpvm network update <name> [options]

Option	Description
`--new-name`	Rename the network
`--type`	Change type: `Shared` or `Host`
`--subnet`	New subnet address
`--mask`	New subnet mask
`--mtu`	New MTU value 1280–9000
`--interface`	New physical interface ID
`--ipv6` / `--no-ipv6`	Enable or disable IPv6
`--ipv6-prefix`	New IPv6 prefix
`--enable` / `--disable`	Enable or disable the network

All virtual machines that use the network must be stopped before updating. If any are running, the command fails with a message listing the blocking VMs.

Examples:

# Rename a network
vpvm network update "Dev Network" --new-name "Production"

# Change MTU
vpvm network update "Dev Network" --mtu 9000

# Disable a network
vpvm network update "Dev Network" --disable

# Change type and subnet together
vpvm network update "Dev Network" --type Host --subnet 10.50.0.0

Deleting a Network

vpvm network delete <name>

A network cannot be deleted while it is assigned to any virtual machine. Remove the network from all VMs first, then delete it.

Example:

vpvm network delete "Old Network"

💾 Managing VM Disks

VM disk management uses the config disk subcommand group. The --disk option accepts either the disk name (e.g. "Disk 1") or its UUID — use config disk list to see both.

For template disks, use the template config disk subcommand group described in the next section.

Listing Disks

Show all disks attached to a VM, including their names, UUIDs, sizes, types, and interface:

vpvm config disk list ubuntu-22.04

Output:

#   NAME      UUID                                  SIZE    TYPE     INTERFACE
1   Disk 1    a1b2c3d4-e5f6-7890-abcd-ef1234567890  64 GB   Dynamic  VirtIo
2   Disk 2    b2c3d4e5-f6a7-8901-bcde-f01234567891  32 GB   Fixed    NVMe

Adding a Disk

vpvm config disk add ubuntu-22.04 --size 50 --interface VirtIo --type Dynamic

Removing a Disk

vpvm config disk remove ubuntu-22.04 --disk "Disk 2"

Updating Disk Settings

Change cache mode or read-only state without affecting data:

vpvm config disk update ubuntu-22.04 --disk "Disk 1" --cache-mode Auto --read-only false

Resizing a Disk

Expand an existing disk to a new size (in GB). The VM must be stopped before resizing.

# Resize by disk name
vpvm config disk resize ubuntu-22.04 --disk "Disk 1" --size 128

# Resize by disk UUID
vpvm config disk resize ubuntu-22.04 --disk a1b2c3d4-e5f6-7890-abcd-ef1234567890 --size 128

Output:

Request completed successfully.
Disk resized to 128 GB

Requirements: - VM must be fully stopped (not paused or suspended) - New size must be larger than the current size — shrinking is not supported

Relocating the macOS Recovery Partition

After resizing a fixed disk on a macOS VM, the recovery partition may no longer be at the expected location. Use this command to move it to the correct position so macOS recovery tools work properly.

vpvm config disk relocate-recovery macos-vm --disk "Disk 1"

Output:

Request completed successfully.
Recovery partition relocated

Requirements: - Disk must be of type Fixed (not Dynamic) - Target must be a macOS VM - VM must be stopped

Disk Command Quick Reference

# List all disks
vpvm config disk list ubuntu-22.04

# Add a new disk
vpvm config disk add ubuntu-22.04 --size 50

# Remove a disk
vpvm config disk remove ubuntu-22.04 --disk "Disk 2"

# Update disk settings
vpvm config disk update ubuntu-22.04 --disk "Disk 1" --cache-mode Auto

# Resize by name (VM must be stopped)
vpvm config disk resize ubuntu-22.04 --disk "Disk 1" --size 128

# Resize by UUID
vpvm config disk resize ubuntu-22.04 --disk a1b2c3d4-e5f6-7890-abcd-ef1234567890 --size 128

# Relocate macOS recovery partition
vpvm config disk relocate-recovery macos-vm --disk "Disk 1"

💾 Managing Template Disks

Template disk operations live under the template config disk subcommand group, keeping them alongside all other template configuration commands. The --disk option accepts either the disk name (e.g. "Disk 1") or its UUID — use template config disk list to see both.

Listing Template Disks

vpvm template config disk list "Ubuntu 22.04 Base"

Output:

NAME      UUID                                  SIZE    TYPE     INTERFACE
Disk 1    a1b2c3d4-e5f6-7890-abcd-ef1234567890  64 GB   Dynamic  VirtIo

Adding a Template Disk

vpvm template config disk add "Ubuntu 22.04 Base" --size 50 --interface VirtIo --type Dynamic

Removing a Template Disk

vpvm template config disk remove "Ubuntu 22.04 Base" --disk "Disk 2"

Resizing a Template Disk

# Resize by disk name
vpvm template config disk resize "Ubuntu 22.04 Base" --disk "Disk 1" --size 128

# Resize by UUID
vpvm template config disk resize "Ubuntu 22.04 Base" --disk a1b2c3d4-e5f6-7890-abcd-ef1234567890 --size 128

Requirements: - New size must be larger than the current size — shrinking is not supported

Relocating the macOS Recovery Partition on a Template Disk

After resizing a fixed disk on a macOS template, relocate the recovery partition:

vpvm template config disk relocate-recovery "My macOS Template" --disk "Disk 1"

Requirements: - Disk must be of type Fixed (not Dynamic) - Target must be a macOS template

Template Disk Quick Reference

# List template disks
vpvm template config disk list "My Template"

# Add a template disk
vpvm template config disk add "My Template" --size 50

# Remove a template disk
vpvm template config disk remove "My Template" --disk "Disk 2"

# Resize template disk by name
vpvm template config disk resize "My Template" --disk "Disk 1" --size 128

# Resize template disk by UUID
vpvm template config disk resize "My Template" --disk a1b2c3d4-e5f6-7890-abcd-ef1234567890 --size 128

# Relocate macOS recovery partition on template
vpvm template config disk relocate-recovery "My macOS Template" --disk "Disk 1"

🎈 Memory Balloon

Memory ballooning lets you adjust how much RAM a running Linux VM can use — without rebooting. The guest's virtio_balloon kernel driver cooperates with the host to inflate or deflate the balloon, reclaiming or releasing memory dynamically.

Memory balloon commands only apply to Linux VMs that have the Memory Balloon device enabled in their CPU & Memory settings. macOS guests do not support this feature.

Checking Balloon Status

vpvm balloon info <vmname>

Shows whether the balloon device is present and what the current target memory is:

  Has Balloon    : yes
  Target Memory  : 2048 MB
  Configured Max : 4096 MB

Field	Description
Has Balloon	Whether a VirtIO balloon device is configured for this VM
Target Memory	The memory the host is currently asking the guest to use
Configured Max	The total RAM the VM was created with

Example:

vpvm balloon info ubuntu-22.04

Setting the Balloon Target

vpvm balloon set <vmname> --target <MB>

Instructs the guest to use at most <MB> megabytes of RAM. The value is clamped between 256 MB and the VM's configured maximum.

Option	Description
`--target <MB>`	Target memory in megabytes

Examples:

# Ask the guest to use only 1 GB
vpvm balloon set ubuntu-22.04 --target 1024

# Restore the guest to its full configured memory
vpvm balloon set ubuntu-22.04 --target 4096

The balloon target is advisory — the guest kernel decides how much memory to actually return. Changes take effect within a few seconds on a cooperative guest.

🖥️ Server Mode

Server Mode suppresses informational and error alert popups on the host Mac, keeping the Web Dashboard responsive during remote control sessions. When enabled, alerts are logged silently instead of blocking the UI. Confirmation dialogs are always shown regardless of this setting.

Enable, disable, or query Server Mode from the terminal — useful for scripting headless or remote setups:

# Enable Server Mode
vpvm servermode --enable

# Disable Server Mode
vpvm servermode --disable

# Check current state
vpvm servermode --info

Output:

Request completed successfully.
Server mode enabled.

Request completed successfully.
Server mode is disabled.

You can also toggle Server Mode from the Tools menu or the status bar icon in the VirtualProg app — a checkmark indicates it is active.

Tip: Use vpvm servermode --info in scripts to check the current state before enabling or disabling, avoiding unnecessary toggles.

🔧 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	Env Variable	Description	Default
`--server <host>`	`VPVM_SERVER`	IP address or hostname of the remote machine	`127.0.0.1`
`--port <port>`	`VPVM_PORT`	Port the VirtualProg CLI server is listening on	Configured in VirtualProg settings
`--token <token>`	`VPVM_TOKEN`	Authentication token	Configured in VirtualProg settings
`--secure`	`VPVM_SECURE=1`	Use HTTPS instead of HTTP	`false`

Flags take priority over environment variables, which take priority over local defaults.

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

Using flags (per-command):

# 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

Using environment variables (set once):

export VPVM_SERVER=192.168.1.10
export VPVM_PORT=49152
export VPVM_TOKEN=mytoken

# All commands now connect to the remote instance automatically
vpvm list
vpvm watch
vpvm start ubuntu-22.04

This is ideal for CI pipelines, shell profiles, or scripts that always target the same remote host.

When any remote flag or environment variable 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 'ubuntu-22.04' is password protected. Run 'vpvm unlock ubuntu-22.04' to unlock it first.

Solution: Run vpvm unlock <vmname> and enter the VM password. Once unlocked, retry the operation. Use vpvm lock <vmname> to re-lock the VM when you are done.

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:

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

HTTP Server Not Available

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

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

Performance Issues

If CLI commands are slow:

Close unused VMs to free resources
Check system disk space
Restart VirtualProg to clear cache
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

# Restart VM
vpvm restart ubuntu-22.04

Snapshots

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

# List snapshots
vpvm snapshot list ubuntu-22.04

# View snapshot details
vpvm snapshot info ubuntu-22.04 before-update

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

# Create VM from snapshot
vpvm snapshot createvm ubuntu-22.04 before-update my-new-vm

# 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"

# Clone a template
vpvm template clone "My Template" "My Template Copy"

# Delete template
vpvm template delete "Old Template"

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

Configure VM

# Inspect current values before changing
vpvm config info general ubuntu-22.04
vpvm config info startup ubuntu-22.04
vpvm config info security ubuntu-22.04

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

# Enable headless mode and set a description
vpvm config general ubuntu-22.04 --headless true --descr "My dev server"

# Set a password (plain text, hashed automatically)
vpvm config security ubuntu-22.04 --password "mypassword"

# Remove the password
vpvm config security ubuntu-22.04 --clear-password

# Disable clipboard sharing
vpvm config security ubuntu-22.04 --clipboard false

# Enable auto-start
vpvm config startup ubuntu-22.04 --auto-start true

# Schedule VM start/stop (Mon–Fri, 09:00–18:00)
vpvm config schedule ubuntu-22.04 --enabled true --days "1,2,3,4,5" --start-time "09:00" --stop-time "18:00"

# List available network sources
vpvm network sources

# Add a network adapter
vpvm config network add ubuntu-22.04 --type "Default (NAT)"

# Update a network adapter
vpvm config network update ubuntu-22.04 --net "Network 1" --type "en0"

# Add port forwarding
vpvm config network pf-add ubuntu-22.04 --net "Network 1" --host-port 2222 --guest-port 22

# Configure template settings
vpvm template config cpu "My Template" --cpu 8 --memory 16384

Screenshots

# PNG screenshot (saved to current directory)
vpvm screenshot ubuntu-22.04

# Save to a specific path
vpvm screenshot ubuntu-22.04 --output ~/Desktop/vm.png

# JPEG at reduced quality
vpvm screenshot ubuntu-22.04 --format jpeg --quality 0.6 --output ~/Desktop/vm.jpg

# Screenshot from a remote instance
vpvm screenshot ubuntu-22.04 --server 192.168.1.10 --port 49152

Create VM

# List available images first
vpvm images list

# Create a Linux VM — by alias (recommended)
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu

# Create a Linux VM — by raw filename (also works)
vpvm create "My Ubuntu" --os linux --cpu 2 --memory 4096 --disk 64 --image ubuntu.iso

# Create a macOS VM (arm64 only)
vpvm create "My Mac" --os macos --cpu 4 --memory 8192 --disk 80 --image sequoia

Disks

# List VM disks (shows name, UUID, size, type, interface)
vpvm config disk list ubuntu-22.04

# Add a new disk
vpvm config disk add ubuntu-22.04 --size 50

# Remove a disk
vpvm config disk remove ubuntu-22.04 --disk "Disk 2"

# Resize a VM disk — by name or UUID (VM must be stopped)
vpvm config disk resize ubuntu-22.04 --disk "Disk 1" --size 128
vpvm config disk resize ubuntu-22.04 --disk a1b2c3d4-e5f6-7890-abcd-ef1234567890 --size 128

# Relocate macOS recovery partition on VM (fixed disks only)
vpvm config disk relocate-recovery macos-vm --disk "Disk 1"

# List template disks
vpvm template config disk list "My Template"

# Add a template disk
vpvm template config disk add "My Template" --size 50

# Resize a template disk
vpvm template config disk resize "My Template" --disk "Disk 1" --size 128

# Relocate macOS recovery partition on template
vpvm template config disk relocate-recovery "My macOS Template" --disk "Disk 1"

Networks (macOS Tahoe 26+)

# List custom networks
vpvm network list

# View details
vpvm network info "My Network"

# Create a shared network
vpvm network add "Dev Network" --type Shared --subnet 192.168.50.0

# Create a host-only network
vpvm network add "Isolated" --type Host --subnet 10.99.0.0

# Rename a network
vpvm network update "Dev Network" --new-name "Production"

# Change MTU
vpvm network update "Dev Network" --mtu 9000

# Delete a network
vpvm network delete "Old Network"

Server Mode

# Check current state
vpvm servermode --info

# Enable Server Mode (suppresses alert popups during remote sessions)
vpvm servermode --enable

# Disable Server Mode
vpvm servermode --disable

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.