// Use when querying or managing a Proxmox VE cluster via the pvetui CLI — listing nodes, guests, and tasks; creating and migrating VMs and LXC containers; managing storage content, downloading templates and OCI images, and restoring backups. Requires pvetui to be installed and configured.
| name | pvetui-cli |
| description | Use when querying or managing a Proxmox VE cluster via the pvetui CLI — listing nodes, guests, and tasks; creating and migrating VMs and LXC containers; managing storage content, downloading templates and OCI images, and restoring backups. Requires pvetui to be installed and configured. |
| license | MIT |
| metadata | {"author":"github.com/devnullvoid/pvetui","version":"1.1"} |
pvetui is a terminal UI and CLI for Proxmox VE. When invoked with a subcommand it runs non-interactively, making it suitable for scripts and AI agent workflows.
# Via Go (recommended)
go install github.com/devnullvoid/pvetui/cmd/pvetui@latest
# Via skill (Claude Code / any skills.sh-compatible agent)
npx skills add devnullvoid/pvetui
pvetui installed and on $PATH~/.config/pvetui/config.yml with at least one profileguests exec / guests shell on LXC containers: ssh_user configured in the profileguests shell on QEMU VMs: ssh_user (and optionally vm_ssh_user) configured| Command | Purpose |
|---|---|
pvetui nodes list | List all cluster nodes |
pvetui nodes show <node> | Show details for one node |
pvetui nodes shell <node> | Open an interactive SSH shell on a node |
pvetui guests list | List all VMs and containers |
pvetui guests show <vmid> | Show details for one guest |
pvetui guests start <vmid> | Start a guest |
pvetui guests stop <vmid> | Force stop a guest (power off) |
pvetui guests shutdown <vmid> | Graceful ACPI shutdown |
pvetui guests restart <vmid> | Graceful restart |
pvetui guests delete <vmid> | Permanently delete a guest and its disks |
pvetui guests exec <vmid> <cmd> | Run a command inside a guest |
pvetui guests shell <vmid> | Open an interactive shell inside a guest |
pvetui guests create vm | Create a QEMU VM |
pvetui guests create lxc | Create an LXC container |
pvetui guests migrate <vmid> <node> | Migrate a guest to another node |
pvetui tasks list | List recent cluster tasks |
pvetui storage list | List storages across the cluster |
pvetui storage show <node> <storage> | Show details for a storage |
pvetui storage content list <node> <storage> | List content in a storage |
pvetui storage content delete <node> <storage> <volid> | Delete a content item |
pvetui storage download url <node> <storage> <url> | Download from a URL |
pvetui storage download template <node> <storage> <template> | Download an appliance template |
pvetui storage download oci <node> <storage> <reference> | Pull an OCI image |
pvetui storage restore <node> <storage> <volid> <vmid> | Restore a guest from backup |
These flags work with every subcommand:
| Flag | Short | Description |
|---|---|---|
--profile <name> | -p | Use a specific connection profile or aggregate group |
--output <format> | -o | Output format: json (default) or table |
--config <path> | -c | Path to config file (default: ~/.config/pvetui/config.yml) |
--no-cache | -n | Disable caching |
Default (JSON): structured output to stdout; errors as JSON to stderr; non-zero exit on failure.
Table (--output table): aligned human-readable output to stdout.
All commands default to JSON — prefer JSON when parsing output in scripts or agents.
Commands that trigger a Proxmox task (guests create, guests migrate, storage content delete, storage download *, storage restore) block until the task completes by default, then include status and exit_status in the output. Pass --no-wait to return the task UPID immediately without waiting.
{
"vmid": 105,
"node": "pve01",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
A non-"OK" exit_status causes a non-zero process exit.
# List all nodes (JSON)
pvetui nodes list
# List nodes in human-readable table
pvetui nodes list --output table
# Show a specific node
pvetui nodes show pve01
pvetui nodes show pve01 --output table
# Open an interactive SSH shell on a node
pvetui nodes shell pve01
JSON shape — nodes list:
[
{
"name": "pve01",
"ip": "10.0.0.10",
"online": true,
"cpu_usage": 0.12,
"memory_used": 7.238216400146484,
"memory_total": 31.174354553222656,
"uptime": 864000,
"version": "8.2.2",
"kernel_version": "6.8.4-2-pve",
"source_profile": "prod"
}
]
cpu_usage is a fraction (0.0–1.0). Memory values are in GiB. uptime is seconds. source_profile is populated in aggregate group mode.
# List all guests
pvetui guests list
# Filter by node, status, or type
pvetui guests list --node pve01
pvetui guests list --status running
pvetui guests list --type qemu
pvetui guests list --node pve01 --status running --type lxc
# Show a specific guest by VMID
pvetui guests show 100
JSON shape — guests list:
[
{
"id": 100,
"name": "web-server",
"node": "pve01",
"type": "qemu",
"status": "running",
"ip": "10.0.0.100",
"template": false,
"tags": "prod;web",
"source_profile": "prod"
}
]
type is "qemu" or "lxc". status is "running", "stopped", or "paused". ip may be empty if the guest agent is not running. template: true guests cannot be started/stopped.
pvetui guests start 100 # start a stopped guest
pvetui guests shutdown 100 # graceful ACPI shutdown (preferred)
pvetui guests stop 100 # force power-off (data loss risk)
pvetui guests restart 100 # graceful restart
JSON shape — lifecycle:
{
"vmid": 100,
"operation": "shutdown",
"upid": "UPID:pve01:00001234:...",
"node": "pve01"
}
The upid is a Proxmox task ID. Use pvetui tasks list to monitor task completion.
Permanently deletes a guest and all its associated disks. The guest must be stopped first unless --force is passed.
# Delete a stopped guest (waits for completion)
pvetui guests delete 108
# Also remove the VMID from backup and replication job configs
pvetui guests delete 108 --purge
# Force-delete a running guest (data loss risk)
pvetui guests delete 108 --force
# Return the task UPID immediately without waiting
pvetui guests delete 108 --no-wait
JSON shape — delete:
{
"vmid": 108,
"node": "pve01",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
# Create a VM (VMID auto-assigned if omitted)
pvetui guests create vm \
--node pve01 \
--name myvm \
--disk-storage local-zfs \
--disk-size 32
# With full options
pvetui guests create vm \
--node pve01 \
--name myvm \
--vmid 105 \
--memory 4096 \
--cores 4 \
--disk-storage local-zfs \
--disk-size 32 \
--iso local:iso/debian-12.iso \
--bridge vmbr0 \
--start
# Create an LXC container (package name resolved to latest template automatically)
pvetui guests create lxc \
--node pve01 \
--hostname myct \
--rootfs-storage local-zfs \
--template debian-12-standard
# LXC with full options
pvetui guests create lxc \
--node pve01 \
--hostname myct \
--rootfs-storage local-zfs \
--template debian-12-standard \
--memory 1024 \
--swap 512 \
--cores 2 \
--rootfs-size 16 \
--bridge vmbr0 \
--start
# Return the task UPID immediately without waiting
pvetui guests create vm --node pve01 --name myvm --disk-storage local-zfs --disk-size 32 --no-wait
Key flags — guests create vm:
| Flag | Required | Default | Notes |
|---|---|---|---|
--node | yes | — | Target node |
--name | yes | — | VM name |
--disk-storage | yes | — | Storage for the boot disk |
--disk-size | yes* | — | Disk size in GB; required unless --import-from |
--vmid | no | auto | Auto-assigned via GetNextID if omitted |
--memory | no | 2048 | MB |
--cores | no | 2 | vCPU cores |
--iso | no | — | ISO volid for CD-ROM |
--bridge | no | vmbr0 | Network bridge |
--start | no | false | Start after create |
--import-from | no | — | Import disk from volid instead of creating |
--no-wait | no | false | Return UPID immediately |
Key flags — guests create lxc:
| Flag | Required | Default | Notes |
|---|---|---|---|
--node | yes | — | Target node |
--hostname | yes | — | Container hostname |
--rootfs-storage | yes | — | Storage for root filesystem |
--template | yes | — | Full filename or package name (e.g. debian-12-standard) |
--vmid | no | auto | |
--memory | no | 512 | MB |
--swap | no | 512 | MB (0 = no swap) |
--cores | no | 1 | |
--rootfs-size | no | 8 | GB |
--bridge | no | vmbr0 | |
--unprivileged | no | true | |
--nesting | no | true | Enable Docker/nested containers |
--start | no | false | Start after create |
--no-wait | no | false | Return UPID immediately |
JSON shape — guests create:
{
"vmid": 105,
"name": "myvm",
"node": "pve01",
"type": "qemu",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
# Migrate a guest (mode selected automatically)
pvetui guests migrate 100 pve02
# Force online/offline mode for QEMU (not valid for LXC)
pvetui guests migrate 100 pve02 --online
pvetui guests migrate 100 pve02 --offline
# Return task UPID immediately
pvetui guests migrate 100 pve02 --no-wait
Migration mode is selected automatically:
JSON shape — guests migrate:
{
"vmid": 100,
"name": "web-server",
"source_node": "pve01",
"target_node": "pve02",
"mode": "online",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
Execute a command inside a running guest without SSH access to the guest itself.
# QEMU VM — uses the QEMU guest agent (API only, no node SSH needed)
pvetui guests exec 100 "uptime"
pvetui guests exec 100 "df -h"
pvetui guests exec 100 "systemctl status nginx"
# LXC container — uses pct exec over SSH to the node (ssh_user must be configured)
pvetui guests exec 200 "uptime"
pvetui guests exec 200 "cat /etc/os-release"
# Custom timeout (default 30s)
pvetui guests exec 100 "apt-get update" --timeout 120s
# Table output (useful for human review)
pvetui guests exec 100 "df -h" --output table
Requirements:
ssh_user must be configured in the profile; the agent user needs permission to run pct exec (or be root).OS detection (QEMU only):
ostype starting with win): command is wrapped in powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command <cmd>/bin/sh -c <cmd>/bin/sh -c <cmd>JSON shape — exec:
{
"vmid": 100,
"command": "uptime",
"stdout": " 10:23:01 up 10 days, 2:34, 0 users, load average: 0.10, 0.08, 0.05\n",
"stderr": "",
"exit_code": 0,
"duration_ms": 412
}
A non-zero exit_code means the command ran but failed. A transport/SSH error causes a non-zero process exit with a JSON error on stderr instead.
Opens an interactive terminal session. These commands take over stdin/stdout and are not suitable for scripting — use exec for non-interactive commands in agents.
pvetui nodes shell pve01 # SSH to a Proxmox node
pvetui guests shell 100 # shell inside a guest (LXC: pct enter; QEMU: SSH to VM IP)
# Last 20 tasks (default)
pvetui tasks list
# Last 50 tasks
pvetui tasks list --recent 50
# Human-readable table
pvetui tasks list --output table
JSON shape — tasks list:
[
{
"upid": "UPID:pve01:00001234:...",
"node": "pve01",
"type": "qmstart",
"status": "OK",
"user": "root@pam",
"starttime": 1710000000,
"endtime": 1710000005,
"source_profile": "prod"
}
]
starttime and endtime are Unix timestamps. status is "OK" on success or an error string on failure. A task with no endtime is still running.
# List all storages (one row per node/storage pair)
pvetui storage list
pvetui storage list --node pve01
pvetui storage list --output table
# Show a specific storage
pvetui storage show pve01 local-zfs
JSON shape — storage list:
[
{
"name": "local-zfs",
"node": "pve01",
"type": "zfspool",
"content": "images,rootdir",
"used": 53687091200,
"total": 214748364800,
"active": true
}
]
# List all content in a storage
pvetui storage content list pve01 local
# Filter by content type: iso, vztmpl, backup, snippets, images
pvetui storage content list pve01 local --type iso
pvetui storage content list pve01 local --type backup
# Delete a content item (explicit volid required)
pvetui storage content delete pve01 local local:iso/old-debian.iso
pvetui storage content delete pve01 local local:iso/old-debian.iso --no-wait
JSON shape — storage content list:
[
{
"volid": "local:iso/debian-12.iso",
"name": "debian-12.iso",
"type": "iso",
"size": 658505728,
"ctime": 1700000000,
"vmid": 0
}
]
# Download an ISO from a URL (content type inferred from extension)
pvetui storage download url pve01 local https://example.com/debian-12.iso
# Override filename or content type
pvetui storage download url pve01 local https://example.com/image.bin \
--filename my-image.iso \
--content-type iso
# Download an appliance template by package name (latest version resolved automatically)
pvetui storage download template pve01 local debian-12-standard
# Or use a full filename to pin a specific version
pvetui storage download template pve01 local debian-12-standard_12.7-1_amd64.tar.zst
# Narrow resolution by section when multiple templates match
pvetui storage download template pve01 local myapp --section turnkeylinux
# Pull an OCI image
pvetui storage download oci pve01 local registry.example.com/myimage:latest
# Any download can return UPID immediately
pvetui storage download url pve01 local https://example.com/debian-12.iso --no-wait
Content type inference from URL extension:
| Extension | Inferred type |
|---|---|
.iso | iso |
.tar.* (.tar.zst, .tar.gz, etc.) | vztmpl |
.img | import |
| other | must supply --content-type |
JSON shape — storage download:
{
"node": "pve01",
"storage": "local",
"url": "https://example.com/debian-12.iso",
"filename": "debian-12.iso",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
Restore a guest from a vzdump backup. Destructive — overwrites the target VMID's config and disks.
# Dry-run: print what would be restored, exit without making changes
pvetui storage restore pve01 local local:backup/vzdump-qemu-100-2024.tar.zst 100
# Actually restore (requires --confirm)
pvetui storage restore pve01 local local:backup/vzdump-qemu-100-2024.tar.zst 100 --confirm
# Override inferred guest type (normally inferred from volid prefix)
pvetui storage restore pve01 local local:backup/unknown.tar.zst 101 --confirm --type lxc
# Return UPID immediately
pvetui storage restore pve01 local local:backup/vzdump-qemu-100.tar.zst 100 --confirm --no-wait
Guest type is inferred from the volid prefix: vzdump-qemu-* → qemu, vzdump-lxc-* → lxc. Use --type to override when inference fails.
JSON shape — storage restore:
{
"node": "pve01",
"storage": "local",
"volid": "local:backup/vzdump-qemu-100-2024.tar.zst",
"vmid": 100,
"type": "qemu",
"upid": "UPID:pve01:...",
"status": "complete",
"exit_status": "OK"
}
All subcommands respect --profile. The profile can be a single connection profile or an aggregate group name.
# Use the "prod" profile
pvetui --profile prod guests list
# Use the "all-clusters" aggregate group (fans out across all member nodes)
pvetui --profile all-clusters guests list --status running
# List available profiles
pvetui --list-profiles
In aggregate group mode, source_profile in JSON output identifies which cluster each resource belongs to. All reads fan out concurrently; write operations (lifecycle, exec, create, migrate) are routed to the correct cluster automatically.
Errors are written as JSON to stderr and the process exits non-zero:
{"error": "guest 999 not found"}
Check exit code to detect failure; parse stderr JSON for the message. Stdout is always valid JSON (or empty) on success.
# Example: check exit code in shell
if ! pvetui guests show 100 > /dev/null 2>&1; then
echo "Guest not found"
fi
# Example: capture error message
err=$(pvetui guests show 999 2>&1 >/dev/null)
# Find all running VMs on a specific node
pvetui guests list --node pve01 --status running --type qemu
# Get IP addresses of all running guests
pvetui guests list --status running | jq '.[].ip'
# Check if a specific guest is running
pvetui guests show 100 | jq -r '.status'
# Create an LXC and wait for it to finish, then get its VMID
result=$(pvetui guests create lxc --node pve01 --hostname myct --rootfs-storage local-zfs --template debian-12-standard)
vmid=$(echo "$result" | jq -r '.vmid')
# Migrate a guest and verify it landed on the target
pvetui guests migrate 100 pve02
pvetui guests show 100 | jq -r '.node' # should now be "pve02"
# Download a template and create a container from it in sequence
pvetui storage download template pve01 local debian-12-standard
pvetui guests create lxc --node pve01 --hostname newct --rootfs-storage local-zfs --template debian-12-standard --start
# List all ISO files available on a node
pvetui storage content list pve01 local --type iso | jq '.[].volid'
# Find all backup files for a specific VM
pvetui storage content list pve01 local --type backup | jq '[.[] | select(.volid | contains("vzdump-qemu-100-"))]'
# Run a health check across multiple guests
for vmid in 100 101 102; do
echo "=== $vmid ==="
pvetui guests exec $vmid "systemctl is-active nginx"
done
# Find guests with a specific tag
pvetui guests list | jq '[.[] | select(.tags | contains("prod"))]'
# Get total memory across all nodes
pvetui nodes list | jq '[.[].memory_total] | add'
# Check storage usage across the cluster
pvetui storage list | jq '[.[] | {name, node, used_pct: (.used / .total * 100 | round)}]'
| Problem | Likely Cause | Fix |
|---|---|---|
{"error": "bootstrap failed: ..."} | Bad config or credentials | Check ~/.config/pvetui/config.yml; verify API token |
{"error": "guest agent is not available"} | Agent not running in VM | Install/start qemu-guest-agent inside the VM |
{"error": "exec failed on LXC ..."} | SSH to node failed | Verify ssh_user is set and SSH key auth works to the node |
{"error": "multiple profiles configured; use --profile"} | No default profile set | Pass --profile <name> or set default_profile in config |
{"error": "failed to delete guest ... locked"} | Guest is running or locked | Stop the guest first, or pass --force |
{"error": "cannot infer guest type from volid ..."} | Backup filename not standard | Pass --type qemu or --type lxc explicitly |
{"error": "cannot infer content type from URL ..."} | URL extension not recognised | Pass --content-type iso (or vztmpl/import) |
ip field empty in guest list | Agent not running or no IP yet | Check guest agent; ip populates only for running QEMU VMs with agent |
| LXC exec fails with permission denied | Non-root user needs sudo | Add NOPASSWD: /usr/sbin/pct exec * to sudoers on node |
| Template name not resolved | Package not in aplinfo catalog | Use the full filename from pvetui storage content list |