Skip to content

Docs Command Line Command Line

Commands

vmpal is VMPal's command-line tool, like docker or gh. This page lists every command in short, then the rules worth knowing. Run vmpal help <command> to see a command's options, and vmpal help <topic> to read a guide.

In the tables, <VM> is a VM's name, its ID or the first 4 or more characters of it, or its .vmpal folder's path. vmpal list shows them.

Ask your AI agent

Your AI agent can do all of this for you. VMPal gives it every command's help and guides, so it can write the commands or run them. Connect it to VMPal, then ask, for example:

  • "Which vmpal command copies a folder into my Windows VM?"
  • "Clone my Ubuntu VM, run the tests in the clone, then delete it."

VMs

Command What it does
vmpal list List your VMs and what each one is doing
vmpal info <VM> Show one VM in full
vmpal systems List the systems you can install, with their IDs. It also says which ones can be Terminal only
vmpal create <system> --wait Make a VM, and wait until it's installed and can run commands
vmpal create --file <path> Install from an IPSW or ISO file instead of a system ID
vmpal create <system> --terminal-only Install Linux without a desktop
vmpal create <system> --password-file <path> Write the new VM's password to a file only you can read
vmpal clone <VM> Clone a shut-down VM. The clone is ready at once
vmpal clone <VM> --shut-down Shut the VM down first, then clone it
vmpal clone <VM> --start --wait Start the clone too, and wait until it can run commands
vmpal set <VM> --cpus 4 --memory 8 Change a VM's settings, such as hardware, shared folders, ports, network and sign-in. vmpal help set lists them all
vmpal set <VM> --display 1440x900@2x Keep the VM's display at that size in points and scale, 1x or 2x, on any screen and in the background. The window shows it scaled to fit, and clones keep it. Use it for UI tests and screenshots. window follows the window again
vmpal set <VM> --render-scale 75 Render a Windows VM's display at 75% or 50% of each side of its window, scaled up with MetalFX. Lower is faster for games the GPU holds back, and softer. 100 goes back to full size
vmpal set <VM> --user <name> Tell VMPal the account's name in the VM, for one VMPal didn't make or one renamed there. It renames nothing in the VM
vmpal delete <VM> Move a VM to the Trash
vmpal delete <VM> --force Turn a running VM off first, then move it to the Trash
vmpal delete <VM> --permanently Delete it for good, without the Trash
vmpal import <path> Import a .vmpalvm file from another Mac, or a Parallels VM. A .vmpal folder is added where it is
vmpal move <VM> <location> Move a shut-down VM to another of VMPal's locations. --wait waits until it's there
vmpal compress <VM> Pack a VM into a .vmpalvm file for another Mac. It goes on the Desktop unless --output says otherwise
vmpal cancel <VM> Stop a VM's download or move
vmpal cancel Stop the import or compression under way

vmpal help create lists create's other options: --name, --cpus, --memory, --disk, --location, --user, --install-updates for Linux, --sign-in-automatically for Windows, --start-at-login, and --no-agent-control.

CPUs, memory, GPU and a few other settings wait until the VM shuts down and starts again. vmpal restart <VM> --apply-settings does that for you.

Power

Command What it does
vmpal start <VM> --wait Start a VM, and wait until it can run commands
vmpal start <VM> --background Start it without its window. vmpal show opens the window
vmpal start <VM> --recovery Start a macOS VM in macOS Recovery
vmpal stop <VM> Shut it down
vmpal stop <VM> --force Turn it off at once, like pulling the plug
vmpal pause <VM> Pause a running VM
vmpal resume <VM> Resume a paused VM
vmpal suspend <VM> Save its session to disk and close it. vmpal start picks up where it left off
vmpal restart <VM> Restart the system in the VM
vmpal restart <VM> --apply-settings Shut it down and start it again, for settings that wait for that
vmpal restart <VM> --reset Restart it at once, like pressing a reset button
vmpal show <VM> Bring a running VM's window to the front
vmpal show <VM> --apps-on-mac Show a Windows VM's apps as Mac windows, each on its own, as View › Run Windows Apps on Mac does. A Linux VM with GPU acceleration does the same, as View › Run Linux Apps on Mac. The VM opens that way next time
vmpal show <VM> --window Bring the VM's window back in place of its apps
vmpal wait <VM> Wait until it can run commands. It gives up after 10 minutes by default
vmpal wait <VM> --until stopped Wait until it's stopped instead. --until also takes running and installed

Waits give up after 5 minutes for start, stop and clone --start, and after 10 minutes for start --wait, clone --start --wait, restart --wait and wait. create --wait, move --wait and compress --wait give up after 2 hours. --timeout sets another limit, up to 24 hours.

Inside a VM

Command What it does
vmpal exec <VM> -- <command> Run a command in the VM, like docker exec. You see its output as it comes
vmpal exec <VM> --arch x64 -- <command> Run the x64 part of a program built for both arm64 and x64. --arch arm64 runs the other
vmpal cp <from> <to> Copy files in or out, like docker cp. Write the VM side as <VM>:<path>
vmpal run <VM> -- <command> Run a command in a fresh clone of a shut-down VM, like a fresh CI runner. --copy-in and --copy-out copy files. Then VMPal deletes the clone. CI/CD says how
vmpal ssh <VM> Sign in to a Terminal only Linux VM with this Mac's ssh. You get input and a terminal
vmpal ssh <VM> -- <command> Run a command there over ssh
vmpal ssh <VM> --tty -- <command> Give the command a terminal too, like ssh -t, for programs such as top
vmpal sign-in <VM> Sign in at its sign-in screen with the password VMPal keeps
vmpal ui <VM> ... Read the screen's windows, buttons and text, and any prompt of the OS such as Windows' UAC (vmpal ui <VM> tree), click, type and take screenshots. vmpal ui help says how
vmpal status <VM> Show whether it can run commands, its screen, and who has its input
vmpal send-files <VM> <path>... Put files on its user's desktop, like dropping them there
vmpal reinstall-tools <VM> Install VMPal Tools in it again

Snapshots

A snapshot saves a VM as it is now, so you can go back to it later.

Command What it does
vmpal snapshot <VM> [name] Take a snapshot
vmpal snapshots <VM> List its snapshots
vmpal revert <VM> [name] Go back to a snapshot. Without a name, it goes back to the newest
vmpal revert <VM> --snapshot-first Keep what it has now in a new snapshot, then go back
vmpal rename-snapshot <VM> <snapshot> <new name> Rename a snapshot
vmpal delete-snapshot <VM> <snapshot> Delete a snapshot for good

Hub

These commands manage the scripts in VMPal's Hub. A script is a shell or PowerShell script that VMPal keeps and runs for you. Your AI agent does the same with VMPal's MCP tools.

<script> is a script's name, in any case, or its ID.

Command What it does
vmpal script create <name> --file <path> Add a script to VMPal's Hub. --file - reads it from standard input. A name another script has gets a number, such as "Test App 2"
vmpal script edit <script> Change its name (--name), its text (--file), its settings, or where it runs. --no-targets makes it run nowhere
vmpal script show <script> Show its settings, where it runs, its last 5 runs with their logs' paths, and its text
vmpal script list List every script, with its language, color and where it runs
vmpal script run <script> --wait Run it now, and wait for its runs to end
vmpal script stop <script> Stop its runs that are waiting or running. --run <ID> stops just one
vmpal script runs <script> List its runs, newest first, with their IDs, states, and why they failed: the 50 that ended last, and those waiting or running. --limit <n> sets how many, up to 100
vmpal script log <script> Print the newest run's log. --run <ID> prints another run's log. --tail <bytes> prints only its end
vmpal script duplicate <script> Copy a script, right after it in the Hub's list
vmpal script move <script> --before <script> Move it up or down the Hub's list. --to-end moves it to the end
vmpal script delete <script> Delete it, with its runs and their logs. Runs in progress stop

These options choose where a script runs. script create, script edit and script run take them.

Option Where the script runs
--run-in <VM> In a fresh clone of the VM, a throwaway copy like a fresh CI runner
--run-in-place <VM> In the VM itself
--host On this Mac, as you
  • script run uses them for this run alone.
  • script edit replaces where it runs with them.
  • A run waits up to 30 minutes for its VM, such as for the VM to shut down before it's cloned.

These options change a script's settings, in script create and script edit:

Option What it sets
--language powershell Makes it a PowerShell script. A .ps1 file is one already
--timeout <duration> How long a run can take. The default is 1 hour, and 24 hours at most
--color <color> Tints its row in the Hub: red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown or gray. In script edit, --color none takes it off

script run --wait exits like a CI job, so its exit code tells you whether the runs passed. In script run, --timeout is how long vmpal waits for the runs, not how long a run can take. By default, it waits the script's timeout and 35 minutes.

Phones and tablets

An iPhone, iPad, iOS simulator or Android device in VMPal's Remote section, by its name: see Phones and Tablets. vmpal start <phone> connects it, and then vmpal ui <phone> uses its screen, as a VM's.

Command What it does
vmpal device <phone> install <path> Install an app: an iPhone's .app or .ipa signed for it, a simulator's .app, or an Android .apk
vmpal device <phone> launch <bundle ID> Start it, ended first if it runs, and keep what it prints. Its own arguments go after --. --no-console keeps nothing
vmpal device <phone> logs <bundle ID> What it printed since launch started it. On Android, its logcat. --lines <n> for more or fewer
vmpal device <phone> crashes [<bundle ID>] Its crash reports, newest first. vmpal device <phone> crash <report> reads one
vmpal device <phone> apps The apps installed, not the system's
vmpal device <phone> terminate <bundle ID> End it. uninstall removes it
vmpal device <phone> rotate landscape-left Turn it: portrait, landscape-left, landscape-right or upside-down
vmpal device <phone> button home Press a button: home, volume-up or volume-down, and on Android back, recents or power
vmpal device <phone> open-url <url> Open a web page, or an app's own link
vmpal device <phone> pinch --scale 2 Pinch with two fingers, at the middle unless --x and --y say, from 0 to 1. Over 1 zooms in
vmpal device <phone> release End VMPal's test session on an iPhone or iPad, so Xcode can run your own UI tests there

Other

Command What it does
vmpal library Show VMPal's locations, its Base OS files, and the downloads, import or compression under way
vmpal add-location <path> Add a folder for VMPal to keep VMs in, such as on another disk
vmpal remove-location <path> Take a folder off VMPal's list. Its VMs stay in it
vmpal delete-base-os <id> Move a Base OS file to the Trash
vmpal diagnostics Zip VMPal's logs, crash reports and VMs' settings for a bug report, and tell you how to send it. Passwords are left out
vmpal diagnostics <VM> The same for one VM: its whole log, and only its files
vmpal diagnostics --problem <text> Describe what went wrong, for the bug report
vmpal tool <name> [<json>] Call one of VMPal's MCP tools by its name, with its arguments as JSON. --file <path> reads them from a file, and - from standard input. --show-password keeps a VM's password in the answer
vmpal help List every command
vmpal help <command> Show one command's options and guide
vmpal help <topic> Read a guide: setup, ci, exec, cp, sign-in or ui

Rules worth knowing

Commands in a VM

  • Agent control. exec, cp, run, ssh, ui and sign-in work only while the VM allows agent control, and so do waits until a VM can run commands, such as start --wait. It's on unless someone turned it off. To turn it back on, run vmpal set <VM> --agent-control on.
  • No shell. exec runs the program itself, without a shell. For pipes and &&, run a shell yourself: vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'.
  • Text output. exec reads the output as text, which changes binary output. Copy binary files with cp.
  • Administrator. --admin runs a command as administrator. In a macOS VM, an administrator must approve that in the VM first. vmpal help exec says how.
  • Time limits. exec stops a command after 2 hours, and cp after 1 hour. --timeout sets another limit, up to 24 hours. Older VMPal Tools allow 10 minutes.
  • No input. A command from exec gets no input. In a Terminal only VM, vmpal ssh gives you input.
  • Copying folders. cp works like cp -R. For example, vmpal cp . "Ubuntu:src" copies this folder's contents into src.
  • Signing in. Windows runs commands only after someone signs in. So create --wait, start --wait, wait, clone --start --wait, restart --wait and run sign in for you, with the password VMPal keeps. They do it at a Windows or macOS sign-in screen. --no-sign-in turns that off. To have Windows sign in by itself at each start, run vmpal set <VM> --sign-in-automatically on.

Exit codes

The exit code tells your script or CI job whether a command worked, as with any command-line tool.

Command Exit code
exec and run The command's own. 124 when it timed out, 125 when vmpal couldn't run it, 128 + N on signal N, and 1 for a code outside 0 to 255, such as Windows' 0xC0000005, which vmpal prints
ssh ssh's own. 255 when it couldn't connect, and 125 when vmpal couldn't start it
script run --wait 0 when every run passed. Otherwise, the run's own exit code when there was one run, or 1
Every other command 0 when it worked, 1 when it didn't, and 2 for a wrong command line

Scripts

  • Scripts on this Mac run as you. So VMPal checks its Scripts on this Mac setting whenever vmpal would make a script run here. That's --host, script run for a script that runs on this Mac, and new text for such a script. The setting has three choices:
    • Allow (agents ask you), the default, lets it through without asking.
    • Ask in VMPal asks you once for each version of the script.
    • Off refuses it.