discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
mytechspacexyz/pvectl · source
Snapshot 0 · 2026-11-04T12:47:28Z · Shell · AGPL-3.0
Content fingerprint
d8e248ad12624bdc9b31b3b2fc2f8bbc584bd2a7d10b11a9e36a4b025f4f740eGitHub description at capture
Pure bash CLI tool for Proxmox VE 7.x/8.x/9.x clusters management. No Python. No Go. No SDKs.
README at capture
# pvectl
```
██████╗ ██╗ ██╗███████╗ ██████╗████████╗██╗
██╔══██╗██║ ██║██╔════╝██╔════╝╚══██╔══╝██║
██████╔╝██║ ██║█████╗ ██║ ██║ ██║
██╔═══╝ ╚██╗ ██╔╝██╔══╝ ██║ ██║ ██║
██║ ╚████╔╝ ███████╗╚██████╗ ██║ ███████╗
╚═╝ ╚═══╝ ╚══════╝ ╚═════╝ ╚═╝ ╚══════╝
```
> **A pure bash+curl+fzf+jq interactive Proxmox VE cluster management tool for the terminal.**
> No web UI required. No Python. No Go. No SDKs. Just bash+curl+fzf+jq+core linux utils.
---
## Table of Contents
* [Demo](#-demo)
* [Why pvectl?](#-why-pvectl)
* [Features](#-features)
* [Free vs Pro](#-free-vs-pro)
* [Requirements](#-requirements)
* [Tested Proxmox VE Versions](#-tested-proxmox-ve-versions)
* [Installation](#-installation)
* [Configuration](#%EF%B8%8F-configuration)
* [Usage](#-usage)
* [Navigation](#-navigation)
* [Uninstallation](#%EF%B8%8F-uninstallation)
* [Architecture](#%EF%B8%8F-architecture)
* [QA Compatibility Matrix](#-qa-compatibility-matrix)
* [Known Limitations](#%EF%B8%8F-known-limitations)
* [Disclaimer](#%EF%B8%8F-disclaimer)
* [License](#-license)
* [Acknowledgements](#-acknowledgements)
---
## 🎬 Demo
---
## 🤔 Why pvectl?
Managing a Proxmox VE cluster has traditionally meant choosing between:
- The web UI — good and usable but not available on jump servers, headless environments or pure terminal workflows
- Raw `pvesh`/`pvecm`/`qm`/`pct` CLI commands — powerful but no interactive UX, no unified workflow
- Heavy automation frameworks — overkill for day-to-day operational tasks
**pvectl fills that gap** — a pure bash+curl+fzf+jq interactive tool for managing your entire Proxmox VE cluster — nodes, vms, containers, storages, pools, backups — directly from any terminal, including jump servers where a browser is not an option.
Zero dependencies beyond what's commonly available on any modern Linux system.
---
## ✨ Features
- 🖥️ **Node management** — interactive cluster nodes information view
- 💻 **VM management** — full lifecycle control via fzf-powered interactive menus
- 📦 **Container (LXC) management** — same interactive lifecycle control as for VMs
- 💾 **Storage management** — view and manage cluster storages
- 🗂️ **Pool management** — organize resources into pools
- 📋 **Backup management** — view and manage backups
- 📊 **Task monitoring** — interactive real-time task tracking while actions are being run on pve objects
- 🎨 **Themes** — customizable terminal UI themes
- 🔐 **Secure** — FQDN + CA/host certificate validation, Proxmox API token authentication only (no admin password used, tokens are independently revocable)
- 🔄 **Single entry point** — `pvectl manage` drives a fully interactive fzf menu system
- 🤖 **Detailed logging** — debug/info/error/warning logging via `pvectl debug on/off`
- 🔀 **Concurrent execution safe** — run multiple pvectl instances in parallel; each gets its own isolated, auto-cleaned temp directory
- 📋 **Configuration lifecycle management** — `pvectl setup reset/backup/restore`
- 📊 **Log management** — `pvectl log view/show/clean` with colorized output
- 🔍 **Startup diagnostics** — bash version and dependency checks with OS-aware install suggestions
- 🖥️ **Node-level cluster actions** — reboot/shutdown directly from the main menu with HA/quorum/running-guest safety checks
---
## 🆓💎 Free vs Pro
pvectl comes in two editions.
**Free Edition** covers the full operational lifecycle of vms and containers, plus storage, pool and node management:
- VM/Container: list, info, start, stop, suspend, resume, shutdown, reboot, reset, rename, destroy
- VM/Container snapshot: list, info, create, delete, rollback
- Storage: info, enable, disable
- Pool: info, list, create, edit, remove
- Node: info, reboot, shutdown, task monitoring
- Configuration management: setup reset/backup/restore
- Log management: log view/show/clean
- Concurrent execution — run multiple pvectl instances in parallel safely
**Pro Edition** adds provisioning, cloning/migration and backup/restore workflows:
- VM/Container: create, clone, migrate
- VM/Container: backup, restore
- Backup management: info, restore, delete
- Storage: ISO download, template download
> 🔗 Interested in the **Pro version**? Coming soon!
---
## 📋 Requirements
- `bash` 4.4 or higher (checked at startup)
- `curl` 7.18.0 or higher
- `fzf` 0.38.0 or higher
- `jq` 1.5 or higher
- `tar` and other core Linux utilities (see `.deps` for the full list)
- FQDN hostname for the Proxmox VE host/cluster — **no IP addresses**
- Valid certificate issued by internal or external CA (CA + host certificate)
- Proxmox API token (authentication is token-based only — no admin password is used, tokens can be independently revoked)
- DNS resolution for the FQDN(s)
> On startup pvectl checks the bash version and all dependencies. If a
> dependency is missing, pvectl detects the host OS and package manager
> and prints the exact install command needed.
### 🐧 Tested And Run On Host Operating Systems
| OS | Version | Notes |
|---|---|---|
| Red Hat Linux | 9 Latest (05-2026) | |
| Ubuntu | 24.04.4 (05-2026) | |
| Kali Linux | Latest (06-2026) | |
| Manjaro Linux | Latest (05-2026) | |
| Alma Linux | 9/10 Latest (06-2026) | |
| Rocky Linux | 9/10 Latest (06-2026) | |
| Alpine Linux | 3.23 (05-2026) | |
---
## 🧪 Tested Proxmox VE Versions
| Version | Status |
|---|---|
| 7.4.3 | ✅ Tested |
| 8.4.19 | ✅ Tested |
| 9.1.7 | ✅ Tested |
See the full [QA Compatibility Matrix](#-qa-compatibility-matrix) below for feature-level results.
---
## 🚀 Installation
```bash
# Clone the repository
git clone https://github.com/mytechspacexyz/pvectl.git
# Add pvectl to PATH via symlink in a folder already in PATH
cd ~/bin; ln -s <pvectl folder>/pvectl pvectl
# Run setup
pvectl setup
# Add autocompletion (optional but recommended)
pvectl completion >> ~/.bashrc
# or, for a different shell rc file:
pvectl completion >> <path to your shell rc file>
# Then restart the shell
exec $SHELL
```
---
## ⚙️ Configuration
During `pvectl setup` you will be prompted for:
- Proxmox VE cluster's node(s) FQDN(s) and their port(s) (usually at 8006 port if not proxied or changed explicitly)
- Proxmox admin username
- Proxmox API token (token ID + secret)
- CA certificate path
Pay **SPECIAL** attention to the CA certificate(s) that has to be included (and will be copied to the conf folder) while running `pvectl setup`:
It is best to issue certificates for your PVE cluster hosts with their FQDNs using your internal/external CA or create self-signed ones — pvectl is built with curl secure flags requiring the CA certificate for a session.
No IP address will work for this setup.
Usually the default Proxmox VE node certificates are under:
```
/etc/pve/nodes/<node name>/pve-ssl.pem
```
signed with:
```
/etc/pve/pve-root-ca.pem
```
(PVE Cluster Manager internal CA)
More about Proxmox VE certificate management (important):
[Certificate Management](https://pve.proxmox.com/wiki/Certificate_Management)
For example (PVE nodes certificates signed with the internal CA):
```bash
pvectl setup
Enter PVE server(s) hostname(s) with ports separated with spaces (pve10.int.ccc.xyz:8006 pve20.int.ccc.xyz:8006): pve10.int.alpi.xyz:8006 pve20.int.alpi.xyz:8006
Enter a PVE admin username [format: pveadmin@pve or root@pam]: pve-adm@pve
Enter a PVE admin token name: pve-adm-token
Enter a PVE token:
Enter the full path to CA certificate (PVE server(s) certificate(s) signed with): /tmp/ssl/certificates/alpi-ca.crt
setup has been completed successfully.
```
All configuration is stored inside the pvectl folder — nothing written outside the app directory.
---
## 💻 Usage
```bash
pvectl setup # configure your Proxmox VE connection
pvectl setup reset # reset configuration to defaults
pvectl setup backup # backup current configuration
pvectl setup restore # restore configuration from backup
pvectl manage # enter the interactive management menu
pvectl log view # view pvectl's log (colorized)
pvectl log show # scroll through pvectl's log
pvectl log clean # clean pvectl's log file
pvectl themes # customize the interface
pvectl debug on # enable debug logging
pvectl debug off # disable debug logging
pvectl completion # output bash completion script to stdout
pvectl describe # show pvectl description information
pvectl version # show version
pvectl help # show usage
```
> ⚠️ `pvectl log` requires a subcommand (`view`, `show` or `clean`) — running it alone displays usage information.
> All Proxmox management actions are performed exclusively through the interactive `pvectl manage` fzf menu. There are no direct scriptable subcommands for VM/CT/storage/pool operations.
> pvectl supports running multiple instances concurrently — each instance uses its own isolated, automatically cleaned-up temp directory.
---
## 🧭 Navigation
### fzf Navigation
| Key | Action |
|---|---|
| `↑` / `↓` | Navigate menu |
| `Enter` | Select item / drill into submenu |
| `Tab` | Multi-select |
| `Ctrl-A` | Select all |
| `Ctrl-D` | Deselect all |
| `Ctrl-P` | Toggle preview panel |
| `Ctrl-H` | Toggle preview panel on actions help |
| `Shift+↑` / `Shift+↓` | Scroll the preview window |
| `Ctrl-B` | Cancel / go back |
| `Esc` / `Ctrl+C` | Exit / go back |
### Node-level Menu Actions
| Key | Action |
|---|---|
| `Ctrl+X` | Reboot the selected node — checks HA status, cluster quorum and running VMs/CTs; prompts to stop-all or migrate-all before proceeding |
| `Ctrl+S` | Shutdown the selected node — same safety checks as reboot |
---
## 🗑️ Uninstallation
```bash
# Remove the symlink from PATH
unlink <path to the pvectl symlink>
# Remove bash completion (if added)
# Edit ~/.bashrc or similar and remove:
# - the _pvectl_completion() function block
# - the complete -F _pvectl_completion pvectl line
# Then restart the shell:
exec $SHELL
# Remove the cloned repository
rm -rf <pvectl folder>
```
---
## 🏗️ Architecture
```
pvectl (main entry)
├── assets/ # various assets like media files
├── conf/ # configuration files — generated during setup
│ ├── backups # configuration backups folder
│ ├── .common_configvars
│ ├── .configvars
│ ├── .deps
│ └── <CA cert file>
├── docs/ # documentation files
│ ├── .help
│ ├── .description
│ └── .version
├── examples/ # configuration examples
├── logs/ # app's logs
├── src/ # source code
│ ├── .functions.bash
│ ├── .functions_init.bash
│ ├── .functions_log.bash
│ ├── .functions_handlers.bash
│ ├── .functions_nodes_handlers.bash
│ ├── .functions_vms_handlers.bash
│ ├── .functions_pcs_handlers.bash
│ ├── .functions_pools_handlers.bash
│ ├── .functions_storages_handlers.bash
│ └── .functions_tasks_handlers.bash
└── tmp/ # app's temporary files folder
```
**Design philosophy:** Pure bash+curl+fzf+jq — every function is self-contained with all data inline. No shared helpers, no external SDKs. Any function can be extracted and used independently with the main pvectl vars set (see Configuration section above).
---
## 🧪 QA Compatibility Matrix
Tested against Proxmox VE 7.4.3, 8.4.19-21 and 9.1.7.
| Feature | 7.4.3 | 8.4.19-21 | 9.1.7 | Notes |
|---|---|---|---|---|
| VM start (Linux) | ✅ | ✅ | ✅ | |
| VM start (Windows) | ✅ | ✅ | ✅ | |
| VM shutdown (Linux) | ✅ | ✅ | ✅ | |
| VM shutdown (Windows) | ✅ | ✅ | ✅ | |
| VM stop (Linux) | ✅ | ✅ | ✅ | |
| VM stop (Windows) | ✅ | ✅ | ✅ | |
| VM suspend (Linux) | ✅ | ✅ | ✅ | |
| VM suspend (Windows) | ✅ | ✅ | ✅ | |
| VM resume (Linux) | ✅ | ✅ | ✅ | |
| VM resume (Windows) | ✅ | ✅ | ✅ | |
| VM reboot (Linux) | ✅ | ✅ | ✅ | |
| VM reboot (Windows) | ✅ | ✅ | ✅ | |
| VM reset (Linux) | ✅ | ✅ | ✅ | |
| VM reset (Windows) | ✅ | ✅ | ✅ | |
| VM list | ✅ | ✅ | ✅ | |
| VM rename | ✅ | ✅ | ✅ | |
| VM create (Linux) | ✅ | ✅ | ✅ | |
| VM create (Windows UEFI) | ✅ | ✅ | ✅ | |
| VM clone (Linux UEFI, online) | ❌ | ❌ | ✅* | Known PVE bug #3227 on 7.x/8.x. *On 9.x: cannot clone TPM state for Linux VMs |
| VM clone (Linux UEFI, offline) | ✅ | ✅ | ✅ | |
| VM clone (Windows UEFI, online) | ❌ | ❌ | ✅ | Cannot clone TPM state on 7.x/8.x — Proxmox design limitation, not a bug |
| VM clone (Windows UEFI, offline) | ✅ | ✅ | ✅ | |
| VM destroy (Linux) | ✅ | ✅ | ✅ | Fails if any storage is offline, even if VM disks aren't on it |
| VM destroy (Windows UEFI) | ✅ | ✅ | ✅ | |
| VM backup (Linux) | ✅ | ✅ | ✅ | |
| VM backup (Windows) | ✅ | ✅ | ✅ | |
| VM restore (Linux) | ✅ | ✅ | ✅ | |
| VM restore (Windows) | ✅ | ✅ | ✅ | |
| VM migrate (Linux) | ✅ | ✅* | ✅ | |
| VM snapshot create (Linux) | ✅ | ✅ | ✅ | |
| VM snapshot create (Windows) | ✅ | ✅ | ✅ | |
| VM snapshot delete (Linux) | ✅ | ✅ | ✅ | |
| VM snapshot delete (Windows) | ✅ | ✅ | ✅ | |
| VM snapshot list (Linux) | ✅ | ✅ | ✅ | |
| VM snapshot list (Windows) | ✅ | ✅ | ✅ | |
| VM snapshot rollback (Linux) | ✅ | ✅ | ✅ | |
| VM snapshot rollback (Windows) | ✅ | ✅ | ✅ | |
| Container start | ✅ | ✅ | ✅ | |
| Container shutdown | ✅ | ✅ | ✅ | |
| Container stop | ✅ | ✅ | ✅ | |
| Container reboot | ✅ | ✅ | ✅ | |
| Container backup (create/delete/restore) | ✅ | ✅ | ✅ | |
| Container migrate (online/offline) | ✅ | ✅ | ✅ | Online migration restarts the container — Proxmox limitation |
| Container create | ✅ | ✅ | ✅ | |
| Container clone (online) | ❌ | ❌ | ❌ | Full clone of a running container only possible from a snapshot |
| Container clone (offline) | ✅ | ✅ | ✅ | |
| Container destroy | ✅ | ✅ | ✅ | |
| Container list | ✅ | ✅ | ✅ | |
| Container suspend | N/A | N/A | N/A | Experimental, not currently supported |
| Container resume | N/A | N/A | N/A | Experimental, not currently supported |
| Container restore | ✅ | ✅ | ✅ | |
| Container snapshot create (online/offline) | ✅ | ✅ | ✅ | |
| Container snapshot delete | ✅ | ✅ | ✅ | |
| Container snapshot list | ✅ | ✅ | ✅ | |
| Container snapshot rollback | ❌ | ✅ | ✅ | Fails on 7.x: not most recent snapshot. Works via Proxmox UI manually |
| Container rename | ✅ | ✅ | ✅ | |
| Storage enable | ✅ | ✅ | ✅ | local/local-lvm cannot be disabled |
| Storage disable | ✅ | ✅ | ✅ | local/local-lvm cannot be disabled |
| Pool create | ✅ | ✅ | ✅ | |
| Pool edit | ✅ | ✅ | ✅ | |
| Pool remove | ✅ | ✅ | ✅ | |
| Pool list | ✅ | ✅ | ✅ | |
| Backup restore (VM) | ✅ | ✅ | ✅ | |
| Backup restore (CT) | ✅ | ✅ | ✅ | |
| Backup delete | ✅ | ✅ | ✅ | |
---
## ⚠️ Known Limitations (by Proxmox design itself or pvectl ones)
- All operations are accessed exclusively through the interactive `pvectl manage`
fzf menu — there are no direct CLI subcommands for scripting or automation
- VM clone (online) with TPM state is not supported on PVE 7.x/8.x due to a
known upstream Proxmox bug (#3227); resolved on PVE 9.x except for Linux
VMs with TPM, where TPM state still cannot be cloned online
- Container clone (online) is not supported — Proxmox only allows full clone
of a running container from a snapshot
- Container snapshot rollback fails on PVE 7.x with "not most recent snapshot"
even when targeting the latest snapshot (works correctly via the Proxmox UI) —
resolved on 8.x and 9.x
- Container suspend/resume are not currently supported (experimental upstream)
- VM destroy can fail with `storage 'xyz' is not online` if any configured
storage in the cluster is offline, even if the VM's disks don't reside on it
- `local` and `local-lvm` storages cannot be enabled/disabled on any tested version
---
## ⚠️ Disclaimer
pvectl is provided **as-is** without any warranty of any kind, express or implied. The authors and contributors are not responsible for any data loss, system outages, VM deletion, storage corruption, host unavailability, or any other damages resulting from the use or misuse of this tool.
**Always test in a non-production environment first. Use at your own risk.**
This project is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH**. All product names, trademarks and registered trademarks are property of their respective owners.
---
## 📄 License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)** — see the [LICENSE](LICENSE) file for full details.
⚠️ Use of this codebase for AI/ML training is explicitly prohibited — see [AI_USAGE_POLICY.md](AI_USAGE_POLICY.md).
In summary: you are free to use, modify and distribute this software, but any modified version must also be released under AGPLv3 and its source code made available. This applies even when the software is provided as a service over a network.
---
## 🙏 Acknowledgements
- [bash manual](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html)
- [fzf](https://github.com/junegunn/fzf) — the fuzzy finder that powers the entire UX
- [jq manual](https://jqlang.org/manual/) — jq utility manual
- [curl manual](https://curl.se/docs/manpage.html) — curl manual
- The Proxmox VE API documentation that makes it all possible:
- [Proxmox VE API documentation](https://pve.proxmox.com/pve-docs/api-viewer/index.html)
- [Certificate Management](https://pve.proxmox.com/wiki/Certificate_Management)
- The MSP, devops/sysadmin and homelab community for the inspiration
---
<div align="center">
**Built with ❤️ for MSPs, devops, sysadmins and homelabbers who live in the terminal**
[](https://github.com/mytechspacexyz/pvectl)
</div>