cv4pve-cli

   ______                _                      __
  / ____/___  __________(_)___ _   _____  _____/ /_
 / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
/ /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
\____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

Command Line Interface for Proxmox VE (Made in Italy)

Quick Start

# Check available releases at: https://github.com/Corsinvest/cv4pve-cli/releases
# Download specific version (replace VERSION with actual version number)
wget https://github.com/Corsinvest/cv4pve-cli/releases/download/VERSION/cv4pve-cli-linux-x64.zip
unzip cv4pve-cli-linux-x64.zip

# Make executable
chmod +x cv4pve-cli

# Run interactive shell
./cv4pve-cli --host=YOUR_HOST --username=root@pam --password=YOUR_PASSWORD sh

# Execute API command
./cv4pve-cli --host=YOUR_HOST --username=root@pam --password=YOUR_PASSWORD get /nodes

Features

Core Capabilities

Performance & Reliability

Native C# implementation
Cross-platform (Windows, Linux, macOS)
API-based operation (no root access required)
Cluster support with automatic failover
High availability with multiple host support

Flexible API Access

Full REST API coverage (GET/POST/PUT/DELETE)
API documentation generated at runtime
Usage command with complete documentation
Multiple output formats (text, json, table)
ls command like filesystem navigation

Advanced Features

Interactive shell mode for exploration
Script file execution support
API token support (Proxmox VE 6.2+)
SSL validation options
Parameter files for complex setups
Alias commands for frequent operations
API metadata cache for faster startup
Command history persistence

Enterprise Features

Multiple host support for HA
Timeout management for operations
Error resilience and detailed logging
Comprehensive command documentation
Automated scripting capabilities

Installation

Linux Installation

# Check available releases and get the specific version number
# Visit: https://github.com/Corsinvest/cv4pve-cli/releases

# Download specific version (replace VERSION with actual version like v1.9.0)
wget https://github.com/Corsinvest/cv4pve-cli/releases/download/VERSION/cv4pve-cli-linux-x64.zip

# Alternative: Get latest release URL programmatically
LATEST_URL=$(curl -s https://api.github.com/repos/Corsinvest/cv4pve-cli/releases/latest | grep browser_download_url | grep linux-x64 | cut -d '"' -f 4)
wget "$LATEST_URL"

# Extract and make executable
unzip cv4pve-cli-linux-x64.zip
chmod +x cv4pve-cli

# Optional: Move to system path
sudo mv cv4pve-cli /usr/local/bin/

Windows Installation

Option 1: Winget (Recommended)

# Install using Windows Package Manager
winget install Corsinvest.cv4pve.cli

Option 2: Manual Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-cli/releases
# Download specific version (replace VERSION with actual version)
Invoke-WebRequest -Uri "https://github.com/Corsinvest/cv4pve-cli/releases/download/VERSION/cv4pve-cli.exe-win-x64.zip" -OutFile "cv4pve-cli.zip"

# Extract
Expand-Archive cv4pve-cli.zip -DestinationPath "C:\Tools\cv4pve-cli"

# Add to PATH (optional)
$env:PATH += ";C:\Tools\cv4pve-cli"

macOS Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-cli/releases
# Download specific version (replace VERSION with actual version)
wget https://github.com/Corsinvest/cv4pve-cli/releases/download/VERSION/cv4pve-cli-osx-x64.zip
unzip cv4pve-cli-osx-x64.zip
chmod +x cv4pve-cli

# Move to applications
sudo mv cv4pve-cli /usr/local/bin/

Configuration

Authentication Methods

Username/Password

cv4pve-cli --host=192.168.1.100 --username=root@pam --password=your_password [commands]

API Token (Recommended)

cv4pve-cli --host=192.168.1.100 --api-token=root@pam!token1=uuid-here [commands]

Password from File

# Store password in file
echo "your_password" > /etc/cv4pve/password
chmod 600 /etc/cv4pve/password

# Use password file
cv4pve-cli --host=192.168.1.100 --username=root@pam --password=file:/etc/cv4pve/password [commands]

Connection Options

Parameter	Description	Example
`--host`	Proxmox host(s) (multiple for HA)	`--host=pve1:8006,pve2:8006`
`--username`	Username@realm	`--username=root@pam`
`--password`	Password or file	`--password=secret` or `--password=file:/path`
`--api-token`	API token	`--api-token=user@realm!token=uuid`
`--validate-certificate`	Validate SSL certificate	`--validate-certificate`

Usage Examples

Interactive Shell

Interactive Mode

Start Interactive Shell

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret sh

Output:

Corsinvest CLI for Proxmox VE (Tuesday, December 11, 2025)
Type '<TAB>' for completion word
Type 'help', 'quit' to close the application.
Initialization metadata... 111ms

>>>

Help Command

>>> help

Commands:
  alias         Alias commands
  clear         Clear screen
  clear-cache   Clear API metadata cache
  clear-history Clear command history
  create        Create (POST) from resource
  delete        Delete (DELETE) from resource
  get           Get (GET) from resource
  help          Show help information
  history       Show history command
  ls            List child objects on <api_path>.
  quit          Close application
  set           Set (PUT) from resource
  usage         Usage resource

Interactive Commands

# Inside shell, explore the API
>>> get /nodes
>>> get /nodes/pve1/qemu
>>> get /cluster/resources type:vm
>>> ls /nodes/pve1
>>> usage /cluster/resources
>>> quit

Script File Execution

# Create script file
cat > commands.txt <<EOF
get /nodes
get /cluster/resources
ls /nodes/pve1
EOF

# Execute script
cv4pve-cli --host=pve.local --username=root@pam --password=secret sh --script=commands.txt

Alias Feature

The shell supports custom aliases for frequently used commands:

>>> alias

System aliases available:
  cluster-backup, cbck           - Cluster list vzdump backup schedule
  cluster-status, csts           - Cluster status
  cluster-top, ct, top           - Cluster top
  qemu-list, qlst                - Qemu list vm
  qemu-status, qsts              - Qemu current status vm
  qemu-start, qstr               - Qemu start vm
  qemu-stop, qsto                - Qemu stop vm
  ... and many more

API Operations

GET - Read Data

Get Version

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret get /version

Output:

┌─────────┬──────────┐
│ key     │ value    │
├─────────┼──────────┤
│ release │ 13       │
├─────────┼──────────┤
│ repoid  │ aee6f0ec │
├─────────┼──────────┤
│ version │ 5.4      │
└─────────┴──────────┘

Get Nodes Status

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret get /nodes

Output:

┌──────┬────────┬───────┬───────┬────────┬───────────┬───────────┬──────────────────────────┬─────────────────┐
│ node │ status │ cpu   │ level │ maxcpu │ maxmem    │ mem       │ ssl_fingerprint          │ uptime          │
├──────┼────────┼───────┼───────┼────────┼───────────┼───────────┼──────────────────────────┼─────────────────┤
│ pve1 │ online │ 4,58% │ c     │ 8      │ 31,39 GiB │ 17,03 GiB │ 81:94:9C:7A:20:38:44...  │ 12d 19h 12m 55s │
│ pve2 │ online │ 4,92% │ c     │ 8      │ 31,39 GiB │ 16,77 GiB │ 70:41:5B:47:21:F4:5C...  │ 13d 23h 34m 25s │
└──────┴────────┴───────┴───────┴────────┴───────────┴───────────┴──────────────────────────┴─────────────────┘

Get Cluster Resources (with filter)

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret get /cluster/resources type:node

Output:

┌───────────┬──────┬───────┬───────────┬────────┬────────────┬───────────┬───────────┬──────┬────────┐
│ id        │ type │ cpu   │ disk      │ maxcpu │ maxdisk    │ maxmem    │ mem       │ node │ status │
├───────────┼──────┼───────┼───────────┼────────┼────────────┼───────────┼───────────┼──────┼────────┤
│ node/pve1 │ node │ 6,47% │ 14,65 GiB │ 8      │ 27,19 GiB  │ 31,39 GiB │ 17,38 GiB │ pve1 │ online │
│ node/pve2 │ node │ 4,38% │ 12,45 GiB │ 8      │ 27,19 GiB  │ 31,39 GiB │ 16,75 GiB │ pve2 │ online │
└───────────┴──────┴───────┴───────────┴────────┴────────────┴───────────┴───────────┴──────┴────────┘

JSON Output

# Standard JSON
cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret get /version --output=json

Output:

{"repoid":"aee6f0ec","release":"13","version":"5.4","keyboard":"it"}

Pretty JSON Output

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret get /version --output=jsonpretty

Output:

{
  "repoid": "aee6f0ec",
  "release": "13",
  "version": "5.4",
  "keyboard": "it"
}

SET - Update Configuration

# Update VM memory
cv4pve-cli --host=pve.local --username=root@pam --password=secret set /nodes/pve1/qemu/100/config memory:4096

# Update VM description
cv4pve-cli --host=pve.local --username=root@pam --password=secret set /nodes/pve1/qemu/100/config description:"Updated by cv4pve-cli"

# Update multiple parameters
cv4pve-cli --host=pve.local --username=root@pam --password=secret set /nodes/pve1/qemu/100/config memory:4096 cores:2

CREATE - Create Resources

# Create snapshot
cv4pve-cli --host=pve.local --username=root@pam --password=secret create /nodes/pve1/qemu/100/snapshot snapname:backup-$(date +%Y%m%d)

# Create user
cv4pve-cli --host=pve.local --username=root@pam --password=secret create /access/users userid:testuser@pve password:secret

# Start VM
cv4pve-cli --host=pve.local --username=root@pam --password=secret create /nodes/pve1/qemu/100/status/start

DELETE - Remove Resources

# Delete snapshot
cv4pve-cli --host=pve.local --username=root@pam --password=secret delete /nodes/pve1/qemu/100/snapshot/backup-20250211

# Stop VM
cv4pve-cli --host=pve.local --username=root@pam --password=secret create /nodes/pve1/qemu/100/status/stop

Navigation & Documentation

LS - Browse API Like Filesystem

List Root

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret ls /

Output:

Dr---        access
Dr---        cluster
Dr---        nodes
Dr--c        pools
Dr--c        storage
-r---        version

List Nodes

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret ls /nodes

Output:

Dr---        pve1
Dr---        pve2
Dr---        pve3

List VMs on Node

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret ls /nodes/pve1/qemu

Output:

Dr---        100
Dr---        101
Dr---        102
Dr---        118

USAGE - API Documentation

Basic Usage Command

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret usage /cluster/resources

Output:

USAGE: get /cluster/resources [OPTIONS]

Verbose Usage (with parameters)

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret usage /cluster/resources --verbose

Output:

USAGE: get /cluster/resources [OPTIONS]

  Resources index (cluster wide).
┌───────┬─────────────────┬─────────────┐
│ param │ type            │ description │
├───────┼─────────────────┼─────────────┤
│ type  │ vm,storage,node │             │
└───────┴─────────────────┴─────────────┘

Usage with Returns Schema

cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret usage /cluster/resources --verbose --returns

Output:

USAGE: get /cluster/resources [OPTIONS]

  Resources index (cluster wide).
┌───────┬─────────────────┬─────────────┐
│ param │ type            │ description │
├───────┼─────────────────┼─────────────┤
│ type  │ vm,storage,node │             │
└───────┴─────────────────┴─────────────┘
RETURNS:
┌─────────┬────────────────────────┬──────────────────────────────────────────┐
│ param   │ type                   │ description                              │
├─────────┼────────────────────────┼──────────────────────────────────────────┤
│ cpu     │ number                 │ CPU utilization                          │
│ disk    │ string                 │ Used disk space in bytes                 │
│ maxcpu  │ number                 │ Number of available CPUs                 │
│ maxmem  │ integer                │ Number of available memory in bytes      │
│ mem     │ string                 │ Used memory in bytes                     │
│ node    │ string                 │ The cluster node name                    │
│ status  │ string                 │ Resource type dependent status           │
│ type    │ node,storage,pool,qemu │ Resource type                            │
└─────────┴────────────────────────┴──────────────────────────────────────────┘

Specific Command Usage

# Show all available commands for a resource
cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret usage /nodes/pve1/status

Output:

USAGE: get /nodes/pve1/status
USAGE: create /nodes/pve1/status command:<string>

# Show specific command documentation
cv4pve-cli --host=192.168.0.100 --username=root@pam --password=secret usage /nodes/pve1/status --command=create

Output:

USAGE: create /nodes/pve1/status command:<string>

Advanced Usage

Parameter Files

Create Parameter File

# /etc/cv4pve/production.conf
--host=pve-cluster.company.com
--api-token=automation@pve!production=uuid-here
--validate-certificate

Execute with Parameter File

cv4pve-cli @/etc/cv4pve/production.conf get /cluster/resources

Output Formats

# Text output (default)
cv4pve-cli --host=pve.local --username=root@pam --password=secret get /nodes

# JSON output
cv4pve-cli --host=pve.local --username=root@pam --password=secret get /nodes --output=json

# Pretty JSON
cv4pve-cli --host=pve.local --username=root@pam --password=secret get /nodes --output=jsonpretty

# Table output (for supported commands)
cv4pve-cli --host=pve.local --username=root@pam --password=secret get /cluster/resources --output=table

Command Reference

Global Options

cv4pve-cli [global-options] [command] [parameters]

Parameter	Description	Example
`--host`	Host name (host[:port])	`--host=pve.local:8006`
`--username`	Username@realm	`--username=root@pam`
`--password`	Password or file	`--password=secret`
`--api-token`	API token	`--api-token=user@realm!token=uuid`
`--validate-certificate`	Validate SSL certificate	`--validate-certificate`
`--version`	Show version	`--version`
`-?, -h, --help`	Show help	`--help`

Commands

API Commands

Command	Description	Syntax
`get`	GET from resource	`get <resource> [parameters]`
`set`	PUT to resource	`set <resource> [parameters]`
`create`	POST to resource	`create <resource> [parameters]`
`delete`	DELETE resource	`delete <resource> [parameters]`

Utility Commands

Command	Description	Syntax
`usage`	Show API usage	`usage <resource> [options]`
`ls`	List child objects	`ls <resource>`
`sh`	Interactive shell	`sh [--script=file] [--only-result]`

Shell Commands (inside interactive shell)

Command	Description
`clear`	Clear screen
`clear-cache`	Clear API metadata cache files
`clear-history`	Clear command history
`history`	Show command history
`alias`	Manage command aliases
`quit`	Exit interactive shell

Command Options

API Command Options

--output <format>     Output format: text, json, jsonpretty, table
--wait                Wait for task to finish
--verbose             Enable verbose output

Usage Command Options

--command, -c <type>  API command type: get, set, create, delete
--returns, -r         Include schema for returned data
--output <format>     Output format
--verbose             Enable verbose output

Shell Command Options

--script, -s <file>   Script file to execute
--only-result, -r     Only show result (no prompts)

Data Storage

The interactive shell stores data in the application data directory:

Platform	Location
Windows	`%APPDATA%\cv4pve-cli\`
Linux	`~/.config/cv4pve-cli/`
macOS	`~/.config/cv4pve-cli/`

Stored files:

api-cache_{host}_{version}.json - API metadata cache (per host/version)
history.txt - Command history (last 100 commands)
alias.txt - Custom command aliases

Use clear-cache and clear-history commands inside the shell to manage these files.

Documentation Links

Support

Professional support and consulting available through Corsinvest.

Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
.vscode		.vscode
src/Corsinvest.ProxmoxVE.Cli		src/Corsinvest.ProxmoxVE.Cli
.editorconfig		.editorconfig
.gitignore		.gitignore
3rd-party-licenses.md		3rd-party-licenses.md
Corsinvest.ProxmoxVE.Cli.sln		Corsinvest.ProxmoxVE.Cli.sln
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
LICENSE.md		LICENSE.md
README.MD		README.MD
icon.png		icon.png

License

Corsinvest/cv4pve-cli

Folders and files

Latest commit

History

Repository files navigation

cv4pve-cli

Quick Start

Features

Core Capabilities

Performance & Reliability

Flexible API Access

Advanced Features

Enterprise Features

Installation

Linux Installation

Windows Installation

Option 1: Winget (Recommended)

Option 2: Manual Installation

macOS Installation

Configuration

Authentication Methods

Username/Password

API Token (Recommended)

Password from File

Connection Options

Usage Examples

Interactive Shell

Start Interactive Shell

Help Command

Interactive Commands

Script File Execution

Alias Feature

API Operations

Get Version

Get Nodes Status

Get Cluster Resources (with filter)

JSON Output

Pretty JSON Output

Navigation & Documentation

List Root

List Nodes

List VMs on Node

Basic Usage Command

Verbose Usage (with parameters)

Usage with Returns Schema

Specific Command Usage

Advanced Usage

Create Parameter File

Execute with Parameter File

Command Reference

Global Options

Commands

API Commands

Utility Commands

Shell Commands (inside interactive shell)

Command Options

API Command Options

Usage Command Options

Shell Command Options

Data Storage

Documentation Links

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 23

Packages 0

Uh oh!

Languages

Packages