vmcli: A Practical Guide for the VMware Fusion and Workstation Command Line

The command line is still the fastest way to script power state, disks, snapshots, and guest operations on with VMware Fusion (macOS) and VMware Workstation (Windows and Linux).

vmcli ships with both desktop hypervisors so you can drive the same lifecycle steps without opening the GUI.. Same lifecycle steps, no GUI.

This post covers the main modules with copy-and-paste examples.

Always confirm flags on your build with vmcli <module> --help and vmcli <vmx> <module> <command> --help, since Fusion and Workstation revisions do not always stay in lockstep.

Basic Syntax¶

vmcli is the cross-platform CLI for Fusion and Workstation. Each functional area (power, snapshots, storage, networking, guest operations) is a module with its own sub-commands. The usual shape is:

vmcli <vmx location> <module> <command> [args]

Global Options¶

Default Install Locations¶

CI runners and daemons often lack the same PATH as an interactive shell. Point scripts at the real binary when vmcli is not on PATH:

On Linux hosts, resolve the Workstation package path for your distro, or install location, then call that absolute path from automation.

If your host responds with vmcli: command not found, the binary is probably fine, but your PATH needs updating.

JSON Output for Scripting¶

Several query style commands accept -f json so you can parse output with jq or your language's JSON decoder instead of scraping plain text. Sub-command spelling is case sensitive (query vs Query), so match vmcli <module> --help on your build.

If -f json is missing on a sub-command, fall back to the default text layout or upgrade the desktop hypervisor build.

Core Modules and Commands¶

1. Power Operations (Power module)¶

Stop, Suspend, and Reset need -o <opType>; other rows below do not.

Power Start optional flags:

Valid -o opType values for Stop, Suspend, and Reset:

2. VM Management (VM & VMTemplate modules)¶

To create a new VM, use the VM module. Note that -g accepts a numeric preset and -c accepts any custom guest OS string.

vmcli VM Create -n myVM -d ~/Desktop/ -c arm-ubuntu-64

The VMTemplate module is used for creating and deploying VM templates natively from the command line.

3. Snapshot Management (Snapshot module)¶

Snapshots give you quick checkpoints for testing and rollbacks. Commands that target an existing snapshot take a <uid> integer. Run Snapshot query first to list UIDs.

!!! warning "Deleting and Reverting Snapshots" The VM must be powered off or suspended before using Snapshot Delete. Always run Snapshot query first to confirm the correct UID.

4. Hardware and Storage (Disk, Ethernet, Nvme, Sata modules)¶

Disk module. Create, extend, query, and configure virtual disks:

Valid -a adapter types for Disk Create: ide, buslogic, lsilogic (use lsilogic for all other types).

Valid -t disk types for Disk Create:

Ethernet module. Configure virtual network adapters:

Other Hardware Modules:

5. Configuration (ConfigParams module)¶

Read and write raw .vmx keys (RAM, CPU, nested virt, display name, and many hardware toggles).

Set bios.forceSetupOnce to TRUE for a one-time visit to firmware or EFI setup on the next boot; the hypervisor clears it after that cycle.

6. Shared Folders (HGFS module)¶

The Host Guest File System (HGFS) module manages the Shared Folders feature between host and guest. VMware Tools must be installed and running in the guest.

On many Fusion vmcli builds, HGFS sub-commands use the .vmx slot label (sharedFolder0, sharedFolder1, …), not an arbitrary string. Create the slot with SetPresent sharedFolder0 true (or matching ConfigParams entries), then set host path, guest name, and ACLs. Arbitrary labels such as projects alone are rejected until that slot exists.

7. Guest Operations (Guest module)¶

The Guest module executes operations directly inside a running VM. VMware Tools must be running for guest-side calls. Commands that start programs or touch the filesystem need -u <username> and -p <password>. Guest query omits -u / -p on supported builds, but the VM must still be powered on (offline returns an error). Confirm with vmcli <vmx> Guest query --help on your SKU.

8. VMware Tools (Tools module)¶

9. Other Modules (MKS, Chipset, VProbes)¶

10. USB Devices (USB module)¶

Some Workstation (and occasional Fusion) builds expose a USB module. vmcli --help must list USB under Available modules; otherwise every vmcli … USB … invocation fails with Invalid/unrecognized argument "USB"`.

When the module exists:

Device identifiers come from USB Query output; treat them as opaque strings.

11. Full VM clones (Clone module)¶

Separate from Snapshot Clone, some Workstation builds expose a top-level Clone module. Confirm with vmcli --help: many Fusion vmcli builds do not list Clone, so vmcli <vmx> Clone … fails the same way as a missing USB module.

Where Clone exists, sub-command names and flags have shifted across releases (CreateLinked, Create -t linked, and similar). Run vmcli Clone --help on the machine that will execute the job, then pin your automation to that text.

Practical Examples¶

Examples use VMX for the .vmx path and dirname "$VMX" for sibling files (extra disk, screenshots, logs). Use zsh or bash. On Windows, set VMX in the environment your script uses before each vmcli invocation.

!!! note "Where the .vmx path is" VM Create layout differs by product (flat folder vs *.vmwarevm bundle). Set VMX to the real .vmx after creation.

1. Create, tune, power on, optional firmware boot¶

vmcli VM Create -n test_vm -d ~/Desktop/ -c ubuntu-64
export VMX="$HOME/Desktop/test_vm.vmx"

vmcli "$VMX" ConfigParams SetEntry memsize 8192
vmcli "$VMX" ConfigParams SetEntry numvcpus 4
vmcli "$VMX" ConfigParams SetEntry vhv.enable TRUE
vmcli "$VMX" ConfigParams query | grep -E "memsize|numvcpus|vhv"

vmcli "$VMX" Power Start

# Optional: firmware or EFI setup on the *next* boot only (cleared after that boot)
# vmcli "$VMX" ConfigParams SetEntry bios.forceSetupOnce TRUE
# vmcli "$VMX" Power Start

2. Extra disk, JSON checks, screenshot¶

vmcli "$VMX" Disk Create \
  -f "$(dirname "$VMX")/test_vm-data.vmdk" \
  -a lsilogic \
  -s 50GB \
  -t 0
vmcli "$VMX" Disk query

# Same `-f json` calls as the table under "JSON output for scripting"
vmcli "$VMX" Power query -f json
vmcli "$VMX" Snapshot query -f json
vmcli "$VMX" Guest query -f json
vmcli "$VMX" Tools Query -f json
vmcli "$VMX" MKS captureScreenshot "$(dirname "$VMX")/test_vm-console.png"

3. Network (NAT to Bridged)¶

vmcli "$VMX" Ethernet query
vmcli "$VMX" Ethernet SetConnectionType ethernet0 bridged
vmcli "$VMX" Ethernet SetNetworkName ethernet0 "VMnet0"

4. Shared folders (HGFS)¶

shareLabel is the sharedFolderN slot (see the HGFS module table above).

vmcli "$VMX" HGFS SetPresent sharedFolder0 true
vmcli "$VMX" HGFS SetHostPath sharedFolder0 ~/Projects
vmcli "$VMX" HGFS SetGuestName sharedFolder0 projects
vmcli "$VMX" HGFS SetEnabled sharedFolder0 true
vmcli "$VMX" HGFS SetReadAccess sharedFolder0 true
vmcli "$VMX" HGFS SetWriteAccess sharedFolder0 true

5. VMware Tools¶

vmcli "$VMX" Tools Query
vmcli "$VMX" Tools Install
vmcli "$VMX" Tools Upgrade

6. Snapshots¶

vmcli "$VMX" Snapshot Take pre-upgrade -d "State before upgrading kernel"
vmcli "$VMX" Snapshot query
vmcli "$VMX" Power Stop -o trySoft
vmcli "$VMX" Snapshot Revert 1
# VM must be off or suspended to delete snapshots
vmcli "$VMX" Snapshot Delete 1
# When you need to drop child snapshots too, use -d before the UID (see `Snapshot Delete --help` on your build)
# vmcli "$VMX" Snapshot Delete -d 1

7. Guest Operations (Credentials)¶

Guest run, file copy, and ps need -u and -p (see the Guest module above). Export GUEST_PASS yourself; don't paste real passwords into shell history.

!!! warning "Credential Handling" Yes, -p on the command line is ugly. So is storing the password in a script file. For automation, use environment variables or a secrets manager and pass them at runtime instead of hard-coding them.

# Set GUEST_PASS in your environment before running these lines (never log real values).

vmcli "$VMX" Guest run -u root -p "$GUEST_PASS" \
  /bin/bash -c "apt-get update && apt-get upgrade -y"

vmcli "$VMX" Guest copyTo -u admin -p "$GUEST_PASS" \
  /path/on/host/nginx.conf /etc/nginx/nginx.conf

vmcli "$VMX" Guest copyFrom -u admin -p "$GUEST_PASS" \
  /var/log/syslog "$(dirname "$VMX")/guest-syslog.txt"

vmcli "$VMX" Guest ps -u admin -p "$GUEST_PASS"

vmcli "$VMX" Guest run -u admin -p "$GUEST_PASS" -nw \
  /usr/bin/python3 /opt/scripts/bootstrap.py

Demos¶

Two short screen recordings from a local Fusion Ubuntu guest (paths match a *.vmwarevm bundle on macOS). Keep "$VMCLI" quoted so VMware Fusion.app paths don't split at the space.

Snapshots, Tools, Power and Guest Query

Copy Host File to Guest, then List

Treat vmcli as a thin wrapper over desktop hypervisor operations: set VMX once per script or session, call one module at a time, and lean on --help when a flag changes between Fusion and Workstation builds.

!!! tip "Quick Reference" Run vmcli <module> --help for module-level syntax, and vmcli <vmx> <module> <sub-command> --help for a specific operation.