Start, stop and lock a Proxmox VE VM from PowerShell

Start-PveGuest, Stop-PveGuest, Restart-PveGuest, Suspend-PveGuest, Resume-PveGuest, Reset-PveGuest and Unlock-PveGuest take the guests with the selection of Get-PveGuest (an id, a name, a range, @node-, @pool-, @tag-, with exclusions), find the node and the type of each one, and call the right endpoint, qemu or lxc. You do not need to know where they run.

Start-PveGuest -VmIdOrName web01
Stop-PveGuest  -VmIdOrName 100
Start-PveGuest -VmIdOrName '@tag-lab,-@node-pve03'     # every lab guest, except those on pve03

They return one PveResponse per guest, with the UPID of the task in .Response.data. Pipe them into Wait-PveTaskIsFinish to wait:

Start-PveGuest -VmIdOrName web01 | Wait-PveTaskIsFinish -Timeout 60000

When nothing matches the selection they write the error VM/CT '…' not found!.

Function	Does
`Start-PveGuest`	Starts the guest (`status/start`).
`Stop-PveGuest`	Stops it at once, like pulling the plug (`status/stop`).
`Stop-PveGuest -Shutdown`	Shuts it down cleanly, through the guest operating system (`status/shutdown`).
`Restart-PveGuest`	Reboots it cleanly, through the guest operating system (`status/reboot`).
`Suspend-PveGuest`	Pauses it (`status/suspend`).
`Resume-PveGuest`	Resumes it after a suspend (`status/resume`).
`Reset-PveGuest`	Resets a VM (`status/reset`). Containers cannot be reset: they get an error and are skipped.
`Unlock-PveGuest`	Removes the lock left by an interrupted backup, snapshot or migration (`config`, `delete=lock`).

The former names Start-PveVm, Stop-PveVm, … still work as aliases.

Shut down cleanly

Stop-PveGuest does not ask the guest to shut down: it stops it at once, and unsaved data in the guest is lost. With -Shutdown it asks the guest operating system to shut down, through ACPI or the guest agent for a VM:

Stop-PveGuest -VmIdOrName '@tag-lab' -Shutdown -Timeout 120 -ForceStop

-Timeout is how many seconds each guest has to shut down; with -ForceStop a guest that has not finished by then is stopped. A VM without an operating system that answers ACPI never shuts down by itself: only -ForceStop stops it. -Timeout and -ForceStop exist only with -Shutdown.

Restart-PveGuest reboots the same way, through the guest; its -Timeout is how long to wait for the shutdown before the guest starts again. Reset-PveGuest is the hard reset of a VM.

Unlock

A VM stays locked if an operation that locks it (backup, snapshot, migration, clone) is interrupted, and Proxmox VE refuses further operations with VM is locked. Unlock-PveGuest removes the lock, like qm unlock on a node. Do it only when you are sure the operation is no longer running.

On a VM it works only for root@pam: it sends skiplock, which Proxmox VE reserves to that account. On a container VM.Config.* privileges are enough: see Permissions.

A wide selection acts on every guest it matches: check it first with -WhatIf, which lists what would be done and does nothing: see -WhatIf and -Confirm.

Stop-PveGuest -VmIdOrName '@tag-lab,-@node-pve03' -Shutdown -WhatIf