proxctl

A command-line interface for Proxmox VE -- manage VMs, containers, nodes, storage, and more from your terminal. Includes declarative infrastructure management with apply and export.

Install

# From crates.io
cargo install proxctl

# From PyPI (pre-built binaries, no Rust toolchain needed)
pip install proxctl

# From GitHub Releases (Linux, macOS, Windows)
curl -fsSL https://github.com/rvben/proxctl/releases/latest/download/proxctl-$(uname -m)-unknown-linux-gnu.tar.gz | tar xz

Quick Start

# Interactive setup (creates API token automatically)
proxctl config init

# Check connectivity
proxctl health

# List VMs
proxctl vm list

# Start a VM
proxctl vm start 100

# Show VM configuration
proxctl vm config 100

# List snapshots
proxctl vm snapshot list 100

# Raw API access
proxctl api get /nodes

Declarative Infrastructure (IaC)

Manage Proxmox resources declaratively with YAML manifests, similar to kubectl apply.

Export existing resources

# Export a single VM
proxctl export vm 101 > haos.yaml

# Export all containers
proxctl export container --all > containers.yaml

# Export cluster firewall rules
proxctl export firewall cluster > firewall.yaml

Apply desired state

# infra/web.yaml
kind: vm
name: web-01
vmid: 100
config:
  memory: 4096
  cores: 2
  onboot: true
---
kind: firewall-rule
scope: cluster
config:
  action: ACCEPT
  type: in
  proto: tcp
  dport: "443"
  comment: "Allow HTTPS"

# Preview changes
proxctl apply -f infra/ --dry-run

# Apply changes
proxctl apply -f infra/

# Round-trip: export, then verify nothing drifted
proxctl export vm --all > current.yaml
proxctl apply -f current.yaml --dry-run  # should show "noop" for all

Key behaviors

• Idempotent -- running apply twice produces "up to date" on the second run
• Patch semantics -- only specified config keys are changed, others left untouched
• Name or VMID -- resources can be identified by name (auto-resolves VMID) or pinned by ID
• Multi-document -- multiple resources in one file with --- separators, or a directory of files
• Optional power state -- add state: running or state: stopped to manage power, or omit to leave it alone
• Safe -- shows a diff before applying, destructive changes prompt for confirmation

Features

• 145+ commands covering VMs, containers, nodes, storage, backups, cluster, firewall, access control, pools, and Ceph
• Declarative IaC -- apply and export for infrastructure-as-code workflows
• Auto-detection -- resolves which node a VM lives on automatically
• Agent-friendly -- --json output, schema command for introspection, structured exit codes
• Async task handling -- waits for operations to complete with progress spinner
• Safe -- destructive operations require --yes confirmation
• Raw API escape hatch -- proxctl api get/post/put/delete for any endpoint
• Hidden aliases -- qm for vm, ct for container
• Idempotent -- starting an already-running VM succeeds without error

Configuration

Config file

~/.config/proxctl/config.toml

[default]
host = "https://192.168.1.1:8006"
token = "root@pam!proxctl=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
insecure = true

[production]
host = "https://pve.example.com:8006"
token = "admin@pam!proxctl=yyyyyyyy-..."

Environment variables

Precedence

CLI flags > environment variables > config file

Usage Examples

Human output (TTY)

$ proxctl vm list
  VMID  NAME                  STATUS      NODE        CPUS      MEMORY
   100  k8s-control-1         running     pve1           4    8.00 GiB
   101  k8s-worker-1          running     pve1           8   16.00 GiB
   200  dev-sandbox            stopped     pve2           2    4.00 GiB

JSON output (piped or --json)

$ proxctl vm list --json | jq '.[].name'
"k8s-control-1"
"k8s-worker-1"
"dev-sandbox"

JSON output is automatic when stdout is not a TTY, so piping to jq, grep, or scripts works without flags.

Agent Integration

The schema command outputs a JSON description of all 145+ commands with their arguments, types, defaults, and behavioral metadata:

proxctl schema | jq '.commands | length'
145

This enables AI agents and automation tools to discover available operations, required parameters, and which commands are mutating or destructive -- without parsing help text.

Comparison

License

MIT

Releasing

Vership owns versioning, changelog generation, release commits, and tags. See the release runbook for the verified workflow and recovery policy.