Getting started

cv4pve-cli runs outside the cluster (on your workstation, a management VM or a CI runner) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes.

Installation

Platform	How
Linux	`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` ARM: `cv4pve-cli-linux-arm64.zip`, `cv4pve-cli-linux-arm.zip`
Debian / Ubuntu	`sudo dpkg -i cv4pve-cli-VERSION-ARCH.deb` (amd64, arm64, armhf)
RHEL / Fedora	`sudo rpm -i cv4pve-cli-VERSION-ARCH.rpm` (x86_64, aarch64, armv7hl)
Arch Linux	`yay -S cv4pve-cli`
Windows (WinGet)	`winget install Corsinvest.cv4pve.cli`
Windows (manual)	`cv4pve-cli.exe-win-x64.zip`, also x86 and arm64
macOS (Homebrew)	`brew install corsinvest/tap/cv4pve-cli`
macOS (installer)	`cv4pve-cli-VERSION-arm64.pkg` (Apple silicon) or `-x86_64.pkg` (Intel)
macOS (manual)	`cv4pve-cli-osx-arm64.zip` or `cv4pve-cli-osx-x64.zip`

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

On its first run cv4pve-cli sets up tab completion for your shell: see Tab completion.

First commands

Create a user and an API token for cv4pve-cli in Proxmox VE, with the privileges you want it to have: see Permissions.
Save the cluster as a context: a name for the connection, stored on your machine, so you never type the host and the token again.
```
cv4pve-cli config add pve01 --host=pve01.example.com --api-token='cli@pve!cli=UUID'
```
cv4pve-cli saves the context, then tries to connect and prints the Proxmox VE version:
```
Context 'pve01' saved.
Connected to pve01.example.com, PVE version 8.4.21
```
The first context you add becomes the current one. If the certificate of the nodes is the self-signed one Proxmox VE installs, add --validate-certificate false (see Contexts).

Run a command. Every command uses the current context:

cv4pve-cli get nodes                    # an alias
cv4pve-cli api get /nodes               # the same call, written as the API path
cv4pve-cli top                          # nodes, VMs, containers, storages, pools and SDN zones

Quote the API token: ! is special in bash. In PowerShell, also quote API paths that contain placeholders such as '/nodes/{node}/qemu': braces start a script block there. In Git Bash on Windows, set MSYS_NO_PATHCONV=1 first: see Troubleshooting.

Where to go next

Contexts: several clusters, token or password, where the credentials are stored.
API calls: get, set, create, delete on any path, and how to discover what a path accepts.
Aliases: the short commands, --guest and your own aliases.
Scripting: output formats, exit codes, waiting for tasks.