DuckbootandClaude Opus 5.5
0df928ab11
r on the info screen restores the backup under the cursor of the backup list. - New guest (default): the next free VMID from `get cluster nextid`, editable. The original is left untouched. An id already used by a listed guest is refused. - Overwrite: replaces the guest itself. The guest must be stopped; its live status is read at apply and again right before the call. The VMID must be typed to confirm, then an "Overwrite" confirm follows. --storage is always passed. It is preselected to the storage of the guest's rootfs or first disk, and the choices are the node's storages that can hold CT (rootdir) or VM (images) disks. Start after restore is off by default, because a copy keeps the original's MAC address and IP. Safety: - cli.restore refuses force (overwrite) for any VMID other than the guest's own (explicit raise). A hypothesis property checks that no other VMID ever reaches the CLI with force. - The volid and storage are validated before they become arguments. - A backup of the other guest type is refused. A reused VMID can carry a qemu backup for a CT or the other way round, and whether PVE rejects a mismatched archive before removing the old guest is not verified. - An earlier guest's backup (visible with a) is labelled with that guest's name in the dialog and the confirm. - r before the info screen has loaded says "still loading". - Restore gets a 1-hour CLI timeout. Not run live: a live test would create a guest that then has to be deleted, which the issue reserves for the user's approval. A read-only check opened the dialog for CT 104 (next id 105, local-lvm preselected) and closed it without any call. Closes #15 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
# cv4pve-cli-tui
|
|
|
|
[](https://git.duckboot.net/Duckboot/cv4pve-cli-tui/actions)
|
|
|
|
Textual TUI for [cv4pve-cli](https://github.com/Corsinvest/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](https://docs.astral.sh/uv/) and a working `cv4pve-cli` on `PATH`.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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 `o` | in info: edit autostart, startup order (order, up and down delay) and tags (one confirmed `set config` call; empty fields remove the setting) |
|
|
| `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) |
|
|
| `Enter` then `f` | in info: fstrim in a running VM with the guest agent enabled (confirms; containers: use `pct fstrim` on the node) |
|
|
| `Enter` then `r` | in info: restore the backup under the cursor, as a new VMID (default, the original stays untouched; a copy keeps the original's network settings, so leave Start off until they are changed) or overwriting the guest itself (stopped guests only; type the VMID, then confirm) |
|
|
| `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 |
|
|
| `/` | filter the guest table as you type: space-separated terms, all must match (case-insensitive); plain term = part of name, VMID or a tag; `is:running` / `is:stopped`; `type:lxc` (or `ct`) / `type:vm` (or `qemu`). `Enter` keeps the filter and returns to the table, `Escape` clears it. The frame's bottom border shows `filter: <text> · N of M` |
|
|
| `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
|
|
|
|
```sh
|
|
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`.
|