API calls

Everything the Proxmox VE web interface does goes through its REST API. cv4pve-cli api calls that API directly, on any path, with the account of the current context. The paths and parameters are those of the Proxmox VE API viewer, and cv4pve-cli can show them itself, see below.

Call a path

cv4pve-cli api <method> <path> [--key value ...]

Command	HTTP	Use it to
api get	GET	Read
api set	PUT	Change a configuration
api create	POST	Create something, or run an action (start, snapshot, migrate…)
api delete	DELETE	Remove something

cv4pve-cli api get /cluster/resources --type vm
cv4pve-cli api set /nodes/pve01/qemu/100/config --memory 4096 --cores 2
cv4pve-cli api create /nodes/pve01/qemu/100/snapshot --snapname before-update
cv4pve-cli api create /nodes/pve01/qemu/100/status/start
cv4pve-cli api delete /nodes/pve01/qemu/100/snapshot/before-update

Parameters use the names of the API, in the order you like:

• --key value or --key=value;
• --key followed by another --key, or last, is sent as true (--force);
• quote values with spaces: --description "Before the update".

A parameter given twice, or a value without a --key before it, stops the command with exit code 6 before anything is sent.

--dry-run shows the call instead of sending it:

$ cv4pve-cli api set /nodes/pve01/qemu/100/config --memory 4096 --delete --dry-run
Dry run, nothing sent to Proxmox VE:
PUT /nodes/pve01/qemu/100/config
  memory: 4096
  delete: true

api asks no confirmation

api set, create and delete run as soon as you press Enter. Check the call with --dry-run first, or use a context with a read-only token.

Find your way in the API

api ls lists what is under a path: D marks a path with children, c a path that accepts create. Paths that stand for objects (nodes, VMs, storages) are read from the cluster.

$ cv4pve-cli api ls /nodes/pve01
Dr---        apt
-r---        config
Dr---        disks
Dr--c        lxc
Dr--c        qemu
-r--c        status
Dr---        storage
Dr---        tasks
…

api usage shows what a path accepts. Write the path with placeholders ({node}, {vmid}) or with real values; add a method to see only that one, -v for the description of every parameter, --returns for the fields of the answer:

$ cv4pve-cli api usage /nodes/{node}/qemu/{vmid}/snapshot
USAGE: get /nodes/{node}/qemu/{vmid}/snapshot
USAGE: create /nodes/{node}/qemu/{vmid}/snapshot --snapname <string> [OPTIONS]

cv4pve-cli api usage /nodes/{node}/qemu/{vmid}/snapshot create -v

param	type	description
description	<string>	A textual description or comment.
snapname	<string>	The name of the snapshot.
vmstate	<boolean>	Save the vmstate

Printed after USAGE: create … --snapname [OPTIONS] and the description of the call, Snapshot a VM.

Tab completion does the same while you type: paths, node names, VM IDs, parameter names and their allowed values.

Output

Answers are printed as a table. An object becomes a key / value table with every key, sorted by key; a list becomes one row per item, sorted by the first column; a single value is printed as it is.

As in pvesh, a list shows the columns the API schema describes (numbered keys such as net0 included). When the answer has more, their names are printed on standard error after the table; --all-columns (-A) shows them all, and json/jsonpretty always have every column.

$ cv4pve-cli api get /nodes
…
+ 4 more columns: disk, id, maxdisk, type (use --all-columns or -o json)

As in pvesh, values the API schema describes as sizes, percentages, durations or dates are printed as text (251.51 GiB, 4.44%, 3d 2h 5m 1s, 2026-09-30 14:22:23 in local time) and aligned right; nested values are printed as JSON. --human-readable false (or 0) prints them as the API returns them (bytes, fractions, seconds, Unix time); json and jsonpretty always do.

--output (-o) chooses the format:

Format	What you get
text	Table with borders, the default
json	The same rows as a JSON array, on one line
jsonpretty	The same, indented
markdown	Markdown table, to paste in a ticket or a wiki
html	HTML table

json and jsonpretty keep the shape of the table: an object comes out as key / value pairs.

$ cv4pve-cli api get /version -o json
[{"key":"release","value":"8.4"},{"key":"repoid","value":"2606ac850d46da29"},{"key":"version","value":"8.4.21"}]

For the answer exactly as Proxmox VE sends it, add -v (--verbose) instead:

$ cv4pve-cli api get /version -v
{
  "data": {
    "version": "8.4.21",
    "repoid": "2606ac850d46da29",
    "release": "8.4"
  }
}

Tasks

Calls that start a long operation (start, shutdown, backup, migrate, clone, snapshot) do not wait for it: Proxmox VE starts a task and answers at once with its ID, the UPID. With --wait, cv4pve-cli waits for the task to end, checking every second, then prints its exit status:

cv4pve-cli api create /nodes/pve01/qemu/100/status/start --wait
cv4pve-cli api create /nodes/pve01/vzdump --vmid 100 --storage backup01 --wait --wait-timeout 3600

The exit code is 0 if the task succeeded and 5 if it failed. --wait-timeout sets a limit in seconds; when it expires the command exits with 5 and the task goes on. The exit code is 5 also when the status of the task cannot be read: a node down, or, with a user and password, a wait longer than the 2 hours a Proxmox VE login lasts: for long tasks use a context with an API token. To watch the log of a task while it runs, use task log --follow.