Skip to content

CLI reference

gpuvm.ps1, at the root of the repository, is a shortcut for the GpuVM module. Run it from PowerShell 7 as administrator to create and modify VMs. (The app doesn’t need this: it carries its own PowerShell 7 and the GpuVM service runs the module for it.)

Terminal window
./gpuvm.ps1 <command> [-Parameter value ...]
  • Without a command (or with an unknown one) it prints the list of commands.
  • If it’s started from Windows PowerShell 5.1, it runs itself again in PowerShell 7 with the same arguments.
  • Parameters are written as in PowerShell: -Name value, a switch alone (-Start), or -Name:value (-Confirm:$false). A negative number after a parameter is a value, not another parameter.
  • Help for each command: Get-Help <Cmdlet> -Detailed.
Command Cmdlet What it does
check Test-GpuVMHost Checks whether the PC is ready to create a VM with the given profile.
new New-GpuVM Creates a Windows 10/11 VM with the host GPU, installed unattended from an ISO.
set Set-GpuVM Changes an existing VM that is off (profile or override).
list Get-GpuVM Lists the VMs created with GpuVM and whether their GPU driver matches the host’s.
sync-driver Sync-GpuVMDriver Copies the host’s GPU driver into the guest.
connect Connect-GpuVM Opens the VM in Moonlight, leaving everything ready on its own.
client-install Install-GpuVMClient Installs Moonlight on the host with winget.
components-update Update-GpuVMComponent Looks for new versions of the streaming components.
remove Remove-GpuVM Removes the VM from Hyper-V.
rename Rename-GpuVM Renames the VM with its folder and disk.
repair Repair-GpuVMState Rebuilds the state file of a VM created with GpuVM.
profiles Get-GpuVMProfile Lists profiles, or shows one resolved.
lab-new New-GpuVMLab Opens a lab.
lab-add Add-GpuVMLabResult Records a measurement in a lab.
lab Get-GpuVMLab Lists labs, or shows one with its comparison.
lab-close Close-GpuVMLab Closes a lab with its conclusion.
Parameter Default
-Profile balanced Profile to check against.
-Override Hashtable merged over the profile.

Checks Windows edition, administrator rights, virtualization, Hyper-V, partitionable GPUs, GPU selection on Windows 10, network switch, the profile against your hardware, free memory, the GPU, disk space, Moonlight and the streaming components.

Parameter Default
-Name required Letters, numbers, _ or -, up to 40 characters.
-IsoPath required Windows 10/11 ISO.
-Profile balanced
-Override Hashtable merged over the profile.
-Edition profile’s guest.edition (Pro) Windows edition from the ISO.
-Credential asks Local account of the guest.
-Start Start the VM when it’s created.

-Name (required), -Profile, -Override. The VM must be off. Without -Profile it starts from the VM’s current settings; with -Profile it keeps the disk, folder and Moonlight preferences.

-Name (default *). Shows name, state, profile, backend, CPU, memory, GPU, driver version, whether the driver is in sync and the edition.

-Name (required), -ShutdownIfRunning (shuts the VM down, syncs and starts it again). Use it after updating the NVIDIA driver.

Parameter
-Name Required.
-Resolution For example 2560x1440.
-Fps 10–480.
-BitrateKbps Moonlight bitrate.
-Codec auto, H.264, HEVC or AV1.
-App Sunshine app to open (default Desktop).
-Pair Pair again even if already paired.
-Monitor The monitor to open on: an id from Get-GpuVMMonitor, or primary. Without it, the one saved for the VM, or the primary one.
-MemoryGB 4–256. Opens with this much memory when the VM doesn’t fit as configured (saved, like changing it on the machine’s page).

Values given here apply to this connection only; the defaults come from the VM’s streaming.client (set with Set-GpuVMStreamingClient), where an FPS of 0 means the refresh rate of the monitor it opens on. connect returns when Moonlight shows the first frame; if the VM is already open in Moonlight (and -Pair isn’t given), it brings that window to the front instead. A VM that is off, saved or paused while it waits for the VM’s address fails at once.

No parameters. Does nothing if Moonlight is already installed.

-Name (one or more components: sunshine, vdd, nefcon, usbip, vigembus; all by default, except those on hold). Supports -WhatIf. See Streaming.

-Name (required), -DeleteDisk (also deletes the VM folder and disk; can’t be undone).

-Name and -NewName (required). The VM must be off. Renames it in Hyper-V, its folder and disk, and keeps its settings, Moonlight pairing and shared disks. The new name follows the same rules as new; if a step fails, what was already renamed is undone.

-Name (required), -Profile (default balanced), -Override. Rebuilds gpuvm.json of a VM created with GpuVM whose state was lost. The VM must be off. If the guest hasn’t booted yet, it also recovers the Sunshine password from its disk.

-Name, -Override. Without a name it lists the profiles; with a name it shows the profile with inheritance and override applied.

Parameter Default
-Title required
-Hypothesis required
-VM
-BaselineProfile balanced
-BaselineOverride
-CandidateProfile
-CandidateOverride

-Lab, -Variant (baseline or candidate), -Metric, -Value (all required), -Unit, -LowerIsBetter, -Notes.

-Lab (optional).

-Lab, -Status (adopted, rejected or inconclusive), -Conclusion (all required).

Terminal window
./gpuvm.ps1 check -Profile max-performance # check the PC
./gpuvm.ps1 new -Name win11 -IsoPath D:\Win11.iso -Profile max-performance -Start
./gpuvm.ps1 client-install # install Moonlight on the host (once)
./gpuvm.ps1 connect -Name win11 # see the VM with the GPU (starts and pairs if needed)
./gpuvm.ps1 list # VMs and whether their driver matches the host's
./gpuvm.ps1 sync-driver -Name win11 # after updating the NVIDIA driver (VM off)
./gpuvm.ps1 set -Name win11 -Profile balanced # switch profile (VM off)
./gpuvm.ps1 rename -Name win11 -NewName games # rename (VM off)
./gpuvm.ps1 remove -Name win11 # add -DeleteDisk to delete the disk too
Terminal window
Import-Module ./src/GpuVM/GpuVM.psd1

Besides the cmdlets above, the module exports these, used mainly by the app:

Cmdlet What it does
Get-GpuVMOverview Every Hyper-V VM with its state and live usage (CPU, memory, GPU), created with GpuVM or not. For GpuVM machines, options.diskBudget says how far its disk can grow, counting the room promised to the other machines on that drive.
Get-GpuVMHostInfo Host threads, memory and GPU name, and as disk the room a new machine’s disk has on GpuVM’s drive once every machine’s disk there is full, keeping 20 GB for Windows.
Get-GpuVMIsoList Windows ISOs in Downloads and Desktop.
Invoke-GpuVMPower -Action Start, Shutdown, TurnOff, Restart, Pause or Resume on any VM.
Set-GpuVMGuestCredential Saves the guest account (DPAPI) so GpuVM can fix things inside the VM through PowerShell Direct.
Set-GpuVMStreamingClient Changes how Moonlight opens the VM. Doesn’t need the VM off. See below.
Set-GpuVMCapture -Name, -Mode wgc (the default: Windows.Graphics.Capture, the picture shows right after connecting and exclusive fullscreen is captured) or ddx (desktop duplication: shows Windows’ administrator prompts in the stream). Applied right away if the VM is running (restarts Sunshine), otherwise on the next open. See Capture modes.
Get-GpuVMAdminPrompt The Windows administrator prompts open in running GpuVM machines captured with wgc: name, id, app, publisher. Reads Hyper-V’s data exchange only (about 100 ms, no PowerShell Direct); the app polls it every 2 s.
Resolve-GpuVMAdminPrompt -Name, -Answer Allow or Deny, -PromptId (the id from Get-GpuVMAdminPrompt). Presses Yes or No in the VM, only if that prompt is still the one open; otherwise it fails and presses nothing. Needs the guest password. See Administrator prompts.
Update-GpuVMSettings Applies processor, memory or GPU even if the VM is running: validates, shuts it down, applies and starts it again; restores the previous settings if it can’t start.
Get-GpuVMHome What the app’s Home shows: the last machine opened, which machines fit in memory and what needs attention.
Stop-GpuVMAll Shuts down every running GpuVM machine cleanly, all at once.
Send-GpuVMClipboard Puts text into the VM’s clipboard (only from the PC to the VM).
Set-GpuVMNetworkIsolation Turns the VM’s network isolation on (the default) or off.
Get-GpuVMCleanup / Set-GpuVMCleanup The Windows cleanup levels / applies one to a VM.
Get-GpuVMMonitor This PC’s monitors, left to right (id, name, size, refresh rate, which one is primary), to choose where a VM opens.
Get-GpuVMApp / Install-GpuVMApp The app catalog / installs apps in a VM (starts it if needed). Apps already installed are left as they are; -Reinstall uninstalls them first and installs them again.
Get-GpuVMInstalledApp -Name. The catalog apps installed in a VM: checked inside Windows while it runs, the last ones seen while it is off.
Uninstall-GpuVMApp -Name, -App. Uninstalls apps with each one’s own uninstaller, silently (starts the VM if needed). Battle.net’s has no silent mode: it opens on the VM’s desktop to finish there.
Add-GpuVMIso / Remove-GpuVMIso Remembers an ISO in the library / forgets it (the file stays).
Get-GpuVMDisk / Restore-GpuVM / Remove-GpuVMDisk The disks in the GpuVM folder / creates a VM again from a kept disk / deletes a free disk.
Get-GpuVMBase / Remove-GpuVMBase The prepared Windows bases (one per ISO and edition) / deletes one; the next VM with that Windows prepares it again.
Save-GpuVMProfile / Remove-GpuVMProfile Creates or updates a user profile / deletes it.
New-GpuVMTemplate / Get-GpuVMTemplate / Remove-GpuVMTemplate Saves a stopped VM as a template / lists templates / deletes one no VM is built on.
New-GpuVMSharedDisk / Get-GpuVMSharedDisk / Connect-GpuVMSharedDisk / Disconnect-GpuVMSharedDisk / Import-GpuVMSharedDisk / Remove-GpuVMSharedDisk Shared disks: create, list, attach, detach, copy a folder of this PC into one, delete.

Through the app, Remove-GpuVM, Remove-GpuVMDisk, Remove-GpuVMBase, Remove-GpuVMSharedDisk and Remove-GpuVMTemplate also need a UAC confirmation (Architecture).

Parameter
-Name Required.
-Resolution For example 2560x1440.
-Fps 10–480, or 0 for the host monitor’s refresh rate, read every time the VM opens.
-BitrateKbps 0–500000; 0 lets Moonlight choose it from the resolution and FPS.
-Codec auto, H.264, HEVC or AV1.
-DisplayMode fullscreen, windowed (a resizable window the size of the resolution) or borderless.
-VSync $true or $false. Unset leaves it as is.
-FramePacing $true or $false. Turned off whenever V-Sync is off.
-Mouse capture (the VM takes the mouse, for games) or absolute (the pointer moves freely, as in remote desktop).
-Monitor The monitor Moonlight opens on: an id from Get-GpuVMMonitor, primary, or default to follow the app’s choice in Settings.
Terminal window
Set-GpuVMStreamingClient -Name win11 -Fps 0 -VSync $true -FramePacing $false -Mouse capture # the "Games" use