cv4pve-cli-tui

Textual TUI for cv4pve-cli: list Proxmox VE guests (VMs and LXC), start/shutdown/stop/reboot them, and change cores, memory and disk size. The table shows CPU % and Mem % of running guests and the info screen shows in-use values (refresh with g).

It shells out to cv4pve-cli and uses its current context (cv4pve-cli config use <name>); it stores no credentials itself. Tested with cv4pve-cli 2.4.0; with another version the app warns at startup, because it parses output formats that are not a stable API.

Install

Needs uv and a working cv4pve-cli on PATH.

uv tool install git+https://git.duckboot.net/Duckboot/cv4pve-cli-tui
cv4pve-tui                      # from any directory
uv tool upgrade cv4pve-tui      # later: get the newest main
uv tool uninstall cv4pve-tui

From a local checkout instead: uv tool install . (add --force to reinstall after changes).

Run

Installed: cv4pve-tui. From a checkout without installing:

uv run cv4pve-tui

Key	Action
s	start
S	shutdown (confirm)
x	stop - hard power-off (confirm)
r	reboot (confirm)
Enter	info: resources (CPU, memory, swap, disks), backups, backup job, network (config and runtime IPs)
Enter then e	in info: edit cores / memory / grow a disk (disk growth asks again; it cannot be undone)
Enter then b	in info: backup now (snapshot, zstd, storage choice); a there = also show backups of earlier guests that had the same VMID
Enter then n	in info: edit network (bridge, VLAN, firewall, IPv4/IPv6; VM IP via cloud-init at next boot); u there = undo the last network change of this guest (this session only)
Enter then p / R / D	in info: take a snapshot (name, description, VM: include RAM) / roll back to the snapshot under the cursor (confirms; starts the guest again if it is running) / delete the snapshot under the cursor (confirms)
t	shell in a running LXC container (ssh -t root@<node> pct enter <vmid>)
l	tasks: recent cluster tasks (start, duration, node, type, VMID, user, status; ! marks failures); Enter shows the log of the task under the cursor, g reloads. In info: l = only this guest's tasks
U	package updates: pending updates per online node (node, package, current, new, origin, priority), read-only; g reloads. The list is as of the node's last apt update. The frame's bottom border shows the count
g	refresh
c	switch cv4pve-cli context (cluster)
q	quit

Warning: link changes (bridge, VLAN, firewall) apply immediately on a running guest and can cut its network (and DNS for others if the guest is your DNS server). IP changes on a running container may need a reboot of the container (seen: static -> DHCP gave no IPv4 until a reboot).

The shell key needs key-based root SSH to the PVE node (LXC only).

Switching context runs cv4pve-cli config use, which changes cv4pve-cli's global current context: other shells and scripts follow, and it stays after the app exits.

A ! in the first column marks a guest that no backup job covers (Proxmox's not-backed-up list); the frame's bottom border shows how many.

Empty fields in the edit dialog are left unchanged. If a CPU/memory change cannot be hot-plugged, the app tells you it applies at the next reboot.

Development

uv sync
uv run pytest
uv run ruff check src tests && uv run ruff format --check src tests

Tests mock cv4pve-cli; they never touch a cluster. CI (.gitea/workflows/ci.yaml) runs the same commands on every PR into main; ruff is pinned in the dev group so local runs and CI check the same rules. Design: docs/plans/guest-tui-mvp.md.