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
• Why pvectl?
• Features
• Free vs Pro
• Requirements
• Tested Proxmox VE Versions
• Installation
• Configuration
• Usage
• Navigation
• Uninstallation
• Architecture
• QA Compatibility Matrix
• Known Limitations
• Disclaimer
• License
• 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 below for feature-level results.

---

🚀 Installation

# 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

For example (PVE nodes certificates signed with the internal CA):

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

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

# 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 file for full details.

⚠️ Use of this codebase for AI/ML training is explicitly prohibited — see 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
• fzf — the fuzzy finder that powers the entire UX
• jq manual — jq utility manual
• curl manual — curl manual
• The Proxmox VE API documentation that makes it all possible:
  • Proxmox VE API documentation
  • Certificate Management
• The MSP, devops/sysadmin and homelab community for the inspiration

---