# pvetui: a terminal console for Proxmox VE that also runs from scripts

> pvetui is a Go terminal user interface for Proxmox Virtual Environment, built on tview and tcell, with multi-profile connections, an embedded noVNC console and a set of CLI subcommands for non-interactive work. It suits admins who live in a terminal and want one binary instead of a browser, and it suits automation because the same tool exposes list, create and restore commands.

**devnullvoid/pvetui** — Terminal UI for Proxmox VE

- Repository: https://github.com/devnullvoid/pvetui
- Website: https://pvetui.org
- Stars: 758 · Forks: 23
- Language: Go
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/devnullvoid-pvetui

## A Proxmox console built on tview and tcell

pvetui is a terminal user interface for Proxmox Virtual Environment, written in Go, and its dependency list shows the shape of it. The rendering layer is github.com/rivo/tview with github.com/gdamore/tcell/v2 underneath, and the command line is handled by github.com/spf13/cobra with github.com/spf13/viper for configuration. That is a familiar stack for Go terminal applications, and it means the interface is drawn with tview widgets rather than a web view.

The feature list covers the objects an administrator actually touches. VMs, containers, nodes and cluster resources are all listed, and the interface is described as Vim-style navigation with customizable key bindings. Screenshots in the repository are organised as node management and guest management views, with a longer set collected in docs/SCREENSHOTS.md.

Two integrations go beyond a table viewer. The README lists integrated shells that open SSH directly to nodes, VMs and containers, and a VNC console feature built on an embedded noVNC client with automatic authentication. The second one removes a real annoyance: switching to a browser-based VNC session normally means another credential prompt.

A caching layer sits underneath the interface, and the go.mod file names its store: github.com/dgraph-io/badger/v4, an embedded key value database. The Dockerfile creates a /app/cache/badger directory and sets CACHE_DIR to /app/cache, which is where that state lives on disk.

## One token or one password, never both in a profile

The configuration format is multi-profile, and the first thing to understand is that a profile holds a connection to one Proxmox endpoint, not to one node. The README describes the format as supporting multiple Proxmox connections, and the example file in the repository shows the shape of a profile entry.

```yaml
profiles:
  default:
    addr: "https://your-proxmox-host:8006"
    user: "your-user"
    # Choose one authentication method:
    password: "your-password"           # Method 1: Password auth
    # OR
    token_id: "your-token-id"          # Method 2: API token (recommended)
    token_secret: "your-secret"
    insecure: false
```

The rule that catches people is the authentication constraint. The README states that only one authentication method, password or token, is allowed per profile, and the example comments mark the API token as the recommended route. The insecure key controls TLS verification for the endpoint, which is worth setting deliberately rather than leaving at its default when your Proxmox host uses a self-signed certificate.

Configuration is edited through a wizard rather than a hand-written file. On first run the app offers to create and edit a config file in a TUI wizard, and you can launch it again with the --config-wizard flag. The wizard validates input, and the config file can be a SOPS-encrypted file, with github.com/getsops/sops/v3 and filippo.io/age in the dependency list to support that. Legacy configurations are migrated automatically to the modern profile-based format, which matters if you are moving from an older install rather than starting fresh.

## Installing through Go, a package, or a source build

There are more than one route to a working binary, and the README is unusually complete about them. The route it recommends for Go users is a single module install.

```bash
go install github.com/devnullvoid/pvetui/cmd/pvetui@latest
```

That command needs Go 1.24 or newer. The go.mod file declares go 1.26.0, and the Dockerfile builds with golang:1.27-alpine, so a machine with an older toolchain will not build from source without upgrading first.

For people who do not want a Go toolchain, pre-compiled binaries are published on the Releases page, and the instructions are to download, extract and run the ./pvetui executable. Debian and RPM packages are published with each release as well, and can be handed to the system package manager.

```bash
# Debian/Ubuntu
sudo apt install ./pvetui_*_linux_amd64.deb

# Fedora/RHEL/openSUSE
sudo dnf install ./pvetui_*_linux_amd64.rpm
```

There is also a Cloudsmith hosted package repository, which the README notes is provided as free hosting for open source projects, and that repository is configured with a curl command piped to sudo bash followed by an apt or dnf install. Arch Linux users have three AUR packages covering a prebuilt binary, a release package built from source, and a version built from the current source tree. macOS has a Homebrew Cask, and Windows has a Scoop bucket.

One rough edge is documented. The README warns that macOS users may hit Gatekeeper warnings with pre-compiled binaries, and points to a troubleshooting guide that covers bypassing the warning or building from source.

## Group mode puts several clusters in one view

The most interesting feature for a larger estate is Group Mode. The README describes it as combining multiple Proxmox profiles into a unified view with routed actions per cluster. That is a different thing from simply switching between profiles: a single list can hold guests from more than one Proxmox installation, and an action taken on a row has to be routed back to the cluster that owns it.

Routing actions correctly is the hard part of that design, and it is the reason a multi-cluster view is more than a display feature. Anything the interface does against a resource, starting a guest or reading a task, has to travel over the connection belonging to the profile that provided the resource.

Profile switching is the simpler counterpart, and it comes with the same tooling as the rest of the application. The multi-profile support feature is listed as managing multiple Proxmox connections with profile switching, and the config wizard handles creation and validation of those profiles.

The repository also points to an interactive Proxmox VE API reference hosted at devnullvoid.github.io/pvetui-openapi, described as a Proxmox API browser. For a tool that talks to the Proxmox API on your behalf, that reference is the place to check which endpoints are being used, and the go.mod file shows the API is consumed through github.com/getkin/kin-openapi.

## The same binary works without a terminal interface

The newest part of the feature list is the CLI. The README describes CLI subcommands for using pvetui non-interactively from scripts or AI agent workflows, and the listed coverage is wide: listing and showing nodes, guests and tasks, creating and migrating VMs and LXCs, managing storage content, downloading templates and OCI images, and restoring backups.

That is the same binary with two personalities. The interactive interface is the main event for a human at a terminal, while the subcommands exist so that the operations can be scripted. The mention of agent workflows is a signal about where the author expects the tool to be used, and it is worth taking at face value when you decide whether pvetui fits an automation pipeline.

Restoring backups and downloading templates are privileged operations, so the permissions on the Proxmox API user matter more here than in a read-only dashboard. The README does not document a role recipe, which means the permission set is something you have to work out for your own deployment.

The interface also mentions a plugin system for opt-in extensions, including a Community Scripts installer, enabled through a Manage Plugins dialog or a config file entry. Plugins are opt-in rather than default, so a fresh install does not pull in extra code, but the presence of a plugin path means the set of things the tool can do is not fully described by the core binary alone.

## Running pvetui in a container needs a TTY and a small cache volume

The repository ships a Dockerfile and a docker-compose.yml, which is unusual for an interactive TUI and worth reading closely. The compose file sets tty and stdin_open to true, sets restart to no with a comment explaining that interactive TUI applications should not restart, and applies a no-new-privileges security option.

Environment variables are how the container is configured, and the compose file reads them from a .env file. The full set covers the connection and the runtime.

```bash
PVETUI_ADDR=https://your-proxmox-server:8006
PVETUI_USER=root
PVETUI_PASSWORD=your-password
PVETUI_DEBUG=false
PVETUI_CACHE_DIR=/app/cache
PVETUI_API_PATH=/api2/json
PVETUI_INSECURE=false
PVETUI_SSH_USER=root
```

The same .env.example file also lists optional SSH jump host variables: PVETUI_SSH_JUMPHOST_ADDR, PVETUI_SSH_JUMPHOST_USER, PVETUI_SSH_JUMPHOST_KEYFILE and PVETUI_SSH_JUMPHOST_PORT. The compose file maps the main connection variables into the container environment and mounts ./cache to /app/cache for persistence.

Resource limits are tight, and that is a signal about the intended footprint. The compose file reserves 64M of memory and 0.1 CPUs and caps the container at 256M and 0.5 CPUs, which fits a client that keeps state in an embedded cache. The Dockerfile compiles a static binary with CGO_ENABLED=0 and GOOS=linux, and the final image adds openssh-client so the integrated shells have an ssh binary to call. A note at the end of the compose file is easy to miss and worth reading twice: for a TUI, use docker-compose run rather than docker-compose up.

## Recent releases, an MIT licence, and a moving API surface

The project is MIT licensed, with the licence file in the repository root, and the repository also tracks third party licences in a separate THIRD_PARTY_LICENSES.md file. That second file matters more than it sounds for a tool that links a large Go dependency tree, including cloud provider SDKs that arrive as indirect dependencies.

Release cadence has been quick. The version history shows v1.4.4 published on 2026-10-03, v1.4.3 on 2026-07-16 and v1.4.2 on 2026-07-03, and the last push to the repository was on 2026-10-19. The project is not archived and the releases are frequent, which is good news for a tool whose interface depends on the Proxmox API continuing to behave as expected.

The flip side is that a fast-moving 1.4 line means the surface area changes. The CLI subcommands, the plugin system and Group Mode are all recent additions, and the CHANGELOG.md at the repository root is where you would look for what changed in a given release before upgrading a shared install.

One documentation gap is worth naming. The README lists the CLI capability in a single dense bullet and does not document individual subcommands or their flags, so for the scripted use case you will need to explore the command surface yourself or read the documentation the repository points to under docs/ before assuming a particular invocation exists.

## Conclusion

pvetui fits Proxmox administrators who want a keyboard-driven view of nodes, guests and tasks, and teams that need the same inventory tool to run from a script or an agent workflow. It does not fit a mixed shop where some operators will only use the web interface, and it does not fit a cluster where API tokens are not permitted, since a profile needs either a token or a password. Before adopting, create one profile with the config wizard, confirm the Proxmox user has the permissions the actions need, and test the go install route on a workstation before distributing binaries, since the README warns of Gatekeeper warnings on macOS.

## FAQ

### How do I install pvetui on my machine?

The README recommends a single Go module install for Go users, go install github.com/devnullvoid/pvetui/cmd/pvetui@latest, which needs Go 1.24 or newer. Pre-compiled binaries, Debian and RPM packages, a Cloudsmith package repository, Arch AUR packages, a Homebrew Cask and a Scoop bucket are also listed.

### How do I set up authentication for a pvetui profile?

Each profile accepts either a password or an API token, and the README states that only one authentication method is allowed per profile, with the API token marked as recommended. Configuration is created with the first run wizard or by launching the --config-wizard flag.

### Can pvetui be used in scripts instead of the terminal interface?

Yes. The README describes CLI subcommands for using pvetui non-interactively from scripts or AI agent workflows, covering listing and showing nodes, guests and tasks, creating and migrating VMs and LXCs, managing storage content, downloading templates and OCI images, and restoring backups.

### What does Group Mode do in pvetui?

Group Mode combines multiple Proxmox profiles into one unified view with routed actions per cluster, so resources from more than one Proxmox installation appear together and each action is sent to the right connection.

### Can I run pvetui inside Docker?

The repository ships a Dockerfile and docker-compose.yml for it. The compose file enables tty and stdin_open, mounts ./cache to /app/cache, and its note says to use docker-compose run rather than docker-compose up for TUI applications.

## Sources

- [devnullvoid/pvetui on GitHub](https://github.com/devnullvoid/pvetui)
- [License: MIT](https://github.com/devnullvoid/pvetui/blob/master/LICENSE)
- [Project website](https://pvetui.org)
- [README](https://github.com/devnullvoid/pvetui/blob/master/README.md)
- [Releases](https://github.com/devnullvoid/pvetui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/devnullvoid-pvetui