DuckbootandClaude Opus 5.5
d97ad22c78
/ opens a filter box under the guest table, and the table filters as you type. Terms are separated by spaces, all must match, and case is ignored: - a plain term matches part of the name, the VMID or a tag - is:running and is:stopped match the status - type:lxc/ct and type:vm/qemu match the guest type Enter keeps the filter and goes back to the table. Escape clears it, from the box or from the table. The frame shows "· filter: <text> · N of M". Actions only ever see the visible rows, and the filter survives reloads and context switches. Review fixes: - Typing "[/b]" or "[/]" crashed the app, because the filter text went into the border subtitle, which Textual parses as markup. The subtitle is now plain text, so "[red]" is also shown literally. - Escape on the table now clears a filter that was applied with Enter. - guest_matches tolerates a None status or type. Read-only live check on mainframe: "debian" gives 104, "type:vm" gives 108, "community-script is:running" gives 14 of 19, and "is:stopped" gives 0 of 19. Closes #16 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
4.2 KiB
Markdown
80 lines
4.2 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 `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 |
|
|
| `/` | 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`.
|