# install (x64; arm64 on the Releases page) $ wget https://github.com/Corsinvest/\ cv4pve-cli/releases/latest/download/\ cv4pve-cli-linux-x64.zip $ unzip cv4pve-cli-linux-x64.zip $ chmod +x cv4pve-cli # run against any node $ ./cv4pve-cli api get /nodes
# install $ brew install corsinvest/tap/cv4pve-cli # run against any node $ cv4pve-cli api get /nodes
# install PS> winget install Corsinvest.cv4pve.cli # run against any node PS> cv4pve-cli api get /nodes
The whole Proxmox VE API, from your terminal
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 |
-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 |
--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 |
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”Every API call
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.
02Several clusters
Each cluster is a saved context: host, port, token or password. Switch with config use, as kubectl does with Kubernetes clusters.
03Aliases for everyday work
do start vm, create guest snapshot, get cluster ha resources: short commands for common operations, plus your own.
04Guests by name
--guest web01 finds the node, the type and the VM ID for you, so you never look up where a guest runs.
05Tab completion from the cluster
bash, zsh and PowerShell complete API paths, node names, VM IDs, parameters and their allowed values.
06Made for scripts
Output as text, JSON, HTML or Markdown; --wait for asynchronous tasks; task log --follow to watch one run.
Run your first command
Install the binary, save your cluster as a context, type get nodes.
Made by Corsinvest,official Proxmox partner