The command line

The elyravm program drives VMs from a terminal, a script or an AI agent. In the app it is

/Applications/Elyra VM.app/Contents/MacOS/Elyra VM

and in a source checkout, target/debug/elyravm (see Building). A link on your PATH makes it elyravm:

ln -s "/Applications/Elyra VM.app/Contents/MacOS/Elyra VM" /usr/local/bin/elyravm

Commands

elyravm mcp
elyravm screenshot <vm> <file.png> [--json]
elyravm type <vm> <text> [--json]
elyravm key <vm> <keys> [--json]
elyravm click <vm> <x> <y> [--right | --middle] [--double] [--json]
elyravm move <vm> <x> <y> [--json]
elyravm scroll <vm> <x> <y> <lines> [--json]
elyravm list [--json]
elyravm start <vm> [--hidden] [--json]
elyravm status <vm> [--json]
elyravm show <vm> [--json]
elyravm pause <vm> [--json]
elyravm resume <vm> [--json]
elyravm suspend <vm> [--json]
elyravm stop <vm> [--json]
elyravm force-stop <vm> [--json]
elyravm reload <vm> [--json]
elyravm snapshot <vm> [<name>] [--json]
elyravm snapshots <vm> [--json]
elyravm restore <vm> <snapshot> [--json]
elyravm delete-snapshot <vm> <snapshot> [--json]
elyravm import <path.pvm | path.qcow2 | path.img | path.raw> [--json]
elyravm exec <vm> [-t] [--user <name> | --session] [--timeout <seconds>] [--json] -- <command> [<argument>…]
elyravm shell <vm> [--user <name>]
elyravm cp [--user <name>] <from> <to>
elyravm send <vm> [--user <name>] [--json] <file or folder>…
elyravm forwards <vm> [--json]
elyravm forward <vm> <Mac port>:<VM port>[/udp] [--public] [--json]
elyravm unforward <vm> <Mac port>[/udp] [--json]
elyravm attach <vm> <disk image> [--read-only] [--json]
elyravm detach <vm> [<disk image's name>] [--json]
elyravm licence [activate <key> | refresh | deactivate] [--json]
elyravm help

Command	Does
`list`	Every VM in the library, with its state and summary
`start`	Starts the VM in its own window and waits until it runs (up to two minutes, plus any time spent installing, whose progress it prints), or prints why it didn't start. A running VM's window comes forward instead. With `--hidden`, the VM starts without showing its window or taking the focus; its Dock icon, or `show`, brings the window up.
`status`	What the VM is doing: `stopped`, `starting`, `installing`, `running`, `paused`, `stopping` (saving or stopping) or `suspended`
`show`	Brings the VM's window to the front, and the VM's app with it
`pause`, `resume`	Freeze and unfreeze the VM
`suspend`	Saves the VM as it is and closes it
`stop`	Asks the guest to shut down
`force-stop`	Turns the VM off at once
`reload`	Makes a running VM read its `config.json` again and take in its name, shared folders and network
`snapshot`	Takes a snapshot, of a running VM too (it is paused for a moment), and waits until it is taken
`snapshots`	The VM's snapshots, oldest first: name, when, running or shut down, and the start of the id
`restore`	Rolls back to a snapshot. A running VM is turned off first, and started again from it
`delete-snapshot`	Deletes a snapshot
`import`	Imports a Linux VM from Parallels Desktop (Creating VMs), or a disk image (Creating VMs), printing how far its disk is
`exec`	Runs a command in the VM through Elyra VM Tools, as root, `--user`, or in a macOS guest the user logged in (`--session`), with its input and output as it goes; the exit code is the command's own. See Running commands
`shell`	Opens a shell in the VM in this terminal, through Elyra VM Tools, as root or `--user`; `exec -t` runs a command in a terminal. See A terminal
`send`	Copies files and folders into the Downloads of the guest's user, as dropping them on the VM's window does. See Dropping files
`cp`	Copies a file or folder into a VM or out of it, one side written `<vm>:<path>`. See Copying files
`forwards`	The VM's address on the shared network, and its forwarded ports
`forward`	Forwards a port on the Mac to one in the VM, such as `2222:22` or `5353:53/udp`; `--public` opens it to other devices. A running VM takes it at once
`unforward`	Stops forwarding a Mac port, such as `2222` or `5353/udp`
`attach`	Plugs a disk image (ISO, IMG or RAW) into a running VM as a USB stick, `--read-only` if it is to stay as it is, and waits until it is in. See Disk images as USB sticks
`detach`	Pulls a disk image out by its file's name, or every one, and waits until it is out
`screenshot`	Saves what a running VM's screen shows as a PNG file: a Windows VM's, or a Linux VM's with Elyra VM's own GPU (3D graphics); a macOS guest's is taken in it, by Elyra VM Tools, with a user logged in
`type`	Types text into a running VM, as on a US keyboard
`key`	Presses keys together and lets go: `enter`, `f5`, `ctrl+c`, `ctrl+alt+delete`, `cmd+space`, `win+r`
`click`, `move`, `scroll`	Point in a running VM, at a place in its screenshot's pixels (from the top left); `scroll` turns the wheel that many lines down (up if negative)
`mcp`	A Model Context Protocol server for AI agents: see AI agents (MCP)
`licence`	The licence on this Mac, or the trial's days left; `activate` enters a licence key, `refresh` asks for it again after renewing, `deactivate` frees this Mac's place on it. See Licence and updates

<snapshot> is a snapshot's name, in any case, or the start of its id (at least four characters).

Requests other than start and status need the VM to be running. They return as soon as the VM has taken them; ask for the status to follow them (a suspend shows stopping until it is saved, then suspended).

Naming a VM

<vm> is any of:

its name, in any case: elyravm start "web server"
the start of its id, at least four characters: elyravm stop 8c79
the path of a .elyravm folder, which needn't be in the library: elyravm start ~/VMs/Test.elyravm

Output

Without --json, results are short lines for people:

$ elyravm list
Web Server               running    2 CPU · 4 GB RAM · 1.2 GB of 128 GB · Ubuntu 26.04.1 LTS
Clean macOS              stopped    4 CPU · 8 GB RAM · 4.2 MB of 256 GB · macOS 27.0.1 (26A434)
$ elyravm pause "web server"
Web Server: paused

With --json, each command prints JSON for programs: list an array, the others one object.

{
  "id": "8c79338e895d4f80b561fe35483b32ee",
  "name": "Web Server",
  "state": "running",
  "detail": null,
  "progress": null,
  "tools": {
    "os": "linux",
    "system": "Ubuntu 26.04.1 LTS",
    "hostname": "web-server",
    "addresses": ["192.168.64.6"],
    "version": "0.9.0"
  },
  "guest": "ubuntu",
  "system": "Ubuntu 26.04.1 LTS",
  "cpus": 2,
  "memory_mib": 4096,
  "disk_bytes": 128000000000,
  "disk_used": 1203400704,
  "address": "192.168.64.6",
  "forwards": [{ "host": 2222, "guest": 22, "protocol": "tcp", "public": false }],
  "path": "/Users/you/Library/Application Support/Elyra VM/Machines/Web Server.elyravm",
  "console": "/Users/you/Library/Application Support/Elyra VM/Machines/Web Server.elyravm/console.log"
}

detail and progress say what a live VM is busy with and how far along (0 to 1), such as "Installing macOS 27.0.1 (26A434) · 42 %" and 0.42; they are null otherwise. console is the guest's serial console log, which an agent can read to follow the guest (Linux guests). tools is what Elyra VM Tools in a running VM says about it, or null when it isn't running there.

Errors and exit codes

The exit code is 0 on success and 1 on failure (exec returns the command's own, and 124 when it timed out). Errors go to stderr as error: …, or with --json to stdout as {"error": "…"}:

$ elyravm pause "web server"
error: The VM is already paused.
$ elyravm start mac
error: macOS VMs can’t be started yet; they come next.

Another library

ELYRAVM_LIBRARY points the command line, and the library window, at another folder of VMs:

ELYRAVM_LIBRARY=~/agent-vms elyravm list

Useful for an agent's own VMs, or for tests that must not touch your library.

For agents

Start with elyravm start <vm> --hidden --json, so the VM doesn't take the person's focus, and check state is running.
The systems ready to use in the catalog (Ubuntu Server, Fedora Cloud, Debian, and their desktops) are set up with no one at the screen, and have Elyra VM Tools: wait until status --json has tools, then run commands with elyravm exec <vm> -- …, and move files with elyravm cp.
Reach the VM at its address, or forward a port (elyravm forward <vm> 2222:22) and use localhost.
Wait for a change by polling status --json.
Read the guest's output from the console path.
Use suspend rather than force-stop to keep a VM's state between tasks.
Take a snapshot before a task that may break the VM, and restore after it: rolling a running VM back takes about a second. Duplicate (an instant clone) gives a task a VM of its own.
The same requests are available directly on each VM's socket; see The control protocol.