@proxman-io/cli

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