VM Management CLI Guide

TL;DR — The Commands You Actually Use Every Day

What you want to do	Command
See all VMs and their status	`qm list`
Open a console on a VM (no SSH needed)	`qm terminal <vmid>` — exit with Ctrl+O
Start a stopped VM	`qm start <vmid>`
Cleanly shut down a VM	`qm shutdown <vmid>`
Kill a VM that won't respond	`qm stop <vmid>`
Reboot a VM	`qm reboot <vmid>`
See a VM's config	`qm config <vmid>`
Change a setting	`qm set <vmid> --memory 4096`
Verify guest agent is talking	`qm agent <vmid> ping`
Take a snapshot before changes	`qm snapshot <vmid> pre-upgrade`
Roll back a snapshot	`qm rollback <vmid> pre-upgrade`
Run a command in the guest	`qm guest exec <vmid> -- uptime`

That covers 90% of day-to-day use. The sections below go deeper on each topic, and the Advanced Operations section covers disk management, cloud-init, migration, diagnostics, and the full command reference.

Listing VMs

qm list

Sample output:

      VMID NAME                 STATUS     MEM(MB)    BOOTDISK(GB) PID
       100 giraffe              running       49152        200.00 2847301
       200 flamingo             running        2048         32.00 2847618
       304 pangolin             running        2048         32.00 136623
       900 tapir                running        4096         32.00 2848012
       910 okapi                running        4096         32.00 2848199

Column	Meaning
`VMID`	Numeric ID used in all `qm` commands
`NAME`	Friendly name set at creation time
`STATUS`	`running`, `stopped`, or `paused`
`MEM(MB)`	RAM allocated to the VM
`BOOTDISK(GB)`	Size of the primary disk
`PID`	Host kernel PID of the QEMU process (running VMs only)

Serial Console — qm terminal

Once a VM has a serial port configured, you can open a direct console from the Proxmox host without needing SSH or the web UI's noVNC viewer.

qm terminal <vmid>

Example session:

starting serial terminal on interface serial0 (press Ctrl+O to exit)

giraffe login: david
Password:
Last login: Fri Mar 20 08:14:22 UTC 2026

david@giraffe:~$

The serial terminal is a raw connection over a virtual UART — no network stack involved. It works even when SSH is down, the network is misconfigured, or the VM is mid-boot. It's the right tool for editing /etc/netplan/, recovering from a bad sshd config, or watching boot output.

Setting Up Serial Console

Why it might not work

Serial port not added to the Proxmox VM config
Guest OS not configured to output to ttyS0
VM was started before the serial port was added — needs a full stop/start (not just a reset)

1 Add the serial port in Proxmox

Run on the Proxmox host:

qm set <vmid> --serial0 socket

2 Configure the guest OS

SSH into the VM and run:

# Tell the kernel to output to both VGA and serial
sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8"/' /etc/default/grub
sudo update-grub

# Enable a login prompt on ttyS0
sudo systemctl enable serial-getty@ttyS0.service

3 Restart the VM from Proxmox

qm stop <vmid>
qm start <vmid>

4 Verify

qm terminal <vmid>
starting serial terminal on interface serial0 (press Ctrl+O to exit)

# Stop all in parallel, then start
for id in 200 304 900 910; do qm stop $id --timeout 15 & done; wait
for id in 200 304 900 910; do qm start $id; done

Starting, Stopping, and Restarting

# Start a stopped VM
qm start <vmid>

# Graceful shutdown — sends ACPI signal, OS shuts down cleanly
qm shutdown <vmid>

# Force stop — equivalent to pulling the power plug
qm stop <vmid>

# Graceful reboot
qm reboot <vmid>

# Hard reset — like hitting the reset button, no ACPI
qm reset <vmid>

Command	Guest OS notified?	Use when
`qm shutdown`	Yes (ACPI)	Normal off — lets the OS flush disks and run shutdown hooks
`qm stop`	No	Guest is frozen or unresponsive; don't care about clean shutdown
`qm reboot`	Yes (ACPI)	Normal restart
`qm reset`	No	Hard restart when the guest won't respond to ACPI

Checking VM Status

# Single VM
qm status <vmid>

# All VMs
qm list

qm status 100
status: running

Viewing and Modifying Config

qm config <vmid>

Sample output:

agent: enabled=1,type=virtio
boot: order=scsi0
cores: 6
machine: q35
memory: 49152
name: giraffe
net0: virtio=BC:24:11:C1:2E:67,bridge=vmbr0
serial0: socket
vga: serial0

Modifying config with qm set

# Change memory (takes effect on next boot)
qm set <vmid> --memory 8192

# Add serial port
qm set <vmid> --serial0 socket

# Enable QEMU guest agent
qm set <vmid> --agent enabled=1,type=virtio

# Change core count
qm set <vmid> --cores 4

# Set boot order
qm set <vmid> --boot order=scsi0

QEMU Guest Agent

The guest agent runs inside the VM and lets Proxmox communicate with it directly over a virtio-serial channel. It enables IP reporting in the web UI, filesystem freeze before snapshots, and graceful shutdown when the guest agent is present.

Check agent status from Proxmox

# Ping the agent — no output means success
qm agent <vmid> ping

# Get IP addresses reported by the guest
qm agent <vmid> network-get-interfaces

# Get agent version and capabilities
qm agent <vmid> info

Enable in VM config

qm set <vmid> --agent enabled=1,type=virtio

Install in guest (Ubuntu / Debian / Kali)

sudo apt-get install -y qemu-guest-agent
sudo systemctl start qemu-guest-agent

Snapshots

# Create a snapshot
qm snapshot <vmid> <name> --description "before upgrade"

# List snapshots for a VM
qm listsnapshot <vmid>

# Roll back to a snapshot
qm rollback <vmid> <name>

# Delete a snapshot
qm delsnapshot <vmid> <name>

Cloning

# Full clone — independent copy, no dependency on the source
qm clone <vmid> <new-vmid> --name <new-name> --full

# Linked clone — shares base storage, much faster and smaller on disk
qm clone <vmid> <new-vmid> --name <new-name>

Linked clones are useful for spinning up test VMs quickly from a template. Full clones are better for long-lived VMs that shouldn't be affected if the source is modified or deleted.

Running Commands via Guest Agent

Run a command inside a VM without SSH, as long as the guest agent is running:

qm guest exec <vmid> -- <command>

# Examples
qm guest exec 100 -- uptime
qm guest exec 100 -- bash -c "df -h /"

Sending Keystrokes — qm sendkey

qm sendkey injects a keypress directly into a running VM — useful when the VM is not responding to ACPI signals, or when you need to interact with something at the console (BIOS, bootloader, a locked screen) without being physically present.

qm sendkey <vmid> <key>

Common examples

# Send Ctrl+Alt+Delete (reboot or unlock screen depending on OS)
qm sendkey 100 ctrl-alt-delete

# Press Enter (confirm a prompt, advance through a bootloader menu)
qm sendkey 100 ret

# Send Escape (exit a menu, cancel a dialog)
qm sendkey 100 esc

# Send a single character
qm sendkey 100 y

This is particularly useful when a VM has a hung console that won't respond to normal input, or when you need to interact with a GRUB menu or BIOS setup screen remotely without opening the noVNC viewer.

Advanced Operations

Less common commands for disk management, cloud-init, migrations, diagnostics, and VM import. If you found what you needed above, you can stop here.

Disk Operations

Resize a disk

# Grow disk by 20GB (use +size to grow, bare size to set absolute)
qm disk resize <vmid> scsi0 +20G

# After resizing the Proxmox disk, extend the partition inside the guest too
# (usually via growpart / resize2fs / lvextend depending on the OS)

Move a disk to different storage

# Move scsi0 from local-lvm to a different storage pool
qm disk move <vmid> scsi0 ceph-pool --delete

Import an existing disk image

# Import a qcow2/raw/vmdk image as a new disk for a VM
qm disk import <vmid> /path/to/disk.qcow2 local-lvm

Detach / remove a disk

# Unlink (detach) a disk — use --purge to also delete the storage volume
qm disk unlink <vmid> --idlist scsi1
qm disk unlink <vmid> --idlist scsi1 --purge

Rescan storage

# Force Proxmox to rescan and detect disk changes
qm disk rescan

Cloud-init Management

For VMs provisioned with cloud-init (user, SSH keys, network injected at first boot).

# Show the rendered cloud-init config that will be injected (user/network/meta)
qm cloudinit dump <vmid> user
qm cloudinit dump <vmid> network

# Show pending cloud-init changes not yet applied to the ISO
qm cloudinit pending <vmid>

# Regenerate the cloud-init ISO after config changes
qm cloudinit update <vmid>

VM Lifecycle

Suspend and resume

# Suspend VM to disk (saves RAM state)
qm suspend <vmid>

# Resume a suspended VM
qm resume <vmid>

Convert a VM to a template

# Convert a stopped VM into a template (irreversible — clone it first if unsure)
qm template <vmid>

Templates can't be started directly — they're designed to be cloned. This is the standard way to create a golden image in Proxmox: provision a VM, configure it, then convert to template.

Destroy a VM

# Delete a VM and all its disks (VM must be stopped)
qm destroy <vmid>

# Also purge from jobs and replication config
qm destroy <vmid> --purge

View pending config changes

# Show config changes that have been set but require a reboot to take effect
qm pending <vmid>

Set a guest password via agent

# Change a user's password inside the guest (requires guest agent)
qm guest passwd <vmid> <username>

Migration

Live migrate to another node (same cluster)

# Live migrate a running VM to another cluster node
qm migrate <vmid> <target-node>

# Force offline migration (VM will be stopped)
qm migrate <vmid> <target-node> --online 0

# Migrate with storage mapping (if storage names differ between nodes)
qm migrate <vmid> <target-node> --targetstorage local-lvm

Remote migrate (different Proxmox cluster)

# Migrate a VM to a completely separate Proxmox cluster
qm remote-migrate <vmid> [<target-vmid>] <target-endpoint> \
  --target-bridge vmbr0 \
  --target-storage local-lvm

Diagnostics & Recovery

Show the QEMU command line

# Print the exact qemu-system-x86_64 command Proxmox would use to start the VM
qm showcmd <vmid>

Useful for debugging passthrough flags, verifying machine type, or understanding exactly how a VM is configured at the QEMU level.

QMP monitor

# Open a QEMU Machine Protocol (QMP) monitor session for a running VM
qm monitor <vmid>

The QMP monitor is a low-level JSON protocol interface directly into the running QEMU process. You can query device state, eject media, trigger savevm, and more. Type help inside the monitor for available commands.

Unlock a stuck VM

# Remove a stuck lock on a VM (e.g., after a failed migration or snapshot)
qm unlock <vmid>

Wait for a VM to reach a specific state

# Block until the VM reaches 'stopped' or 'running' — useful in scripts
qm wait <vmid> --timeout 60

Check async guest exec status

# Check the result of a previously started qm guest exec command
qm guest exec-status <vmid> <pid>

Importing VMs

Import a disk image

# Import a raw/qcow2/vmdk disk to Proxmox storage, attach later with qm set
qm import <vmid> /path/to/disk.img --storage local-lvm

Import an OVF / OVA appliance

# Import a VM exported as OVF/OVA (from VMware, VirtualBox, etc.)
qm importovf <vmid> /path/to/vm.ovf local-lvm

# For a .ova file, extract it first:
tar -xf vm.ova
qm importovf <vmid> vm.ovf local-lvm

Enroll Secure Boot EFI keys

# Enroll Microsoft/default Secure Boot keys into the VM's EFI store
qm enroll-efi-keys <vmid>

Required when setting up a new UEFI VM with Secure Boot enabled. Enrolls the standard Microsoft and distro-vendor keys so a signed bootloader (shim, GRUB) will be accepted.

Full Command Reference

Every qm subcommand, in one place.

Command	What it does
`qm list`	List all VMs and their status
`qm status <vmid>`	Show status of a single VM
`qm start <vmid>`	Start a stopped VM
`qm shutdown <vmid>`	Graceful shutdown via ACPI
`qm stop <vmid>`	Force stop (power cut)
`qm reboot <vmid>`	Graceful reboot via ACPI
`qm reset <vmid>`	Hard reset (no ACPI)
`qm suspend <vmid>`	Suspend VM to disk
`qm resume <vmid>`	Resume a suspended VM
`qm terminal <vmid>`	Open serial console (exit: Ctrl+O)
`qm sendkey <vmid> <key>`	Inject a keypress into the VM
`qm monitor <vmid>`	Open raw QMP monitor session
`qm config <vmid>`	Show VM configuration
`qm set <vmid> [OPTIONS]`	Modify VM configuration
`qm pending <vmid>`	Show config changes pending a reboot
`qm showcmd <vmid>`	Print the raw QEMU command line
`qm snapshot <vmid> <name>`	Create a snapshot
`qm listsnapshot <vmid>`	List all snapshots
`qm rollback <vmid> <name>`	Roll back to a snapshot
`qm delsnapshot <vmid> <name>`	Delete a snapshot
`qm clone <vmid> <newid>`	Clone a VM
`qm create <vmid>`	Create a new VM
`qm destroy <vmid>`	Delete a VM and its disks
`qm template <vmid>`	Convert VM to template
`qm migrate <vmid> <node>`	Migrate to another cluster node
`qm remote-migrate <vmid> ...`	Migrate to a different Proxmox cluster
`qm unlock <vmid>`	Remove a stuck lock
`qm wait <vmid>`	Block until VM reaches a state (for scripts)
`qm disk resize <vmid> <disk> <size>`	Grow or shrink a disk
`qm disk move <vmid> <disk> <storage>`	Move disk to different storage
`qm disk import <vmid> <source> <storage>`	Import a disk image file
`qm disk unlink <vmid> --idlist <disk>`	Detach/delete a disk
`qm disk rescan`	Force rescan of storage volumes
`qm cloudinit dump <vmid> <type>`	Show rendered cloud-init config
`qm cloudinit pending <vmid>`	Show pending cloud-init changes
`qm cloudinit update <vmid>`	Regenerate the cloud-init ISO
`qm guest exec <vmid> -- <cmd>`	Run a command via guest agent
`qm guest exec-status <vmid> <pid>`	Check status of async guest exec
`qm guest passwd <vmid> <user>`	Set a guest user password via agent
`qm import <vmid> <source>`	Import a disk image to storage
`qm importovf <vmid> <manifest> <storage>`	Import OVF/OVA from VMware/VirtualBox
`qm enroll-efi-keys <vmid>`	Enroll Secure Boot EFI keys
`qm cleanup <vmid> ...`	Clean up after a failed operation
`qm vncproxy <vmid>`	Start a VNC proxy for web console
`qm nbdstop <vmid>`	Stop an NBD server started for disk access
`qm mtunnel`	Internal migration tunnel (used by Proxmox internals)
`qm help`	Show help for a command

Quick Reference

Task	Command
List all VMs	`qm list`
Open serial console	`qm terminal <vmid>`
Exit serial console	Ctrl + O
Start VM	`qm start <vmid>`
Graceful shutdown	`qm shutdown <vmid>`
Force stop	`qm stop <vmid>`
Reboot	`qm reboot <vmid>`
Hard reset	`qm reset <vmid>`
View config	`qm config <vmid>`
Modify config	`qm set <vmid> --<option> <value>`
Ping guest agent	`qm agent <vmid> ping`
Get IPs from guest	`qm agent <vmid> network-get-interfaces`
Create snapshot	`qm snapshot <vmid> <name>`
List snapshots	`qm listsnapshot <vmid>`
Roll back snapshot	`qm rollback <vmid> <name>`
Clone VM	`qm clone <vmid> <new-vmid> --name <name> --full`
Run command in guest	`qm guest exec <vmid> -- <command>`
Send keystrokes to VM	`qm sendkey <vmid> <key>`