# Proxmox CLI command reference

Full command coverage for `qm`, `pct`, `pvesm`, `pvecm`, `pveam`, backup/
restore, networking, firewall, and troubleshooting. Adapted from
`bastos/skills@proxmox-admin` (upstream source: see `SKILL.md`
provenance note) with all example VMIDs, storage pool names, bridge
names, and networks replaced by placeholders — **none of the values
below are this fleet's real values.** Resolve real values from
`docs/server-*.md` or from live discovery (`qm list`, `pvesm status`,
etc.) before running anything.

Read `SKILL.md` first — it has the safety workflow and the destructive-
command tier list this reference assumes you already know. Everything
in a "never run without confirmation" tier there is repeated here only
as reference syntax, not as something to execute unattended.

## Tool overview

| Tool | Purpose |
|------|---------|
| `qm` | Manage KVM virtual machines |
| `pct` | Manage LXC containers |
| `pvesm` | Manage storage |
| `pvecm` | Manage cluster |
| `pveam` | Manage appliance/template downloads |
| `pvesh` | Access the Proxmox API from the shell |
| `pveperf` | Benchmark host performance |

## VM management with `qm`

### Creating a VM (destructive tier: creates persistent state — confirm first)

```bash
qm create <vmid> --name <vm-name> --memory 2048 --cores 2 --sockets 1 \
  --net0 virtio,bridge=<bridge> --ostype l26

# SCSI disk on a given storage pool
qm create <vmid> --name <vm-name> --memory 4096 --cores 4 \
  --scsi0 <storage>:32 --scsihw virtio-scsi-pci \
  --net0 virtio,bridge=<bridge> --ostype l26

# Attach an ISO for installation
qm set <vmid> --cdrom <storage>:iso/<image>.iso --boot order=ide2
```

### VM lifecycle

| Command | Purpose | Tier |
|---------|---------|------|
| `qm start <vmid>` | Start a VM | generally fine once target confirmed |
| `qm shutdown <vmid>` | Graceful ACPI shutdown | generally fine |
| `qm stop <vmid>` | Force stop (like pulling power) | confirm first — no ACPI grace |
| `qm reboot <vmid>` | Reboot (ACPI-graceful) | can hang if guest unresponsive — see SKILL.md |
| `qm reset <vmid>` | Hard reset | confirm clean unmount first — see SKILL.md |
| `qm suspend <vmid>` | Suspend to RAM | confirm first |
| `qm resume <vmid>` | Resume from suspend | generally fine |
| `qm destroy <vmid>` | Delete VM and its disks | **never without human confirmation** |
| `qm destroy <vmid> --purge` | Delete VM, disks, and all related jobs | **never without human confirmation** |

### VM configuration

```bash
qm config <vmid>                     # show current config — always run before qm set

qm set <vmid> --memory 8192
qm set <vmid> --cores 4
qm set <vmid> --balloon 2048          # dynamic memory (min)
qm set <vmid> --cpu cputype=host      # pass through host CPU features
qm set <vmid> --machine q35           # Q35 chipset (needed for PCIe passthrough)

# Add/resize disks — check pvesm status for free space first
qm set <vmid> --scsi1 <storage>:50    # add a 50GB disk
qm disk resize <vmid> scsi0 +20G      # grow an existing disk

# Networking — <bridge> and any VLAN tag are fleet-specific, resolve first
qm set <vmid> --net0 virtio,bridge=<bridge>,tag=<vlan>
qm set <vmid> --net1 virtio,bridge=<bridge2>

# Cloud-init
qm set <vmid> --ide2 <storage>:cloudinit
qm set <vmid> --ciuser <user> --cipassword '<generated-secret>'
qm set <vmid> --ipconfig0 ip=<ip>/<cidr>,gw=<gateway>
qm set <vmid> --sshkeys ~/.ssh/authorized_keys
qm set <vmid> --boot order=scsi0

# EFI / UEFI boot
qm set <vmid> --bios ovmf --efidisk0 <storage>:1,efitype=4m,pre-enrolled-keys=1

# Serial console (headless)
qm set <vmid> --serial0 socket --vga serial0

# PCI passthrough
qm set <vmid> --hostpci0 <pci-address>,pcie=1
```

### Snapshots and cloning

See SKILL.md's "Snapshot vs. backup" section before relying on any of
these as your only safety net.

```bash
qm snapshot <vmid> <snapshot-name> --description "<why>"
qm listsnapshot <vmid>
qm rollback <vmid> <snapshot-name>
qm delsnapshot <vmid> <snapshot-name>

qm clone <vmid> <new-vmid> --name <new-name> --full   # full copy
qm clone <vmid> <new-vmid> --name <new-name>            # linked clone (shares base disk)
```

### Templates

```bash
qm template <vmid>    # convert VM to template — IRREVERSIBLE, confirm first

qm clone <template-vmid> <new-vmid> --name <new-name>          # linked clone from template
qm clone <template-vmid> <new-vmid> --name <new-name> --full   # full clone from template
```

### Migration (confirm first — affects a second node)

```bash
qm migrate <vmid> <target-node> --online   # online (live) migration
qm migrate <vmid> <target-node>            # offline migration
```

### Monitoring

```bash
qm status <vmid>
qm list

qm agent <vmid> ping
qm agent <vmid> get-osinfo

qm monitor <vmid>     # QEMU monitor console
```

## Container management with `pct`

### Creating a container (destructive tier — confirm first)

```bash
# Download a template first
pveam update
pveam available --section system
pveam download <storage> <template-filename>

pct create <ctid> <storage>:vztmpl/<template-filename> \
  --hostname <ct-name> --memory 1024 --cores 2 \
  --rootfs <storage>:8 \
  --net0 name=eth0,bridge=<bridge>,ip=dhcp \
  --password '<generated-secret>' --unprivileged 1

# Static IP variant
pct create <ctid> <storage>:vztmpl/<template-filename> \
  --hostname <ct-name> --memory 2048 --cores 2 \
  --rootfs <storage>:16 \
  --net0 name=eth0,bridge=<bridge>,ip=<ip>/<cidr>,gw=<gateway> \
  --nameserver <dns-ip> --unprivileged 1
```

### Container lifecycle

| Command | Purpose | Tier |
|---------|---------|------|
| `pct start <ctid>` | Start container | generally fine once target confirmed |
| `pct shutdown <ctid>` | Graceful shutdown | generally fine |
| `pct stop <ctid>` | Force stop | confirm first |
| `pct reboot <ctid>` | Reboot container | same ACPI-hang caveat as `qm reboot` |
| `pct destroy <ctid>` | Delete container and its volumes | **never without human confirmation** |
| `pct enter <ctid>` | Open a shell inside the container | generally fine |
| `pct exec <ctid> -- <cmd>` | Run a command inside the container | depends what `<cmd>` does |
| `pct console <ctid>` | Attach to container console | generally fine |

### Container configuration

```bash
pct config <ctid>                     # always run before pct set

pct set <ctid> --memory 4096
pct set <ctid> --cores 4
pct set <ctid> --swap 1024

pct set <ctid> --mp0 /mnt/data,mp=/data              # bind mount from host
pct set <ctid> --mp1 <storage>:50,mp=/var/lib/data   # additional storage volume

pct set <ctid> --net0 name=eth0,bridge=<bridge>,ip=<ip>/<cidr>,gw=<gateway>
pct set <ctid> --net1 name=eth1,bridge=<bridge2>,ip=dhcp

pct set <ctid> --features nesting=1
pct set <ctid> --features nesting=1,fuse=1,mount=nfs

pct set <ctid> --nameserver "<dns-ip-1> <dns-ip-2>" --searchdomain <domain>

pct set <ctid> --onboot 1 --startup order=1,up=30
```

### Container snapshots and cloning

```bash
pct snapshot <ctid> <snapshot-name>
pct rollback <ctid> <snapshot-name>
pct clone <ctid> <new-ctid> --hostname <new-name> --full
```

## Storage management

```bash
pvesm status                  # list pools + free space — check before any restore/resize

pvesm list <storage>          # content of a specific storage pool

# Adding storage is a cluster-wide config mutation — confirm first
pvesm add dir <name> --path <path> --content backup
pvesm add nfs <name> --server <nfs-server-ip> --export <export-path> --content images,vztmpl
pvesm add lvm <name> --vgname <vg-name> --content rootdir,images
pvesm add zfspool <name> --pool <zfs-pool>/<dataset> --content rootdir,images

pvesm remove <name>           # never without human confirmation

wget -P /var/lib/vz/template/iso/ <iso-url>
```

## Networking

```bash
cat /etc/network/interfaces     # current bridge/interface config — read first

# Bridge stanza shape (values are placeholders, not this fleet's real config)
# auto <bridge>
# iface <bridge> inet static
#     address <host-ip>/<cidr>
#     bridge-ports <physical-nic>
#     bridge-stp off
#     bridge-fd 0

ifreload -a     # apply network changes — can drop connectivity if misconfigured, confirm first
```

## Cluster management (all tiers below: confirm first — affects multiple nodes)

```bash
pvecm create <cluster-name>
pvecm add <existing-cluster-node-ip>
pvecm status
pvecm nodes
pvecm delnode <node-name>
pvecm expected 1     # force quorum — single-node recovery only, real split-brain risk otherwise
```

## Firewall

```bash
pve-firewall start
pve-firewall stop
pve-firewall status

# Datacenter:  /etc/pve/firewall/cluster.fw   ([OPTIONS] enable: 1)
# Node:        /etc/pve/nodes/<node>/host.fw
# VM/CT:       /etc/pve/firewall/<vmid>.fw
#
# Add remote-management allow rules BEFORE enabling a restrictive default
# policy — locking yourself out of remote access to the node is a real,
# hard-to-recover-from failure mode.
```

## Backup and restore

```bash
vzdump <vmid> --storage <backup-storage> --mode snapshot --compress zstd
vzdump <ctid> --storage <backup-storage> --mode stop --compress zstd
vzdump --all --storage <backup-storage> --mode snapshot --compress zstd --mailto <admin-email>

# Restore — never without human confirmation (creates/overwrites a guest).
# Check pvesm status for target free space FIRST, especially for large disks.
qmrestore <path-to-vzdump-file> <vmid> --storage <storage>
pct restore <ctid> <path-to-vzdump-file>
```

## Common provisioning patterns (reference only — each step still follows the tier rules above)

### Cloud-init VM from a template

```bash
qm template <base-vmid>                                    # irreversible — confirm first

qm clone <base-vmid> <new-vmid> --name <new-name> --full
qm set <new-vmid> --ciuser <user> --sshkeys ~/.ssh/authorized_keys
qm set <new-vmid> --ipconfig0 ip=<ip>/<cidr>,gw=<gateway>
qm set <new-vmid> --nameserver <dns-ip>
qm start <new-vmid>
```

Note: some Proxmox documentation and community examples use VMIDs like
`9000` as a convention for template base images. That's a naming
convention some operators adopt, not a Proxmox default or a value to
copy into this fleet — check `docs/server-*.md` for whatever convention
(if any) applies to a given host before picking an ID.

### Batch-create containers

Bulk/loop patterns are explicitly a higher tier than the single-target
equivalent (see SKILL.md) — pilot one iteration manually, confirm it's
correct, before running the loop.

```bash
for i in $(seq 1 <count>); do
  CTID=$((<base-ctid> + i))
  pct create "$CTID" <storage>:vztmpl/<template-filename> \
    --hostname "<name-prefix>-${i}" --memory 1024 --cores 2 \
    --rootfs <storage>:8 \
    --net0 name=eth0,bridge=<bridge>,ip=<ip-prefix>.$((<ip-offset> + i))/<cidr>,gw=<gateway> \
    --unprivileged 1 --start 1
done
```

### Import a disk image (e.g. a cloud image)

```bash
wget <cloud-image-url>

qm disk import <vmid> <downloaded-image-file> <storage>
qm set <vmid> --scsi0 <storage>:vm-<vmid>-disk-0
qm set <vmid> --boot order=scsi0
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| VM won't start | `qm config <vmid>`, verify storage exists with `pvesm status` |
| "TASK ERROR: can't lock file" | Check for a genuinely running task first; if the task is gone, `qm unlock <vmid>` / `pct unlock <ctid>` |
| Container has no network | Check bridge exists: `brctl show`; verify firewall rules |
| Disk full on storage | `pvesm status` for usage; `lvs` for LVM thin pools |
| Cluster quorum lost | `pvecm expected 1` on a surviving node — single-node recovery only, confirm first |
| Migration fails | Check CPU type compatibility; confirm network reachability between nodes |
| Backup fails with lock error | `qm unlock <vmid>` / `pct unlock <ctid>` |
| Slow disk I/O in VM | `--scsihw virtio-scsi-single` plus disk options like `,iothread=1,discard=on` |
| Guest agent not responding | Install `qemu-guest-agent` in the guest, then `qm set <vmid> --agent 1` |
| SSH/command seems to hit the wrong host | See SKILL.md's Tailscale hostname-collision gotcha — verify with `ssh -v <host> 2>&1 \| grep "Connecting to"` |

## Useful paths

| Path | Contents |
|------|----------|
| `/etc/pve/` | Cluster-wide config (pmxcfs) |
| `/etc/pve/qemu-server/<vmid>.conf` | VM configuration files |
| `/etc/pve/lxc/<ctid>.conf` | Container configuration files |
| `/etc/pve/storage.cfg` | Storage definitions |
| `/etc/pve/nodes/` | Per-node configuration |
| `/var/lib/vz/` | Default local storage root |
| `/var/lib/vz/template/iso/` | ISO images |
| `/var/lib/vz/template/cache/` | Container templates |
| `/var/lib/vz/dump/` | Backup files |
| `/var/log/pve/tasks/` | Task logs |