pve_tui

A terminal-based tool for managing Proxmox VE clusters. Provides both an interactive TUI and a CLI.

Requirements

• Python 3.14+
• uv (recommended) or pipx

Installation

uv tool install pve-tui --index-url https://git.kropcloud.net/api/packages/JustScreaMy/pypi/simple/ --extra-index-url https://pypi.org/simple/

Alternative: pipx

pipx install pve-tui --index-url https://git.kropcloud.net/api/packages/JustScreaMy/pypi/simple/ --pip-args='--extra-index-url https://pypi.org/simple/'

Development

uv sync

Configuration

Create a config file at one of these locations (checked in order):

1. ./config.toml (current directory)
2. ~/.config/pve_tui/config.toml (Linux)
3. ~/Library/Application Support/pve_tui/config.toml (macOS)
4. %APPDATA%/pve_tui/config.toml (Windows)

[contexts.my-cluster]
base_url = "https://proxmox.example.com"
token_id = "your_token_id"
token = "your_secret_token"

The config format supports multiple contexts (see config.example.toml), but context selection is not yet implemented — the app currently uses the first context alphabetically.

Environment variables PVE_TOKEN_ID and PVE_TOKEN override config values.

API Token Permissions

The token needs the following minimum privileges for full functionality:

Privilege	Used for
Sys.Audit	Listing nodes and cluster resources
VM.Audit	Reading VM/CT status, config, and snapshots
VM.PowerMgmt	Start, stop, shutdown, reboot
VM.Snapshot	Creating snapshots
VM.Snapshot.Rollback	Rolling back to a snapshot
VM.Config.Options	Managing group tags on VMs/CTs

To set up an API token with the minimum required permissions, run the following on your Proxmox node (replace user@realm with your actual user):

# 1. Create a role with the required privileges
pveum role add TUIRole -privs 'VM.Audit,VM.PowerMgmt,VM.Snapshot,VM.Snapshot.Rollback,VM.Config.Options,Sys.Audit'

# 2. Create an API token (save the displayed secret — it is shown only once)
pveum user token add user@realm pve-tui

# 3. Assign the role to the token
pveum aclmod / -tokens 'user@realm!pve-tui' -roles TUIRole

Tip: To list existing users and see available realms, run pveum user list.

Note: If the token has Privilege Separation enabled (the default), permissions must be assigned directly to the token (step 3), not just to the user.

Usage

TUI

pve-tui

Interactive split-view interface with server/group list on the left and details/actions on the right.

Keybindings:

Key	Action
r	Refresh server list
g	Toggle servers/groups view
Up/Down	Navigate list
Space	Select/deselect item
Tab	Switch panes
q	Quit

CLI

pve [command]

All commands accept VMIDs or group names as targets.

Server management:

pve list                        # List all servers
pve server start <targets...>   # Start servers
pve server stop <targets...>    # Hard power off
pve server shutdown <targets...> # Graceful shutdown
pve server reboot <targets...>  # Reboot

Snapshots:

pve snapshot list <target>                      # List snapshots
pve snapshot create <targets...> [--name NAME]  # Create snapshot
pve snapshot rollback <targets...>              # Rollback to latest
pve snapshot rollback <targets...> --snapshot NAME  # Rollback to specific

Groups:

Groups are stored as Proxmox tags with a pve-tui- prefix.

pve group list                          # List all groups
pve group add <group> <targets...>      # Add servers to group
pve group remove <group>                # Remove entire group
pve group detach <group> <targets...>   # Detach servers from group

Development

# Install with dev dependencies
uv sync

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Pre-commit hooks
prek run --all-files