Getting started

cv4pve-report runs outside the cluster — on your workstation, a management VM or a scheduled job — and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes.

Installation

Platform	How
Linux	wget https://github.com/Corsinvest/cv4pve-report/releases/latest/download/cv4pve-report-linux-x64.zip && unzip cv4pve-report-linux-x64.zip && chmod +x cv4pve-report ARM: cv4pve-report-linux-arm64.zip, cv4pve-report-linux-arm.zip
Debian / Ubuntu	sudo dpkg -i cv4pve-report-VERSION-ARCH.deb (amd64, arm64, armhf)
RHEL / Fedora	sudo rpm -i cv4pve-report-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl)
Arch Linux	yay -S cv4pve-report
Windows (WinGet)	winget install Corsinvest.cv4pve.report
Windows (manual)	cv4pve-report.exe-win-x64.zip — also x86 and arm64
macOS (Homebrew)	brew install corsinvest/tap/cv4pve-report
macOS (installer)	cv4pve-report-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel)
macOS (manual)	cv4pve-report-osx-arm64.zip or cv4pve-report-osx-x64.zip

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

Connect to the cluster

Create a dedicated user and API token first — see Permissions. Then:

cv4pve-report --host=pve1.local --api-token='report@pve!report=UUID' export

Option	What it does
--host	One or more nodes, comma-separated: pve1,pve2:8006,[fe80::1]. The port defaults to 8006. At startup the first node that accepts a connection is used, so the tool runs while a node is down; if the login on that node fails, the others are not tried. Any node gives the view of the whole cluster.
--api-token	USER@REALM!TOKENID=UUID, Proxmox VE 6.2 or later. Recommended. Quote it on the command line: ! is special in bash.
--username / --password	Alternative to the token, e.g. --username=report@pve (without a realm, pam is used). Accounts with two-factor authentication cannot log in this way — use a token.--password=file:/path/secret asks for the password the first time and saves it in that file obfuscated, not encrypted (the key is built into the tool): protect the file like the password itself.
--validate-certificate	Verify the node TLS certificate. Off by default, so the default self-signed Proxmox certificate is accepted — turn it on if the nodes have a trusted certificate.

Long command lines can go in a parameter file, one option per line, passed with @:@/etc/cv4pve/production.conf. On error the tool prints ERROR: … and exits with code 1.

Run

cv4pve-report has two commands:

Command	What it does
export	Reads the cluster and writes the report.
create-settings	Writes settings.json in the current folder with the default settings (or those of --fast / --full), to edit and pass with --settings-file — see Settings. Needs no connection to the cluster.

Options of export:

Option	What it does
--format	Xlsx (default), Html or Json — see Output.
--output, -o	Path of the .zip to write. Default: Report_YYYYMMDD_HHmmss.zip in the current folder. If the path does not end in .zip, .zip is appended. An existing file is overwritten.
--fast	Fast profile, overview tables only: no detail sheets, snapshots, disks, partitions, guest agent data, RRD, storage content, backups or firewall. For a quick look at a large cluster.
--full	Full profile: adds SMART data, syslog, cluster log and guest RRD, reads a week of RRD history instead of a day, and limits the firewall log to the last 3 days.

Without --fast or --full the standard profile is used. The profiles page lists exactly what each one turns on.

cv4pve-report --host=pve1 --api-token='report@pve!report=UUID' export                   # standard profile, Excel
cv4pve-report --host=pve1 --api-token='report@pve!report=UUID' export --fast            # quick inventory of a large cluster
cv4pve-report --host=pve1 --api-token='report@pve!report=UUID' export --full            # everything, for audits
cv4pve-report --host=pve1 --api-token='report@pve!report=UUID' export --format Html -o cluster-2026-09

# Your own selection of sections
cv4pve-report create-settings --full        # then edit settings.json
cv4pve-report --host=pve1 --api-token='report@pve!report=UUID' --settings-file=settings.json export

--format, --output, --fast and --full go after export. --settings-file goes before the command, with the connection options. A settings file always wins over --fast and --full.

While it runs, the tool shows the section it is reading on one line. When the output is redirected — a scheduled job, a log file — it prints one line per step instead. At the end it prints Report generated: <path>.

Next

The report is a .zip with the sections of the cluster, one sheet, page or file each: Output explains the formats and where to start reading, and Sections every table and column.