CLI Reference

The vmctl command-line tool provides full control over GhostVM virtual machines from the terminal.

vmctl --help

macOS VM Commands

init

Create a new macOS VM bundle.

vmctl init <bundle-path> [options]

Options:
  --cpus N              Number of virtual CPUs (default: 4)
  --memory GiB          Memory in GiB (default: 8)
  --disk GiB            Disk size in GiB (default: 256)
  --restore-image PATH  Path to IPSW restore image
  --shared-folder PATH  Host folder to share with guest
  --writable            Make shared folder writable

install

Install macOS from the restore image in the VM bundle.

vmctl install <bundle-path>

Common Commands

list

List all VMs in the current root directory with their state. Running VMs show their socket path.

vmctl list

start

Launch a VM.

vmctl start <bundle-path> [options]

Options:
  --headless             Run without a GUI window
  --shared-folder PATH   Host folder to share with guest
  --writable             Make shared folder writable (use with --shared-folder)
  --read-only            Make shared folder read-only (use with --shared-folder)

stop

Graceful shutdown.

vmctl stop <bundle-path>

status

Report running state and configuration.

vmctl status <bundle-path>

resume

Resume from suspended state.

vmctl resume <bundle-path> [options]

Options:
  --headless             Run without a GUI window
  --shared-folder PATH   Host folder to share with guest
  --writable             Make shared folder writable (use with --shared-folder)
  --read-only            Make shared folder read-only (use with --shared-folder)

discard-suspend

Discard the suspended state so the VM boots fresh.

vmctl discard-suspend <bundle-path>

snapshot

Manage VM snapshots.

vmctl snapshot <bundle-path> list
vmctl snapshot <bundle-path> create <name>
vmctl snapshot <bundle-path> revert <name>
vmctl snapshot <bundle-path> delete <name>

socket

Print the Unix socket path for a running VM. Useful for command substitution with other tools.

vmctl socket <bundle-path>

remote

Execute commands against a running VM via its Host API socket. Requires --name or --socket to identify the VM.

vmctl remote --name <VMName> [--json] <subcommand> [args...]
vmctl remote --socket <path> [--json] <subcommand> [args...]

Subcommands:
  health                     Check VM connection status
  exec <command> [args...]   Run a command in the guest
  clipboard get              Get guest clipboard contents
  clipboard set <text>       Set guest clipboard contents
  apps                       List running guest applications
  interactive                Start interactive REPL

Examples

Full macOS workflow
# Create and install a macOS VM
vmctl init ~/VMs/dev.GhostVM --cpus 6 --memory 16 --disk 128
vmctl install ~/VMs/dev.GhostVM
vmctl start ~/VMs/dev.GhostVM

# Create a checkpoint
vmctl snapshot ~/VMs/dev.GhostVM create clean-state

# Later: revert to clean state
vmctl snapshot ~/VMs/dev.GhostVM revert clean-state
Remote commands
# Run a command inside the guest
vmctl remote --name dev exec uname -a

# Get the guest clipboard
vmctl remote --name dev clipboard get

# List running apps
vmctl remote --name dev apps

# Use socket path with command substitution
vmctl remote --socket $(vmctl socket ~/VMs/dev.GhostVM) interactive
VM CloneVM Bundles