proxcli

A CLI tool to interact with Proxmox VE nodes and clusters via the REST API.

Designed to be easy for humans (table output, ergonomic flags) and AI agents (structured JSON, strict exit codes, --dry-run). Provides a higher-level abstraction over the raw Proxmox API.

Installation

Requires Python 3.10+ and uv.

# From PyPI
uv tool install proxcli

# From Git
uv tool install git+https://github.com/xezpeleta/proxcli.git

# From local checkout
uv tool install .

Quickstart

# Bootstrap credentials + permissions on a node in one step.
# Requires SSH access to a Proxmox node as root@pam (key auth by default).
proxmox auth setup --host pve01.lan
#    → creates the recommended proxcli roles, an API token, and ACLs on the node
#    → writes the token to ~/.config/proxmox-cli/credentials.json (mode 0600)
# Preview the script without changing anything:
#    proxmox auth setup --host pve01.lan --dry-run
# Password auth (needs sshpass installed):
#    proxmox auth setup --host pve01.lan --ssh-password-stdin

# Check auth status
proxmox auth status

# List VMs
proxmox vm list

# Show a specific VM
proxmox vm show 100

Prefer to write the config file by hand? See Manual config file below.

# Enable shell completions
source <(proxmox completion bash)          # bash
source <(proxmox completion zsh)           # zsh
proxmox completion fish | source           # fish  (or save to ~/.config/fish/completions/proxmox.fish)

# Create a VM (CLI flags)
proxmox vm create --node pve01 --vmid 110 --memory 2048 --cores 2 --name webserver

# Create a VM from a YAML file (declarative, version-controlled)
proxmox vm create --file my-vm.yaml

# Export an existing VM config as a YAML template
proxmox --output yaml vm config 112 > my-vm.yaml

# Start / stop / reboot
proxmox vm start 110
proxmox vm stop 110
proxmox vm reboot 110

# Delete (with purge)
proxmox vm delete 110 --purge

Authentication

Credentials are stored in ~/.config/proxmox-cli/credentials.json with restrictive permissions (0600). A system-wide config at /etc/proxmox-cli/credentials.json is also supported (checked after the user-level path).

Recommended: auth setup

proxmox auth setup --host <node> SSHes into a Proxmox node as root@pam and, in one idempotent pass, creates the recommended proxcli-* roles, an API token, and the ACLs that bind them — then writes the resulting token secret to credentials.json for you.

# Key-based SSH auth (default):
proxmox auth setup --host pve01.lan

# Password auth (requires sshpass):
proxmox auth setup --host pve01.lan --ssh-password-stdin

# Preview the generated script without touching the node:
proxmox auth setup --host pve01.lan --dry-run

# JSON output for agents/automation:
proxmox auth setup --host pve01.lan --dry-run --json

Options: --ssh-user, --port, -i/--identity, --pve-user (default root@pam), --token-name (default proxcli), --privsep/--no-privsep (default on — privilege separation), --regenerate (rotate the token secret), --force (overwrite an existing credentials.json), --no-write (run on the node but don't save locally).

The legacy --via api path uses an existing Administrator token over the REST API to create roles + ACLs only (it cannot capture or write the token secret). Prefer --via ssh.

Manual config file

If you prefer to hand-edit credentials, create ~/.config/proxmox-cli/credentials.json (chmod 600):

{
  "url": "https://192.168.1.10:8006",
  "username": "root@pam",
  "auth_method": "api_token",
  "api_token_id": "my-token",
  "api_token_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "verify_tls": false
}

For password auth, use "auth_method": "password" with a "password" field instead of api_token_id / api_token_secret.

Override credentials per command

proxmox --url https://other-pve:8006 --username admin@pam --password pass123 vm list

Environment variable

export PROXMOX_PASSWORD=mysecret
proxmox vm list --username root@pam --url https://pve:8006

Self-signed certificates

proxmox --insecure vm list

Command Reference

Global flags

Auth

proxmox auth status            # Show current auth context
proxmox auth status --permissions  # + effective permissions from API
proxmox auth setup             # Bootstrap roles + token + ACLs (SSH as root@pam, writes credentials.json)
proxmox auth setup --dry-run   # Preview the generated script without changing anything
proxmox auth check             # Live permission test table (39 checks)

Self-update

proxmox update              # Check for updates and install the latest version
proxmox update --check      # Only check (no install)
proxmox update --pre        # Include pre-release versions

Completion

proxmox completion bash    # Emit bash completion script
proxmox completion zsh     # Emit zsh completion script
proxmox completion fish    # Emit fish completion script

Add to your shell's rc file:

# bash (~/.bashrc)
source <(proxmox completion bash)

# zsh (~/.zshrc)
source <(proxmox completion zsh)

# fish (~/.config/fish/completions/proxmox.fish)
proxmox completion fish > ~/.config/fish/completions/proxmox.fish

VM (QEMU)

proxmox vm list [--node <node>]
proxmox vm show <vmid> [--node <node>]
proxmox vm config <vmid> [--node <node>]     # clean config, ready for --file import
proxmox vm create --node <node> --memory <mb> [--vmid <id>] [--cores <n>] \
    [--name <name>] [--cdrom <iso>] [--net <config>] [--disk <size>] \
    [--scsihw <type>] [--bios seabios|ovmf] [--machine <type>] [--boot <order>] \
    [--file <spec.yaml>]     # declarative VM spec (CLI flags override file values)
proxmox vm start <vmid> [--node <node>]
proxmox vm stop <vmid> [--node <node>]
proxmox vm reboot <vmid> [--node <node>]
proxmox vm suspend <vmid> [--node <node>]
proxmox vm resume <vmid> [--node <node>]
proxmox vm delete <vmid> [--node <node>] [--force] [--purge]

# VM snapshots
proxmox vm snapshot list <vmid> [--node <node>]
proxmox vm snapshot create <vmid> <snapname> [--description <text>] [--vmstate 1]
proxmox vm snapshot show <vmid> <snapname> [--node <node>]
proxmox vm snapshot rollback <vmid> <snapname> [--start 1]
proxmox vm snapshot delete <vmid> <snapname> [--force 1]

# VM guest agent
proxmox vm agent interfaces <vmid> [--node <node>]

# VM firewall
proxmox vm firewall options <vmid> [--node <node>]
proxmox vm firewall enable <vmid> [--node <node>]
proxmox vm firewall disable <vmid> [--node <node>]
proxmox vm firewall policy <vmid> --in-policy ACCEPT --out-policy DROP [--node <node>]
proxmox vm firewall rules list <vmid> [--node <node>]
proxmox vm firewall rules add <vmid> --action ACCEPT --dport 22 --proto tcp [--source <cidr>] [--comment <text>]
proxmox vm firewall rules show <vmid> <pos>
proxmox vm firewall rules update <vmid> <pos> --action DROP
proxmox vm firewall rules delete <vmid> <pos>
proxmox vm firewall refs <vmid> [--type alias|ipset|group]

# VM disk management
proxmox vm disk import <vmid> --image /path/to/image.qcow2 [--disk scsi0] [--storage rbd_ssd]
proxmox vm disk import <vmid> --url https://.../image.qcow2 [--disk scsi0] [--storage rbd_ssd]
proxmox vm disk resize <vmid> --disk scsi0 --size +10G
proxmox vm disk detach <vmid> --disk scsi0
proxmox vm disk remove <vmid> --disk scsi0 [--force]

Declarative VM specs (--file)

Create VMs from YAML files using native Proxmox VM config keys. CLI flags override file values — ideal for infrastructure-as-code:

# webserver.yaml
name: webserver
node: sanmarko
memory: 4096
cores: 2
net0: "virtio,bridge=vmbr0,tag=99"
import_from: local:import/debian-12-genericcloud-amd64.qcow2
citype: nocloud
ciuser: debian
cipassword: ChangeMe123!
sshkeys: ~/.ssh/id_rsa.pub

# Create from file
proxmox vm create --file webserver.yaml

# Override specific values
proxmox vm create --file webserver.yaml --name staging --memory 8192

# Export existing VM as YAML template
proxmox --output yaml vm config 112 > template.yaml

See docs/cloud-init.md for cloud-init specifics.

Container (LXC)

proxmox container list [--node <node>]
proxmox container show <vmid> [--node <node>]
proxmox container create --node <node> --vmid <id> --ostemplate <tmpl> [--memory <mb>] [--cores <n>] [--storage <name>]
proxmox container start <vmid> [--node <node>]
proxmox container stop <vmid> [--node <node>]
proxmox container delete <vmid> [--node <node>] [--force] [--purge]

# Container firewall
proxmox container firewall options <vmid> [--node <node>]
proxmox container firewall enable <vmid> [--node <node>]
proxmox container firewall disable <vmid> [--node <node>]
proxmox container firewall policy <vmid> --in-policy ACCEPT --out-policy DROP
proxmox container firewall rules list <vmid> [--node <node>]
proxmox container firewall rules add <vmid> --action ACCEPT --dport 22 --proto tcp
proxmox container firewall rules show <vmid> <pos>
proxmox container firewall rules update <vmid> <pos> --action DROP
proxmox container firewall rules delete <vmid> <pos>
proxmox container firewall refs <vmid> [--type alias|ipset|group]

Node

proxmox node list
proxmox node show <node>
proxmox node status [<node>]

# Node firewall
proxmox node firewall options <node>
proxmox node firewall enable <node>
proxmox node firewall disable <node>
proxmox node firewall policy <node> --in-policy ACCEPT --out-policy DROP
proxmox node firewall rules list <node>
proxmox node firewall rules add <node> --action ACCEPT --dport 22 --proto tcp
proxmox node firewall rules show <node> <pos>
proxmox node firewall rules update <node> <pos> --action DROP
proxmox node firewall rules delete <node> <pos>
proxmox node firewall refs <node> [--type alias|ipset|group]

# Node system info
proxmox node subscription <node>    # subscription status
proxmox node dns <node>             # DNS configuration
proxmox node time <node>            # timezone and local time
proxmox node services <node>        # systemd service status
proxmox node pci <node>             # PCI device inventory
proxmox node netstat <node>         # network statistics
proxmox node config <node>          # node configuration

Storage

proxmox storage list [--node <node>]
proxmox storage show <storage>
proxmox storage content <storage> [--node <node>]
proxmox storage status <storage> [--node <node>]   # usage stats
proxmox storage upload --node <node> --storage <storage> --file <path> [--content-type iso|vztmpl|import]

Network

proxmox network list [--node <node>] [--type bridge|bond|eth|vlan|...]
proxmox network show <iface> [--node <node>]

List and inspect network interfaces (bridges, bonds, VLANs, physical NICs) on any node. Use --type to filter by interface type.

$ proxmox network list --node sanmarko --type vlan
vmbr0.10   cidr=192.168.10.14/24   gateway=192.168.10.1
vmbr0.11   cidr=192.168.11.47/24

Pool

proxmox pool list
proxmox pool show <poolid>
proxmox pool create <poolid> [--comment <text>]
proxmox pool update <poolid> [--comment <text>] [--allow-delete]
proxmox pool delete <poolid>

Cluster

proxmox cluster status
proxmox cluster log [--limit N]              # cluster-wide log
proxmox cluster options                      # migration, keyboard, mac_prefix, tags

# Ceph management
proxmox ceph status                          # cluster health: OSDs, PGs, usage, monitors
proxmox ceph osd [--node <node>]             # OSD list with disk model/size/health/wearout
proxmox ceph log [--node <node>] [--limit N] # recent Ceph log entries
proxmox ceph disks [--node <node>]           # physical disks: device, model, health, wearout, OSD

# Cluster firewall
proxmox cluster firewall options
proxmox cluster firewall enable
proxmox cluster firewall disable
proxmox cluster firewall policy --in-policy ACCEPT --out-policy DROP
proxmox cluster firewall rules                                      # list (shorthand)
proxmox cluster firewall rules list                                 # list (explicit)
proxmox cluster firewall rules add --action ACCEPT --dport 22 --source 10.0.0.0/8
proxmox cluster firewall rules show <pos>
proxmox cluster firewall rules update <pos> --action DROP
proxmox cluster firewall rules delete <pos>
proxmox cluster firewall aliases                                    # list (shorthand)
proxmox cluster firewall aliases add <name> --cidr 10.0.0.0/24 --comment "web tier"
proxmox cluster firewall aliases delete <name>
proxmox cluster firewall ipsets                                     # list (shorthand)
proxmox cluster firewall ipsets add <name> --comment "trusted hosts"
proxmox cluster firewall ipsets show <name>
proxmox cluster firewall ipsets delete <name>
proxmox cluster firewall ipsets add-cidr <name> --cidr 192.168.1.0/24
proxmox cluster firewall ipsets delete-cidr <name> --cidr 192.168.1.0/24
proxmox cluster firewall refs [--type alias|ipset|group]

Task

proxmox task list [--node <node>]
proxmox task show <upid>
proxmox task log <upid> [--follow]

proxmox task log --follow polls the log endpoint every second and streams new lines until the task completes (like tail -f). cluster log --follow and ceph log --follow <node> work the same way.

Backup (vzdump)

proxmox backup list [--node <node>] [--storage <storage>] [--vmid <id>]
proxmox backup show <volid> [--node <node>] [--vmid <id>]
proxmox backup create [--node <node>] --vmid <id> --storage <storage> \
    [--mode snapshot|suspend|stop] [--compress 0|1|zstd] \
    [--bwlimit <kbps>] [--ionice <0-8>] [--prune-backups <spec>]
proxmox backup delete <volid> [--node <node>]
proxmox backup tasks [--node <node>] [--limit <n>]
proxmox backup defaults [--node <node>] [--storage <storage>]

Use --all instead of --vmid to back up all guests on a node. Backup tasks can be monitored with proxmox task log <upid> --follow.

User

proxmox user list
proxmox user show <userid>
proxmox user create <userid> [--password <pw>] [--email <email>] \
    [--firstname <name>] [--lastname <name>] [--group <group>] [--disable]
proxmox user update <userid> [--password <pw>] [--email <email>] [--enable|--disable]
proxmox user delete <userid>

Role

proxmox role list
proxmox role show <roleid>
proxmox role create <roleid> [--privs <priv1,priv2,...>]
proxmox role update <roleid> [--privs <priv1,priv2,...>]
proxmox role delete <roleid>

ACL

proxmox acl list
proxmox acl show <path>
proxmox acl add <path> --roles <role> [--users <users>] [--groups <groups>] [--tokens <tokens>]
proxmox acl delete <path> [--roles <role>] [--users <users>] [--groups <groups>]

ACL write operations require the Permissions.Modify privilege (Administrator role).

Output Formats

JSON (default)

[
  {
    "vmid": 100,
    "name": "webserver",
    "status": "running",
    "cpu": 0.05,
    "mem": 2048
  }
]

Table

┌──────┬───────────┬─────────┬───────┬──────┐
│ vmid │ name      │ status  │ cpu   │ mem  │
├──────┼───────────┼─────────┼───────┼──────┤
│ 100  │ webserver │ running │ 0.05  │ 2048 │
└──────┴───────────┴─────────┴───────┴──────┘

YAML

- vmid: 100
  name: webserver
  status: running
  cpu: 0.05
  mem: 2048

AI Agent Usage

Every command emits valid JSON by default (stdout) and diagnostic messages on stderr. Exit codes follow Unix conventions.

# Dry-run to preview the API call
proxmox --dry-run vm create --node pve01 --vmid 110 --memory 1024

# Machine-parseable JSON output
proxmox --output json vm list | jq '.[] | {vmid, status}'

# Check exit code
proxmox vm show 999 || echo "VM not found"

Development

# Clone
git clone https://github.com/xezpeleta/proxcli.git
cd proxcli

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=proxmox --cov-report=term-missing

# Lint
uv run ruff check .

# Build
uv build

License

MIT

Firewall Rule Options

Firewall rules share the same flags across cluster, node, VM, and container. The --macro flag can be used as a shortcut for common services (e.g., --macro SSH sets up port 22/tcp).

Example:

# Allow SSH from a specific subnet
proxmox vm firewall rules add 100 --action ACCEPT --dport 22 --proto tcp --source 192.168.1.0/24 --comment "Admin SSH"

# Or use a macro
proxmox vm firewall rules add 100 --action ACCEPT --macro SSH --source 192.168.1.0/24