ProxmoxScripts: a text menu driven admin layer over a Proxmox cluster

A menu over the cluster, and the shape of the script tree

ProxmoxScripts is described as CCPVE, scripts for management and task automation in Proxmox VE, and the project description says it provides automation scripts for managing Proxmox VE systems efficiently, aimed at system administrators and DevOps professionals who want to make their Proxmox operations less repetitive.

The top level directory listing is the architecture. There is GUI.sh, which is the interactive entry point, and CCPVE.sh, which is the script that fetches and dispatches. Around them sit the functional areas: Cluster, Firewall, HighAvailability, Host, LXC, Networking, Resources, Security, Storage, ThirdParty, Utilities and VirtualMachines, plus Manuals, a .docs directory, a .check directory, a .site directory for the website, and a nodes.json.template for node configuration.

The organisation by area is what makes the collection navigable. An operator thinking about storage looks in Storage, and the examples given in the README for the non-interactive mode are exactly that: Host/QuickDiagnostic.sh for a host check, Storage/Benchmark.sh with device and mode arguments, VirtualMachines/CreateFromISO.sh with an ISO path, a VMID and a storage target.

The Utilities directory and the .check directory are the two that reveal the project's maturity. Utilities holds the shared helpers, and the version 2.0 notes describe a unified utility framework with new ArgumentParser, BulkOperations and Operations utilities that standardise script behaviour and error handling across the codebase. The .check directory holds the repository checks, which the documentation lists as line ending conversion, function indexing, source verification, code formatting, security analysis and dead code detection.

So this is not a loose pile of scripts. It is a collection with a shared library, a house style and a check suite, and the CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md at the root suggest a project with process around it.

The one-liner runs code straight from the internet

The quickest way in is a single command, and it is worth looking at exactly what it does before repeating it.

bash -c "$(wget -qLO - https://github.com/coelacant1/ProxmoxScripts/raw/main/CCPVE.sh)"

There is a shorter form using a short domain.

bash <(curl -L pve.coela.sh)

And a version that prints the help with the full header.

bash <(curl -L pve.coela.sh) -h

The mechanism is process substitution: the script is piped into bash rather than saved, and it is fetched fresh from the main branch on every invocation. The README calls this ephemeral mode, and it says the repository is downloaded fresh each invocation, and that for repeated usage you should clone the repo and call GUI.sh directly.

The branch handling is a real feature rather than a detail. The --testing flag downloads from the testing branch instead of main, and --branch takes an explicit branch name.

bash <(curl -L pve.coela.sh) --testing

bash <(curl -L pve.coela.sh) --branch experimental-feature

The version 2.0 notes describe branch management as a key feature, with a stable main branch and a testing branch, and built-in updates. That is a sensible model for infrastructure scripts, where you want a tested path and a bleeding-edge path, and where the bleeding-edge path is opt-in.

The security posture follows from the design. Running code fetched over the network at the moment of execution means the code that runs is whatever the branch holds at that second. The README's own installation guidance says that for production use you should clone and maintain a local copy of the repository, review and validate all scripts before execution on production infrastructure, test in a non-production environment first, and keep a local copy for review and version control. The warning block is explicit that you are responsible for any changes made to your infrastructure.

Non-interactive mode is what makes this scriptable rather than a toy menu

The most useful addition in version 2.0 is the ability to run a specific script without launching the interactive interface, because that is what turns a menu of utilities into something a terminal or an automation system can drive.

To see what is runnable, list the scripts by relative path.

bash <(curl -L pve.coela.sh) --list

To run one of them.

bash <(curl -L pve.coela.sh) --run Host/QuickDiagnostic.sh

And to pass arguments through to it.

bash <(curl -L pve.coela.sh) --run Storage/Benchmark.sh --args "--device /dev/nvme0n1 --mode quick"

The same works through the wget form, which is what you would use where process substitution is awkward, such as a cron job or a container without curl.

bash -c "$(wget -qLO - https://github.com/coelacant1/ProxmoxScripts/raw/main/CCPVE.sh)" --run VirtualMachines/CreateFromISO.sh --args "--iso debian-12.iso --vmid 900 --storage local-lvm"

Two details from the best practices list are worth carrying. UTILITYPATH is exported automatically, so scripts can source the shared helpers without being told where they are. And the recommendation is to use --list first if you are unsure of a relative path, which is the same advice as checking a filename before running it.

The version 2.0 notes also describe a temporary multi-remote mode using IP or VMID ranges, so a bulk operation can be aimed at a set of nodes without re-downloading the repository, and the remote cluster management feature lets scripts execute on single or multiple Proxmox nodes.

Remote execution needs sshpass, jq and a node configuration file

The prerequisites section splits the two ways of using the collection, and that split is the practical decision to make first.

For local execution on Proxmox you need Proxmox VE 8.x or newer installed and running, SSH access with appropriate privileges, and basic knowledge of Proxmox operations and Linux.

For remote execution from any Linux system you need any major Linux distribution, and four specific tools. wget and unzip for updating scripts from GitHub, jq for parsing node configuration files, and sshpass for password-based SSH authentication, which is not needed if you are using SSH keys.

apt update
apt install git wget unzip jq sshpass

The node configuration file is the piece that makes remote work possible, and the repository ships a template for it at nodes.json.template. The jq dependency exists because of that file, since jq is what parses it.

On the GUI side, the cross-platform claim is handled by auto-detection. The note says it works on any Linux distribution and automatically detects and uses the appropriate package manager, with apt, dnf, yum, zypper and pacman named. The local execution path is therefore the GUI talking to a local node, and the remote path is the GUI talking over SSH to one or more nodes, using a different credential model depending on whether you have keys or a password.

For the interactive interface, the README describes a text-based GUI with a comprehensive help system and settings, and the version 2.0 notes add that the branch management and settings are accessible from any menu.

One thing the documentation does not describe is what happens when a remote node is unreachable or a bulk operation partially fails. The bulk operations are described as having progress tracking, detailed statistics and automatic success and failure reporting, which suggests failures are reported rather than silently ignored, but the recovery story is not spelled out in the visible text.

Where ProxmoxScripts is the wrong tool

The first wrong-tool case is a team that wants infrastructure as code. These scripts apply operations to a running cluster from a menu or a command line. They are the opposite of a declarative model where you commit the desired state and a reconciler makes it true. For a cluster whose state must be reproducible, auditable and reviewable, a declarative tool is the right shape and this is not it.

The second case is a cluster where running unreviewed remote code is unacceptable. The curl one-liner fetches and executes the current contents of a branch on the internet. In an environment with strict change control, a script whose content changes under you between runs cannot be approved once and trusted later. The README's own production guidance is to clone and maintain a local copy, which is the answer, and it means the tool is usable in that setting only if you adopt the clone-first workflow.

The third case is a user who wants a supported product. There is a documentation site, a Discord, a changelog and a security file, but this is a shell script collection maintained by one person, not a commercial product with a support contract, and the Proxmox API itself changes between releases. The version 2.0 notes mention that scripts were validated against Proxmox VE 9.1.1 documentation, which is the kind of statement that has to be re-checked with each Proxmox release rather than assumed.

There is also a general point about shell in an administrative context. The scripts run with SSH privileges against a hypervisor, they are not type checked, and the .check directory's security analysis and dead code detection are static checks rather than a proof of anything. A script that computes a storage target or a VMID wrong will do so quietly.

On licensing, the project is GPL-3.0 with a LICENSE file at the root, which is the copyleft licence. If you modify these scripts and distribute them, the source obligation applies, which is the right fit for a community infrastructure collection and a consideration for a commercial one.

Editorial conclusion

ProxmoxScripts suits a Proxmox operator who wants a menu driven way to run the same maintenance tasks across one node or a whole cluster, and who wants the option of running a specific script non-interactively from a terminal or a job. It does not suit a team that wants a declarative infrastructure tool or a supported product with an API, since this is a shell script collection with no service contract. Before adopting, read the warning in the README and validate the scripts you intend to run in a non-production environment, and for production use clone the repository and maintain a local copy rather than running the curl one-liner against a live cluster.

Frequently asked questions

Official sources

1. coelacant1/ProxmoxScripts on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases