Coming from pvesh

If you already use pvesh on your nodes, you already know cv4pve-cli: both are a shell interface to the same Proxmox VE API, with the same paths and the same parameters. What changes is where it runs.

	pvesh	cv4pve-cli
Runs on	A node, in a root shell	Any machine that reaches port 8006 of a node
How it calls the API	Directly, without the HTTPS server	Over HTTPS, like the web interface
Account	root	The user or API token of the context, with its privileges
Clusters	The one the node belongs to	Any number, switched with config use

So a command that works in pvesh works in cv4pve-cli if the account of the context has the privileges it needs: root has them all, a dedicated token only those you gave it.

Commands

The same call three ways: with pvesh on a node, with cv4pve-cli api, and (highlighted, marked # alias) with a cv4pve-cli alias, where one exists.

Read

pvesh get /nodes
cv4pve-cli api get /nodes
cv4pve-cli get nodes   # alias

Change a configuration

pvesh set /nodes/pve01/qemu/100/config --memory 4096
cv4pve-cli api set /nodes/pve01/qemu/100/config --memory 4096
cv4pve-cli set vm config pve01 100 --memory 4096   # alias

Create

pvesh create /nodes/pve01/qemu/100/snapshot --snapname before-update
cv4pve-cli api create /nodes/pve01/qemu/100/snapshot --snapname before-update
cv4pve-cli create vm snapshot pve01 100 before-update "Before the update"   # alias

Delete

pvesh delete /nodes/pve01/qemu/100/snapshot/before-update
cv4pve-cli api delete /nodes/pve01/qemu/100/snapshot/before-update
cv4pve-cli delete vm snapshot pve01 100 before-update --yes   # alias

List what is under a path

pvesh ls /nodes/pve01
cv4pve-cli api ls /nodes/pve01

Show what a path accepts

pvesh usage /nodes/{node}/qemu --command create --verbose
cv4pve-cli api usage /nodes/{node}/qemu create --verbose

pvesh usage /nodes/{node}/qemu --returns
cv4pve-cli api usage /nodes/{node}/qemu --returns

An alias is a short name for an API call: its arguments fill the path in order, and further parameters follow as --key value. With --guest you give the guest name or ID instead of node and VM ID (cv4pve-cli set vm config --guest web01 --memory 4096), and cv4pve-cli finds where the guest runs. The alias snapshot command also takes the description as an argument. alias list --search finds the alias for a call; the alias reference lists them all.

Options

pvesh	cv4pve-cli
--output-format json	--output json (-o json)
--output-format json-pretty	-o jsonpretty
--output-format text	-o text, the default
--output-format yaml	Not available; -o html and -o markdown instead
--human-readable <0|1>	--human-readable <false|true|0|1>, the same default: sizes, percentages, durations and dates as text
--noborder, --quiet	Not available
--noproxy	Not needed: the node that receives the call forwards it to the node in the path, as for the web interface

ls prints the same kind of listing as pvesh: D for a path with children, c when it accepts create.

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

What cv4pve-cli adds

• Tab completion that reads the cluster: node names, VM IDs, parameter names and their allowed values: see Tab completion.
• Aliases and --guest: short commands, and guests by name instead of node and VM ID.
• --wait on any call that starts a task, and the task commands to follow one.
• Several clusters from the same shell, each with its own account.