Skip to content

Docs Command Line

Command Line

vmpal runs VMPal from Terminal, scripts and CI: create and start VMs, run commands in them, copy files in and out, and delete them when you're done.

Install

vmpal comes inside VMPal. Link it into a folder on your PATH:

sudo ln -sf /Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine /usr/local/bin/vmpal

Learn it from your AI agent

The quickest way to learn vmpal is to ask your coding agent. VMPal gives it vmpal's full help and guides, for the VMPal you have.

  1. In VMPal, open Settings › AI Agents and turn on Let coding agents on this Mac manage all VMs.
  2. Click Add to Claude Code, or the button for Codex, Grok Build or Antigravity, and restart the agent.
  3. Ask it, for example:
    • "Show me VMPal's command line."
    • "Set up a GitHub Actions job that runs my tests in a fresh Ubuntu VM."
    • "Write a script that copies this project into my Windows VM and builds it."

The agent writes the commands or the script, explains them, and runs them if it has a terminal on this Mac.

Or read its help

vmpal help              # every command
vmpal help run          # one command's options, and its guide
vmpal help ci           # a guide: setup, ci, exec, cp, sign-in or ui

The basics

  • A VM is its name ("Windows 11"), its ID or the first 4 or more characters of it, or its .vmpal folder's path. vmpal list shows them. In cp's <VM>:<path>, use its name or ID.
  • Output is plain text. --json prints JSON for scripts; -q prints only IDs.
  • Exit status: 0 when it worked, 1 when it didn't, 2 for a wrong command line. exec and run exit with the command's own status.
  • It never asks. What it can't do fails, with the reason. Waits give up at their --timeout.
  • Commands inside a VM (exec, cp, run, ui, sign-in) need the VM's Settings › AI Agents › Allow agent control of this VM. It's on unless someone turned it off. vmpal set <VM> --agent-control on turns it back on.