@proxman-io/cli

Command-line interface for ProxManLib. Drives any Proxmox VE cluster from the shell or from an agent host. Structured JSON output mode (--json) makes it a clean integration target for nanopilot / Spark / any tool-calling agent.

Install

npm install -g @proxman-io/cli
proxman --help

Or use it one-off without a global install:

npx @proxman-io/cli --help

Configuration

Every command needs a Proxmox host and API token. Supply via environment (preferred) or flags.

| Env var | Flag | Purpose | | --------------------- | ---------------------------------------- | ------------------------------------- | | PROXMOX_HOST | --host <host> | Proxmox hostname or IP | | PROXMOX_TOKEN | --token <token> | API token (USER@REALM!TOKENID=UUID) | | PROXMOX_FINGERPRINT | --fingerprint <fp> | SHA-256 cert fingerprint | | PROXMOX_CA_CERT | --ca-cert <path> | Path to CA cert PEM | | PROXMOX_INSECURE=1 | --tls-mode insecure | Skip TLS verification (lab only) | | — | --tls-mode <ca\|fingerprint\|insecure> | Explicit TLS policy | | — | --timeout <ms> | Request timeout | | — | --json | Structured JSON output (for agents) |

If no TLS mode is specified, ca is used — relying on the system trust store unless PROXMOX_CA_CERT is set.

Commands

proxman nodes

proxman nodes list                  # list cluster nodes
proxman nodes status <node>         # runtime status for a node

proxman qemu

proxman qemu list <node>
proxman qemu config <node> <vmid>
proxman qemu start <node> <vmid> [--wait] [--wait-timeout <ms>]
proxman qemu stop <node> <vmid> [--wait]
proxman qemu shutdown <node> <vmid> [--wait]

--wait polls the returned task UPID to completion and sets a non-zero exit code on failure/timeout.

proxman lxc

proxman lxc list <node>
proxman lxc config <node> <vmid>
proxman lxc start <node> <vmid> [--wait]
proxman lxc stop <node> <vmid> [--wait]
proxman lxc shutdown <node> <vmid> [--wait]

proxman storage

proxman storage list <node>

proxman task

proxman task list <node> [--limit <n>] [--source active|all|archive]
proxman task status <node> <upid>
proxman task wait <node> <upid> [--timeout <ms>] [--interval <ms>]

proxman tool call

Unified tool-adapter entry — policy-enforced, structured output. Ideal for agent integration.

proxman tool call <operation> \
  [--node <node>] [--vmid <vmid>] \
  [--params '<json>'] \
  [--confirm-risk high|destructive] \
  [--allow-destructive] \
  [--json]

<operation> is any OperationKind (listNodes, startQemu, deleteLxc, etc.). High-risk and destructive operations are rejected unless confirmation flags match.

Exit codes

| Code | Meaning | | ---- | ----------------------------------------------------------------- | | 0 | Success | | 1 | Runtime/configuration error (missing host, auth failure, network) | | 2 | tool call blocked by policy or returned ok: false |

JSON output

With --json, every command writes a single JSON document to stdout (errors to stderr). Shape depends on the command — see docs/cli.md for the contract.

proxman --json nodes list
proxman --json qemu start pve1 101 --wait
proxman --json tool call deleteLxc --node pve1 --vmid 200 \
  --confirm-risk destructive --allow-destructive

Agent integration

nanopilot / Spark should call proxman tool call <operation> --json. The result is a single ToolResult JSON object with fields ok, operation, risk, target, data, taskRef?, error?, summary. Non-zero exit code on failure — check ok or the exit code.

See the root README for library-level usage.