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 runuses them for this run alone.script editreplaces 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,uiandsign-inwork only while the VM allows agent control, and so do waits until a VM can run commands, such asstart --wait. It's on unless someone turned it off. To turn it back on, runvmpal set <VM> --agent-control on. - No shell.
execruns the program itself, without a shell. For pipes and&&, run a shell yourself:vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'. - Text output.
execreads the output as text, which changes binary output. Copy binary files withcp. - Administrator.
--adminruns a command as administrator. In a macOS VM, an administrator must approve that in the VM first.vmpal help execsays how. - Time limits.
execstops a command after 2 hours, andcpafter 1 hour.--timeoutsets another limit, up to 24 hours. Older VMPal Tools allow 10 minutes. - No input. A command from
execgets no input. In a Terminal only VM,vmpal sshgives you input. - Copying folders.
cpworks likecp -R. For example,vmpal cp . "Ubuntu:src"copies this folder's contents intosrc. - Signing in. Windows runs commands only after someone signs in. So
create --wait,start --wait,wait,clone --start --wait,restart --waitandrunsign in for you, with the password VMPal keeps. They do it at a Windows or macOS sign-in screen.--no-sign-inturns that off. To have Windows sign in by itself at each start, runvmpal 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
vmpalwould make a script run here. That's--host,script runfor 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.