The PVE command surface, tool by tool · Proxmox VE

A Proxmox node ships roughly fifteen command-line tools, and the design is more consistent than it first appears: each tool owns one area of the system, and its name tells you which. Learning the map is worth more than memorising any individual command, because with the map you can find the command you need and without it you cannot.

The other thing worth knowing up front is that almost none of these tools do the work themselves. They are clients of the same REST API the web interface uses. That has practical consequences — for permissions, for what appears in the task log, and for what a script should call — and the mechanism section at the end covers them.

The map

Tool	Owns	Scope
`qm`	QEMU/KVM virtual machines	This node’s guests
`pct`	LXC containers	This node’s guests
`pvesm`	Storage definitions and volumes	Cluster-wide config, node-local status
`pvesh`	The API itself, as a shell	Anything the API exposes
`pvecm`	Cluster membership and quorum	Cluster-wide
`pveum`	Users, groups, roles, ACLs, API tokens	Cluster-wide
`pveceph`	Ceph deployment and lifecycle	Cluster-wide
`pvenode`	Node-level operations, tasks, certificates	This node
`ha-manager`	HA resources, groups and CRM commands	Cluster-wide
`pvesr`	Storage replication jobs (ZFS)	Cluster-wide config
`vzdump`	Taking backups	This node’s guests
`qmrestore`	Restoring a VM backup	This node
`pvesubscription`	Subscription key and repository entitlement	This node
`pveperf`	A quick node benchmark	This node
`pvereport`	Evidence collection for support	This node
`proxmox-boot-tool`	The ESP, bootloader and kernel entries	This node
`pveversion`	Package versions	This node

The scope column is the one that catches people. qm and pct act on guests on the node you are logged into; pveum and pvecm change state that every node sees immediately. Running the wrong one on the wrong node is the difference between a mistake and an incident.

`qm` — virtual machines

Read-only / Safewhat VMs are on this node, and what is one of them made of?— Read-only. qm list covers this node only; for a cluster-wide view use pvesh get /cluster/resources. qm config shows the configuration as stored, including any pending changes.

qm list

VMID=100
qm config "$VMID"
qm status "$VMID" --verbose

Read-only / Safeqm list, and what the columns mean— Illustrative. MEM is the configured memory in MiB, not what the guest is using. BOOTDISK is the primary disk size. PID is the QEMU process, and its absence is how you tell 'stopped' from 'the process died'.

# qm list

      VMID NAME                 STATUS     MEM(MB)    BOOTDISK(GB) PID
     100 db-primary           running    32768              500 2841
     101 web-01               running     8192               50 3012
     102 web-02               running     8192               50 3188
     141 reporting            running    16384              200 4402
     150 staging-old          stopped    16384              100 0

Illustrative output

The two qm subcommands that repay learning early are less obvious than start and stop.

Read-only / Safewhat QEMU command line does this configuration produce?— Read-only. showcmd renders the exact qemu-system invocation PVE would use. It is the fastest way to answer 'is this option actually taking effect' and the first thing to attach to a bug report.

VMID=100
qm showcmd "$VMID" --pretty

Read-only / Safeqm showcmd tells you what PVE really did with your config— Illustrative and abridged. Reading this is how you confirm that iothread, aio and cache settings reached QEMU rather than being silently ignored.

# qm showcmd 100 --pretty

/usr/bin/qemu-system-x86_64 \
-id 100 \
-name 'db-primary,debug-threads=on' \
-smp '8,sockets=1,cores=8,maxcpus=8' \
-cpu 'x86-64-v3,+aes,+pdpe1gb' \
-m 32768 \
-object 'iothread,id=iothread-virtioscsi0' \
-device 'virtio-scsi-pci,id=virtioscsi0,iothread=iothread-virtioscsi0' \
-drive 'file=/dev/zvol/rpool/data/vm-100-disk-0,if=none,id=drive-scsi0,\
cache=none,aio=io_uring,discard=on,format=raw' \
-machine 'type=pc-q35-10.0+pve0'

Illustrative output

Read-only / Safewhich disks does this VM own, and where do they live?— Read-only. Answers the question that precedes every storage migration and every 'can I delete this volume' decision.

VMID=100
qm config "$VMID" | grep -E '^(scsi|virtio|sata|ide|efidisk|tpmstate)[0-9]*:'

pvesm list local-zfs --vmid "$VMID"

`pct` — containers

pct mirrors qm deliberately: list, config, start, stop, shutdown, status, set, destroy all behave the same way. Three subcommands have no qm equivalent because they exploit the fact that a container shares the host kernel.

Read-only / Safeget inside a container, and move files without a network— Read-only in the sense that these commands do not themselves change state, but pct enter gives you a root shell inside the container, from which anything is possible. There is no equivalent for a VM because a VM has its own kernel.

CTID=205

pct list
pct config "$CTID"

# a root shell inside, no SSH and no network required
pct enter "$CTID"

Configuration changecopy a file in or out without networking— Writes a file into or out of the container filesystem from the host. Useful precisely when the container's network is broken, which is when you most need it.

CTID=205

pct push "$CTID" /root/fix.sh /root/fix.sh --perms 0755
pct pull "$CTID" /var/log/syslog /root/ct205-syslog

pct exec "$CTID" -- systemctl status nginx

`pvesm` — storage

Read-only / Safewhat storage exists, is it up, and what is on it?— Read-only. status is the first command in any storage incident: it shows each storage's type, whether it is active, and its usage.

pvesm status

pvesm list local-zfs
pvesm path local-zfs:vm-100-disk-0

Read-only / Safepvesm status, and the column that matters— Illustrative. Active 0 on a storage that should be up is the finding — it means the node cannot reach the backend right now, which is a different problem from the storage being full.

# pvesm status

Name             Type     Status           Total            Used       Available        %
backup-pbs        pbs     active     41943040000     18294419456     23648620544   43.62%
ceph-rbd          rbd     active      8796093022      3221225472      5574867550   36.62%
local             dir     active        98564608        14203392        79322112   14.41%
local-zfs     zfspool     active      1717986918       412316860      1305670058   24.00%
nfs-iso           nfs   inactive               0               0               0    0.00%

Illustrative output

Storage entries have a content type — images, rootdir, vztmpl, iso, backup, snippets, import — and a storage only accepts the types it declares. The documentation defines them as: images for “QEMU/KVM VM images”, rootdir to “allow to store container data”, vztmpl for “container templates”, backup for “backup files (vzdump)”, iso for “ISO images”, snippets for “snippet files, for example guest hook scripts”, and import for “OVAs and VM disk images that can be imported from this storage”.

'Storage does not support content type' is a configuration error, not a bug

The commonest pvesm surprise is a backup, restore or VM creation failing with a message about an unsupported content type. It reads like a defect and it is a one-line configuration fix.

A storage entry declares which content types it will hold. A dir storage created for ISOs will refuse a VM disk; a zfspool created without rootdir will refuse a container. The check is pvesm status --content images or reading /etc/pve/storage.cfg, and the fix is pvesm set STORAGE --content images,rootdir with the full list you want — the option replaces rather than appends, so omitting an existing type silently removes it.

Getting this wrong in the other direction is worse and quieter: adding backup to a storage that holds VM disks means vzdump will happily fill your production pool with backup files.

`pvesh` — the API as a shell

pvesh is “a shell interface for the Proxmox VE API” that, in the man page’s words, “allows to directly invoke API function, without using the REST/HTTPS server”. Five subcommands map onto HTTP methods:

`pvesh`	HTTP	Use
`get`	GET	Read
`set`	PUT	Modify an existing object
`create`	POST	Create, or invoke an action
`delete`	DELETE	Remove
`ls`	—	List child nodes of a path
`usage`	—	Print the API documentation for a path

Read-only / Safeexplore the API without leaving the shell— Read-only. ls walks the tree; usage prints the parameters a path accepts, which is faster than the online API viewer and is guaranteed to match the version installed on this node.

pvesh ls /nodes
pvesh ls /cluster

pvesh usage /nodes/{node}/qemu/{vmid}/status/start --verbose

Read-only / Safethe single most useful pvesh call— Read-only. /cluster/resources is the cluster-wide inventory: every guest, storage and node, with status and usage, from any node. This is the one to reach for when qm list only shows you one node's worth.

pvesh get /cluster/resources --type vm --output-format json | jq -r \
'.[] | [.vmid, .name, .node, .status] | @tsv'

Read-only / Safeevery guest in the cluster, and where it is— Illustrative. The node column is what makes this different from qm list: it answers 'where is VM 141 right now', which after an HA failover is not a question you can answer from any single node.

# pvesh get /cluster/resources --type vm --output-format json | jq -r '.[] | [.vmid, .name, .node, .status] | @tsv'

100	db-primary	pve-01	running
101	web-01	pve-01	running
102	web-02	pve-02	running
141	reporting	pve-03	running
205	dns-01	pve-02	running
150	staging-old	pve-02	stopped

Illustrative output

--output-format accepts json, json-pretty, text and yaml, with text as the default. Scripts should always pass json: the text format is a human-readable table whose columns can change between versions, and parsing it is how automation breaks at an upgrade.

`pvecm` — cluster membership

Read-only / Safeis this node in the cluster, and does the cluster have quorum?— Read-only. status is the first command in any cluster incident. The Quorate line is the one that determines whether /etc/pve is writable.

pvecm status
pvecm nodes

Read-only / Safepvecm status on a healthy three-node cluster— Illustrative. Expected votes 3, Total votes 3, Quorate Yes. If Total votes drops below Quorum, /etc/pve goes read-only and no guest configuration can be changed anywhere.

# pvecm status

Cluster information
-------------------
Name:             pve-prod
Config Version:   7
Transport:        knet
Secure auth:      on

Quorum information
------------------
Date:             Wed Aug 12 14:31:08 2026
Quorum provider:  corosync_votequorum
Nodes:            3
Node ID:          0x00000001
Ring ID:          1.4f2
Quorate:          Yes

Votequorum information
----------------------
Expected votes:   3
Highest expected: 3
Total votes:      3
Quorum:           2
Flags:            Quorate

Illustrative output

pvecm expected is not a first response to an outage

pvecm expected 1 lowers the expected vote count so a minority partition becomes “quorate”. It is presented in a great deal of forum advice as the way to get a cluster working again.

It is a recovery tool for a cluster you have already established cannot regain quorum by normal means, used with the other nodes confirmed powered off, not merely unreachable. Applied to a network partition where the other nodes are alive and doing the same thing, you get two partitions both convinced they are authoritative, both writing to /etc/pve, and both starting the same HA guests against the same disks.

The correct first response to a quorum loss is to find out why the nodes cannot see each other. pvecm status on each reachable node, then corosync-cfgtool -s for link state, then the network.

`pveum` — access control

Read-only / Safewho has access to what?— Read-only. The ACL list is the authoritative answer to 'who can do this', and it is worth reading before granting anything, because permissions inherit down the path tree.

pveum user list
pveum role list
pveum acl list
pveum token list root@pam

Configuration changecreate a scoped automation identity— Creates a user, a token with privilege separation, and an ACL limited to one path. privsep 1 means the token carries only the permissions granted to the token itself, not the user's. The secret is printed once and cannot be retrieved again.

pveum user add automation@pve --comment "CI pipeline"
pveum acl modify /vms/100 --users automation@pve --roles PVEVMAdmin
pveum user token add automation@pve ci --privsep 1

pveum acl list

`pvenode` — the node itself

pvenode is the tool most operators discover last and then use daily, because it owns the task log.

Read-only / Safewhat has this node been doing?— Read-only. task list is the node's history: every backup, migration, start, stop and snapshot, with its UPID and exit status. This is where you look after 'something happened last night'.

pvenode task list --limit 20

pvenode config get
pvenode cert info

Read-only / Safepvenode task list, with a failure in it— Illustrative. The Status column is the whole point: OK for success, anything else is the error string. Copy the UPID and feed it to pvenode task log for the full output.

# pvenode task list --limit 6

UPID                                                       Type       Status
UPID:pve-01:00006A2F:04C1B2E1:6A7C83E0:vzdump:100:root@pam: vzdump     OK
UPID:pve-01:00006B41:04C2F011:6A7BD3F1:vzdump:101:root@pam: vzdump     OK
UPID:pve-01:00006C88:04C41A02:6A7BD3A3:vzdump:141:root@pam: vzdump     job errors
UPID:pve-01:00007012:04C88811:6A7C2A18:qmigrate:102:root@pam: qmigrate OK
UPID:pve-01:000071A0:04C9C401:6A7C3B04:qmstart:150:root@pam: qmstart   OK
UPID:pve-01:00007244:04CA1180:6A7C4D90:qmsnapshot:100:root@pam: qmsnapshot OK

Illustrative output

Service impact possiblebulk guest operations for a maintenance window— migrateall moves every guest off this node to the named target; startall and stopall act on every guest on this node. These are the correct tools for draining a node, and they respect each guest's startup order and delay.

TARGET=pve-02

pvenode migrateall "$TARGET" --maxworkers 2

# after maintenance
pvenode startall

`ha-manager`, `pvesr`, `pveceph`

Read-only / Safewhat is HA managing, and what does the CRM think?— Read-only. status shows the master, each node's LRM state, and every managed resource with its current and requested state. A node in 'wait_for_agent_lock' is the usual sign of trouble.

ha-manager status
ha-manager config

Read-only / Safereplication and Ceph status— Read-only. pvesr status shows each ZFS replication job's last run and next run; pveceph status is the PVE-flavoured wrapper around ceph -s.

pvesr status
pvesr list

pveceph status
pveceph pool ls

Backup, restore and evidence

Service impact possibletake a backup by hand— Runs a backup immediately rather than on a schedule. Snapshot mode is the least disruptive; the guest keeps running. bwlimit is in KiB/s and is the control that stops a manual backup saturating shared storage.

VMID=100

vzdump "$VMID" --storage backup-pbs --mode snapshot --bwlimit 102400 --notes-template '{{guestname}} manual'

Destructiverestore a VM from a backup— Restoring onto an existing VMID overwrites that VM entirely, including its disks. Restore to an unused VMID first and verify, unless you have specifically decided to overwrite.

NEWID=900
qmrestore /var/lib/vz/dump/vzdump-qemu-100-2026_08_12-02_00_03.vma.zst "$NEWID" --storage local-zfs

qm config "$NEWID"

Read-only / Safecollect everything at once for a support case— Read-only. pvereport gathers versions, storage, network, cluster, disk and guest configuration into one stream. Redirect it to a file. It is the single most useful command to run before opening a ticket, and it is worth running while a node is still misbehaving rather than after a reboot.

pvereport > "/root/pvereport-$(hostname)-$(date +%F).txt"

wc -l "/root/pvereport-$(hostname)-$(date +%F).txt"

Read-only / Safeversions, subscription and boot configuration— Read-only. pveversion -v is what every forum answer will ask you for. proxmox-boot-tool status tells you which bootloader the node uses, which decides where kernel command-line changes go.

pveversion -v
pvesubscription get
proxmox-boot-tool status

Which tool answers which question?

The question	The command
What is on this node?	`qm list`, `pct list`
Where in the cluster is guest N?	`pvesh get /cluster/resources --type vm`
Why did last night’s backup fail?	`pvenode task list`, then `pvenode task log UPID`
Is the cluster quorate?	`pvecm status`
Is the storage reachable?	`pvesm status`
What can this user actually do?	`pveum acl list`
Did my disk option reach QEMU?	`qm showcmd VMID --pretty`
What is HA about to do?	`ha-manager status`
What do I attach to a support case?	`pvereport`, `pveversion -v`
Where do kernel parameters go on this node?	`proxmox-boot-tool status`
What parameters does this API path take?	`pvesh usage PATH --verbose`

Under the hood

What these tools actually are, and why it matters for scripting.

Almost every pve* command is a thin Perl client over the same REST API that serves the web interface. qm start 100 and a click on Start in the GUI both end up at POST /nodes/{node}/qemu/{vmid}/status/start, run the same permission check, and create the same task.

Four consequences that change how you write automation.

Permissions are identical across interfaces. There is no CLI back door. A token that cannot start a VM through curl cannot start it through qm either, and a role that works in the GUI works in a script. This is why pveum is worth learning properly: it is the single place access is decided, for every interface at once.

pvesh bypasses the HTTP layer, not the API. The man page says it invokes API functions “without using the REST/HTTPS server” — meaning it calls the handler in-process rather than making a network request. It still goes through the same authentication, authorisation and parameter validation. The practical effects are that it is faster, that it works when pveproxy is down but pvedaemon is up, and that it runs as the Unix user you are logged in as, so root@pam is implied when you are root.

Everything that changes state becomes a task with a UPID. qm start returns as soon as the task is created, not when the VM is running. In a shell that is invisible because the command usually completes fast; in a script it is the single most common source of race conditions, and the tasks-and-UPIDs lesson is entirely about it.

Some commands are proxied to another node automatically. qm and pct operate on the local node’s guests, but the API path they call carries a node name, and PVE will forward the request to the node that owns the resource. This is why pvesh get /nodes/pve-03/qemu/141/config works from pve-01, and why --noproxy exists for the cases where you specifically want to talk to the local daemon and see it fail rather than be silently redirected.

The design conclusion for automation: prefer the API path over the tool when writing anything durable. pvesh get /cluster/resources --output-format json returns a documented, versioned structure. qm list returns a table formatted for a human, whose columns are not a stable interface and have changed between releases. Scripts built on the second break at an upgrade, and they break by silently parsing the wrong column rather than by erroring.

What happens if you run qm or pct on the wrong node?

Usually nothing, in a way that teaches you the wrong lesson — and occasionally something expensive. The distinction is worth having clear before you are typing at 2 a.m.

qm list on the wrong node just shows you the wrong list. There is no error, because there is nothing wrong: it is doing exactly what it says, for the node you are on. This is the common case, it is harmless, and it is how people acquire the belief that qm is cluster-aware. It is not.

qm config 141 for a guest that lives elsewhere fails cleanly, with a configuration-file-not-found error. Also harmless, also instructive.

qm destroy 141 when a different guest holds VMID 141 on this node is the expensive case. VMIDs are unique cluster-wide in normal operation, so this requires an unusual state to have arisen — most often a restore that was performed onto a node while the original still existed elsewhere, or a guest recreated by hand during an incident. When it does arise, the command finds a local VM 141, and destroys it. There is no prompt, and disks are removed.

The cluster-wide tools have the opposite failure mode, and it is more dangerous because it is silent. pveum, pvecm and pveceph change state that every node reads from /etc/pve immediately. Running pveum acl delete from the “wrong” node has exactly the same effect as running it from the right one, so there is no wrong node and no protective error — the mistake is in the command, and it propagates in under a second.

How to make this a non-issue. Two habits, both cheap.

Confirm where a guest is before acting on it, from any node: pvesh get /cluster/resources --type vm gives you VMID and node in one line. If the guest is elsewhere, either SSH there or use the API path with the correct node name and let PVE proxy the call.

And put the node name in your shell prompt. It sounds trivial next to the consequences, and it prevents more of these than any amount of care does, because the failure mode is never carelessness — it is a second terminal window that looks identical to the first.

Common mistakes

Treating qm list as a cluster view. It shows one node. pvesh get /cluster/resources --type vm is the cluster inventory.
Parsing pvesh text output in a script. It is a human table. Always pass --output-format json.
Using qm stop when qm shutdown was meant. stop is the power cable; shutdown sends ACPI and lets the guest flush its filesystems.
pvesm set --content without listing every type you want. The option replaces the list; omitting a type removes it.
Reaching for pvecm expected 1 during a quorum loss. It is a recovery tool for nodes you have confirmed are powered off, not a first response to a partition.
Restoring onto an existing VMID. qmrestore overwrites it, including disks, without a prompt.
Running pvereport after rebooting the node. Collect the evidence while the fault is present.
Not knowing which bootloader the node uses. proxmox-boot-tool status answers it; guessing means editing a file nothing reads.

Key takeaways

Each tool owns one area, and its name says which. Learn the map, not the commands.
qm and pct are node-scoped; pvecm, pveum, pveceph and ha-manager change cluster-wide state that propagates immediately.
pvesh is the API as a shell, with get/set/create/delete mapping to GET/PUT/POST/DELETE, plus ls and usage for exploring.
pvesh get /cluster/resources is the cluster-wide inventory that qm list is not.
pvenode task list and pvenode task log are where you find out what happened overnight.
qm showcmd --pretty proves whether a configuration option actually reached QEMU.
Storage entries declare content types; “does not support content type” is configuration, not a bug, and pvesm set --content replaces the list rather than appending to it.
pvereport collects everything a support case needs, and should be run while the fault is still present.
Every pve* tool is a client of the same API with the same permission checks, so scripts should call documented API paths with JSON output rather than parse human-formatted tables.

Knowledge check

Why this matters

The GUI is genuinely good, and for most day-to-day work it is the right tool. So the argument for learning this command surface is not that clicking is inferior — it is that three specific situations are much harder without it, and all three are situations where you are already under pressure.

The GUI is unavailable. pveproxy is what serves the web interface, and it is a separate process from pvedaemon, which does the work. A node whose web interface will not load is frequently a node where pvesh and qm work perfectly. Knowing that turns a “the cluster is down” call into a ten-minute fix.

The question spans more than one screen. “Which guests have cpulimit set?” is a single line at the command line and an afternoon of clicking. So is “which storages accept content type backup”, “which tasks failed last night across all nodes”, and “which VMs are still on machine type pc-q35-8.1”. The GUI answers questions about one object at a time; the estate-wide questions are the ones that turn into incidents.

You need a record. A command and its output can be pasted into a ticket, a runbook, a change record or a support case. A sequence of clicks cannot, which means GUI work is reconstructed from memory afterwards and reconstructed differently by each person who does it.

There is a fourth reason that only becomes apparent later. Everything in this part — the API, tokens, Terraform, Ansible, Proxmoxer, webhooks — sits on top of the same interface these tools use. An operator who understands that qm start is a POST to a documented path, that it returns a UPID rather than a result, and that the same permission check applies whichever route you take, can pick up any of those tools quickly. An operator who has memorised commands has to learn each one from scratch. The map is the thing worth having.

The map

qm — virtual machines

pct — containers

pvesm — storage

pvesh — the API as a shell

pvecm — cluster membership

pveum — access control

pvenode — the node itself

ha-manager, pvesr, pveceph

Backup, restore and evidence

Which tool answers which question?

Common mistakes

Key takeaways

Knowledge check

`qm` — virtual machines

`pct` — containers

`pvesm` — storage

`pvesh` — the API as a shell

`pvecm` — cluster membership

`pveum` — access control

`pvenode` — the node itself

`ha-manager`, `pvesr`, `pveceph`