get, set, create and delete on any path of the Proxmox VE REST API, with parameters as --key value. ls and usage show what a path contains and what it accepts.
Up and running in 4 steps
- Install cv4pve-cli
- Create an API token
- Save the cluster as a context
- Run a command
The whole Proxmox VE API, from your terminal
Runs outside the nodes, API only: what kubectl is to Kubernetes. Saved contexts for every cluster you manage, short aliases for everyday operations and tab completion that reads node names and VM IDs from the live cluster.
By sysadmins, for sysadmins.
Built by Corsinvest, official Proxmox partner.
arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/;s/armv7l/arm/')wget https://github.com/Corsinvest/cv4pve-cli/releases/latest/download/cv4pve-cli-linux-$arch.zipunzip cv4pve-cli-linux-$arch.zipchmod +x cv4pve-clicurl -s https://api.github.com/repos/Corsinvest/cv4pve-cli/releases/latest | grep -o "https://[^\"]*-$(dpkg --print-architecture)\.deb" | xargs curl -LOsudo dpkg -i cv4pve-cli-*-$(dpkg --print-architecture).debcurl -s https://api.github.com/repos/Corsinvest/cv4pve-cli/releases/latest | grep -o "https://[^\"]*-$(rpm --eval %_target_cpu)\.rpm" | xargs curl -LOsudo rpm -i cv4pve-cli-*-$(rpm --eval %_target_cpu).rpmyay -S cv4pve-clibrew install corsinvest/tap/cv4pve-clicurl -s https://api.github.com/repos/Corsinvest/cv4pve-cli/releases/latest | grep -o "https://[^\"]*-$(uname -m)\.pkg" | xargs curl -LOsudo installer -target / -pkg cv4pve-cli-*-$(uname -m).pkgarch=$(uname -m | sed 's/x86_64/x64/')curl -LO https://github.com/Corsinvest/cv4pve-cli/releases/latest/download/cv4pve-cli-osx-$arch.zipunzip cv4pve-cli-osx-$arch.zipchmod +x cv4pve-cliwinget install Corsinvest.cv4pve.cli$arch = @{ AMD64 = 'x64'; x86 = 'x86'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]Invoke-WebRequest https://github.com/Corsinvest/cv4pve-cli/releases/latest/download/cv4pve-cli.exe-win-$arch.zip -OutFile cv4pve-cli.zipExpand-Archive cv4pve-cli.zip -DestinationPath . -ForceAll files are on the latest release page.
cv4pve-cli config add pve01 --host=pve01.example.com --api-token='cli@pve!cli=…'cv4pve-cli get nodesThe first line saves the cluster once; from then on every command runs against it:
| node | status | cpu | level | maxcpu | maxmem | mem | ssl_fingerprint | uptime |
|---|---|---|---|---|---|---|---|---|
| pve01 | online | 0.0551737049022492 | c | 40 | 270057619456 | 201251405824 | 5A:8A:DE:…:1C:05:7A | 7805388 |
| pve02 | online | 0.0232613845048306 | c | 40 | 134766219264 | 84975058944 | F3:12:C6:…:2A:71:10 | 7805413 |
Values as the API returns them: memory in bytes, uptime in seconds. Add
-o json for a script.| key | value |
|---|---|
| agent | 1 |
| cpus | 2 |
| maxmem | 4294967296 |
| mem | 2030592000 |
| name | mailstore |
| qmpstatus | running |
| running-qemu | 9.2.0 |
| status | running |
| uptime | 7803584 |
| vmid | 1012 |
Some of the rows.
--guest found the node and the VM ID from the name.| name | description |
|---|---|
| create guest snapshot | Create a new snapshot for a guest (VM or CT) |
| delete guest snapshot | Delete a specific guest snapshot |
| do rollback guest | Rollback guest state to a specific snapshot (VM or CT) |
| get guest snapshots | List snapshots for a guest (VM or CT) |
| set guest snapshot | Update guest snapshot description |
| show guest snapshot | Show configuration of a specific guest snapshot |
Some of the rows: each operation also exists for VMs only (
vm) and containers only (ct).The Proxmox VE web interface is made for clicking, one object at a time. The API behind it can do
everything the interface does, but calling it by hand means a login, a ticket, a CSRF token and a
curl line for each call. pvesh is simpler, but it
runs only on a node, as root, and knows only the cluster that node belongs to.
cv4pve-cli puts the whole API in a command you run from your own workstation. You save each cluster
once, switch between them by name, and type do start vm --guest web01 instead of looking up which
node the guest runs on. Every API call the web interface makes, you can make from a shell script, a
scheduled job or an AI assistant, against as many clusters as you manage.
Outside the nodes, API only
Section titled “Outside the nodes, API only”cv4pve-cli runs outside the cluster (on Windows, Linux or macOS) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes and no SSH is needed. It can do exactly what its account is allowed to do, so give it a dedicated API token with the privileges you want it to have: see Permissions.
| cv4pve-cli | pvesh | |
|---|---|---|
| Runs on | Your workstation, a management VM, a CI runner | A Proxmox VE node |
| Account | Any user or API token, with its own privileges | root on the node |
| Clusters | Any number, as saved contexts | The one the node belongs to |
| API calls | api get/set/create/delete/ls/usage |
get/set/create/delete/ls/usage |
| Shortcuts | 347 built-in aliases, plus your own | - |
The Coming from pvesh page maps each pvesh command to cv4pve-cli.
Where it fits
Section titled “Where it fits”The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. cv4pve-cli is the general-purpose one: any API call, by hand or in a script. The others answer one question each and run on their own:
| Tool | Use it for |
|---|---|
| cv4pve-cli | Any API call from a shell: read, change, automate |
| cv4pve-api-powershell | The same API as PowerShell cmdlets, with objects instead of text, the choice if your scripts are PowerShell |
| cv4pve-report | The full inventory of a cluster, in Excel, HTML or JSON |
| cv4pve-diag | What is wrong in a cluster: a list of problems, each with a severity |
| cv4pve-admin | A web platform for several clusters, when a command line is not what you want |
What it does for you
Section titled “What it does for you”Each cluster is a saved context: host, port, token or password. Switch with config use, as kubectl does with Kubernetes clusters.
do start vm, create guest snapshot, get cluster ha resources: short commands for common operations, plus your own.
--guest web01 finds the node, the type and the VM ID for you, so you never look up where a guest runs.
bash, zsh and PowerShell complete API paths, node names, VM IDs, parameters and their allowed values.
Output as text, JSON, HTML or Markdown; --wait for asynchronous tasks; task log --follow to watch one run.
Part of the cv4pve suite →
Made by Corsinvest,
official Proxmox partner
Run your first command
Install the binary, save your cluster as a context, type get nodes.
Made by Corsinvest,official Proxmox partner
