Skip to content

Install cv4pve-cli, a remote command line for Proxmox VE

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.

  1. Install cv4pve-cli

    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.zip
    unzip cv4pve-cli-linux-$arch.zip
    chmod +x cv4pve-cli

    All files are on the latest release page.

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

  2. Create an API token

    Create a user and an API token for cv4pve-cli in Proxmox VE, with the privileges you want it to have: see Permissions.

  3. Save the cluster as a context

    A context is 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).

  4. 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.

  • 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.