Docs › AI agents

vmpane

Every command of the vmpane tool

VMPane's command-line tool (VMPane.app/Contents/Helpers/vmpane; vmpane install-cli puts it on the PATH). Generated by scripts/gen-cli-docs.sh from vmpane --help.

Exit codes: 0 ok, 1 failed, 64 bad arguments, 66 no such VM, 69 helper or guest agent unavailable, 75 try again (busy, wrong state), 77 refused by the VM's agent policy or the kill switch; vmpane exec exits with the command's own code.

vmpane

Code

OVERVIEW: Control VMPane virtual machines from the command line.

USAGE: vmpane <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  list                    List the VMs in the library.
  info                    Show a VM's settings and state.
  start                   Start a VM (its window shows unless --headless).
  stop                    Shut a VM down (the guest's power button), or turn it
                          off with --force.
  suspend                 Save a VM's memory to disk and stop it; it resumes at
                          the next start.
  pause                   Pause a running VM.
  resume                  Resume a paused VM.
  snapshot                Take, list, restore and delete a VM's snapshots.
  exec                    Run a command in a running VM (needs VMPane's guest
                          tools).
  cp                      Copy a file to or from a running VM: vmpane cp
                          file.txt ubuntu:/tmp/ or vmpane cp ubuntu:/etc/hosts .
  ssh                     ssh into a VM through its port forward to port 22.
  port                    Forward ports from this Mac to a VM.
  screenshot              Save a PNG of a running VM's screen.
  mcp                     Serve VMPane to an AI agent over MCP (stdio), or stop
                          all agents.
  operator                Let your own terminal use of vmpane control VMs
                          whatever their agent policy.
  install-cli             Put vmpane on your PATH (/usr/local/bin, with one
                          administrator prompt; --user: ~/.local/bin).
  doctor                  Check VMPane's installation and running VMs.
  version                 Print VMPane's version.

  See 'vmpane help <subcommand>' for detailed help.

vmpane list

Code

OVERVIEW: List the VMs in the library.

USAGE: vmpane list [--json]

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane info

Code

OVERVIEW: Show a VM's settings and state.

USAGE: vmpane info <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane start

Code

OVERVIEW: Start a VM (its window shows unless --headless).

USAGE: vmpane start <vm> [--headless] [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --headless              Run without a window.
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane stop

Code

OVERVIEW: Shut a VM down (the guest's power button), or turn it off with
--force.

USAGE: vmpane stop <vm> [--force] [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --force                 Turn it off at once, like pulling the plug.
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane suspend

Code

OVERVIEW: Save a VM's memory to disk and stop it; it resumes at the next start.

USAGE: vmpane suspend <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane pause

Code

OVERVIEW: Pause a running VM.

USAGE: vmpane pause <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane resume

Code

OVERVIEW: Resume a paused VM.

USAGE: vmpane resume <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane snapshot

Code

OVERVIEW: Take, list, restore and delete a VM's snapshots.

USAGE: vmpane snapshot <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  list                    List a VM's snapshots.
  create                  Take a snapshot (live, with memory, of a running VM;
                          of the disks of a stopped one).
  restore                 Go back to a snapshot (a running VM is turned off
                          first; what changed since is lost).
  delete                  Delete a snapshot.

  See 'vmpane help snapshot <subcommand>' for detailed help.

vmpane snapshot list

Code

OVERVIEW: List a VM's snapshots.

USAGE: vmpane snapshot list <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane snapshot create

Code

OVERVIEW: Take a snapshot (live, with memory, of a running VM; of the disks of
a stopped one).

USAGE: vmpane snapshot create <vm> <name> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <name>                  The snapshot's name.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane snapshot restore

Code

OVERVIEW: Go back to a snapshot (a running VM is turned off first; what changed
since is lost).

USAGE: vmpane snapshot restore <vm> <snapshot> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <snapshot>              The snapshot: its id or name.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane snapshot delete

Code

OVERVIEW: Delete a snapshot.

USAGE: vmpane snapshot delete <vm> <snapshot>

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <snapshot>              The snapshot: its id or name.

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane exec

Code

OVERVIEW: Run a command in a running VM (needs VMPane's guest tools).

USAGE: vmpane exec <vm> [--as <as>] [--cwd <cwd>] [--env <env> ...] [--timeout <timeout>] -- [<command> ...]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <command>               The command and its arguments, after --.

OPTIONS:
  --as <as>               user (the logged-in user) or admin (root / SYSTEM).
                          (default: user)
  --cwd <cwd>             Working directory in the guest.
  --env <env>             An environment variable, NAME=value (repeatable).
  --timeout <timeout>     Kill the command after this many seconds.
  --version               Show the version.
  -h, --help              Show help information.

vmpane cp

Code

OVERVIEW: Copy a file to or from a running VM: vmpane cp file.txt ubuntu:/tmp/
or vmpane cp ubuntu:/etc/hosts .

USAGE: vmpane cp <source> <destination> [--overwrite]

ARGUMENTS:
  <source>                From: a Mac path, or VM:path.
  <destination>           To: a Mac path, or VM:path (a path ending in / is a
                          folder).

OPTIONS:
  --overwrite             Replace an existing file.
  --version               Show the version.
  -h, --help              Show help information.

vmpane ssh

Code

OVERVIEW: ssh into a VM through its port forward to port 22.

USAGE: vmpane ssh <vm> [--user <user>] -- [<arguments> ...]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <arguments>             More ssh arguments, after --.

OPTIONS:
  -u, --user <user>       The guest user.
  --version               Show the version.
  -h, --help              Show help information.

vmpane port

Code

OVERVIEW: Forward ports from this Mac to a VM.

USAGE: vmpane port <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  list                    List a VM's port forwards and their state.
  add                     Forward a port: MAC_PORT:VM_PORT, with /udp for UDP
                          (e.g. 8080:80, 5353:53/udp).
  rm                      Remove a port forward (by id, or by its Mac port).

  See 'vmpane help port <subcommand>' for detailed help.

vmpane port list

Code

OVERVIEW: List a VM's port forwards and their state.

USAGE: vmpane port list <vm> [--json]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane port add

Code

OVERVIEW: Forward a port: MAC_PORT:VM_PORT, with /udp for UDP (e.g. 8080:80,
5353:53/udp).

USAGE: vmpane port add <vm> <mapping> [--all-interfaces]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <mapping>               MAC_PORT:VM_PORT[/udp]

OPTIONS:
  --all-interfaces        Listen on every network interface of this Mac, not
                          just on this Mac (others can then connect).
  --version               Show the version.
  -h, --help              Show help information.

vmpane port rm

Code

OVERVIEW: Remove a port forward (by id, or by its Mac port).

USAGE: vmpane port rm <vm> <forward>

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.
  <forward>               The forward's id, or its Mac port.

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane screenshot

Code

OVERVIEW: Save a PNG of a running VM's screen.

USAGE: vmpane screenshot <vm> --output <output> [--max-edge <max-edge>]

ARGUMENTS:
  <vm>                    The VM: its name, id or short id.

OPTIONS:
  -o, --output <output>   Where to save the PNG.
  --max-edge <max-edge>   Longest edge in pixels (0: full size). (default: 0)
  --version               Show the version.
  -h, --help              Show help information.

vmpane mcp

Code

OVERVIEW: Serve VMPane to an AI agent over MCP (stdio), or stop all agents.

USAGE: vmpane mcp <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  serve (default)         Serve VMPane over MCP on stdin/stdout (the default).
  kill                    Stop every AI agent now.
  config                  Add VMPane to Claude Code, Codex CLI or Gemini CLI
                          (shows the change; --apply makes it).

  See 'vmpane help mcp <subcommand>' for detailed help.

vmpane mcp serve

Code

OVERVIEW: Serve VMPane over MCP on stdin/stdout (the default).

USAGE: vmpane mcp serve

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane mcp kill

Code

OVERVIEW: Stop every AI agent now.

USAGE: vmpane mcp kill

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane mcp config

Code

OVERVIEW: Add VMPane to Claude Code, Codex CLI or Gemini CLI (shows the change;
--apply makes it).

USAGE: vmpane mcp config <client> [--apply]

ARGUMENTS:
  <client>                claude, codex or gemini

OPTIONS:
  --apply                 Make the change (the old file is kept as a backup).
  --version               Show the version.
  -h, --help              Show help information.

vmpane operator

Code

OVERVIEW: Let your own terminal use of vmpane control VMs whatever their agent
policy.

USAGE: vmpane operator <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  grant                   Allow it (asks for confirmation).
  revoke                  Take it back.
  status                  Whether this process acts as operator.

  See 'vmpane help operator <subcommand>' for detailed help.

vmpane operator grant

Code

OVERVIEW: Allow it (asks for confirmation).

USAGE: vmpane operator grant

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane operator revoke

Code

OVERVIEW: Take it back.

USAGE: vmpane operator revoke

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

vmpane operator status

Code

OVERVIEW: Whether this process acts as operator.

USAGE: vmpane operator status [--json]

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane install-cli

Code

OVERVIEW: Put vmpane on your PATH (/usr/local/bin, with one administrator
prompt; --user: ~/.local/bin).

USAGE: vmpane install-cli [--user]

OPTIONS:
  --user                  Install in ~/.local/bin, without an administrator
                          prompt.
  --version               Show the version.
  -h, --help              Show help information.

vmpane doctor

Code

OVERVIEW: Check VMPane's installation and running VMs.

USAGE: vmpane doctor [--json]

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

vmpane version

Code

OVERVIEW: Print VMPane's version.

USAGE: vmpane version [--json]

OPTIONS:
  --json                  Print JSON instead of text.
  --version               Show the version.
  -h, --help              Show help information.

Edit this page on GitHubLast updated 11 October 2026