cv4pve-cli

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

Command Line Interface for Proxmox VE (Made in Italy)

cv4pve-cli is to Proxmox VE what kubectl is to Kubernetes — a remote-first CLI with context switching, direct API access, and aliases for common operations. Think of it as pvesh, but running from your workstation, supporting multiple clusters, and with tab completion that queries the live API.

---

Quick Start

# 1. Add a context (connection profile)
cv4pve-cli config add homelab --host 192.168.1.100 --username root@pam --password secret

# 2. Use it
cv4pve-cli config use homelab

# 3. Run commands
cv4pve-cli api get /nodes
cv4pve-cli top

---

Installation

---

Features

• Self-contained binary — no runtime to install, copy and run
• Cross-platform — Windows, Linux, macOS
• Multiple clusters — save and switch between connection profiles (contexts)
• Direct API access — full Proxmox VE REST API via api get/set/create/delete
• 300+ built-in aliases — shortcuts for common operations (start, stop, snapshot, migrate, …)
• Guest auto-resolution — use --guest instead of typing node, vmtype and vmid
• Async task support — add --wait to any command, or use task log --follow to tail a running task
• Tab completion — bash, zsh and PowerShell, queries the live API
• API schema cached locally — refreshed automatically on PVE upgrade
• Scriptable — semantic exit codes, errors on stderr

---

Configuration

All configuration is managed through the config subcommand. Contexts are connection profiles — each stores a host, credentials, and port.

File locations

Files are in YAML format and can be edited directly.

---

API Commands

cv4pve-cli api get     [--key value ...]
cv4pve-cli api set     [--key value ...]
cv4pve-cli api create  [--key value ...]
cv4pve-cli api delete 
cv4pve-cli api ls     
cv4pve-cli api usage   [method] [--returns] [--output ]

cv4pve-cli api get /cluster/resources --type vm
cv4pve-cli api set /nodes/pve1/qemu/100/config --memory 4096 --cores 2
cv4pve-cli api create /nodes/pve1/qemu/100/snapshot --snapname before-update
cv4pve-cli api delete /nodes/pve1/qemu/100/snapshot/before-update

Output formats

--output / -o: text (default), json, jsonpretty, html, markdown

cv4pve-cli api get /nodes --output json
cv4pve-cli api usage /nodes/{node}/qemu/{vmid}/config get --returns --output json

---

Aliases

Aliases are shortcuts for API commands. Placeholders like {node}, {vmid} are filled positionally at runtime.

Built-in aliases

300+ read-only aliases are available out of the box — see the full alias reference or run cv4pve-cli alias list. A few examples:

Aliases prefixed with guest work for both VMs and containers — {vmtype} is resolved automatically:

The same operation is available at three levels — guest (both VM and CT), vm (qemu only), ct (lxc only):

cv4pve-cli create guest snapshot --guest myvm  snap1 "before update"  # VM or CT — by name
cv4pve-cli create guest snapshot --guest 100   snap1 "before update"  # VM or CT — by id
cv4pve-cli create vm snapshot pve1 100 snap1 "before update"           # VM only
cv4pve-cli create ct snapshot pve1 200 snap1 "before update"           # CT only

cv4pve-cli alias list
cv4pve-cli alias list --verbose        # includes command and placeholder args
cv4pve-cli alias list --search snap    # filter by keyword

Guest auto-resolution (--guest)

Aliases whose path targets a specific guest accept --guest . The CLI resolves node, vmid and vmtype automatically from the cluster.

# Without --guest (explicit)
cv4pve-cli do start vm pve1 100

# With --guest (auto-resolve)
cv4pve-cli do start vm --guest 100
cv4pve-cli do start vm --guest myvm
cv4pve-cli get ct status --guest myct
cv4pve-cli create guest snapshot --guest myvm snap1 "before update"

Tab completion on --guest shows all VM and container names and IDs live from the cluster.

To check if an alias supports --guest, run it with --help — the description will contain:

Tip: use --guest  to resolve guest info automatically

User aliases

# Add
cv4pve-cli alias add vm-net \
    --command "get /nodes/{node}/qemu/{vmid}/config" \
    --description "Show VM network config"

# Use
cv4pve-cli vm-net pve1 100

# Remove
cv4pve-cli alias remove vm-net

Built-in aliases cannot be modified or removed.

---

Tab Completion

Tab completion is registered automatically on first run. Open a new terminal to activate it, or reload your profile:

To force re-registration: cv4pve-cli completion reset

What completes

---

Documentation

• Command reference — core commands (config, api, alias, completion), global options, guest auto-resolution
• Alias reference — the full list of 300+ built-in aliases
• AI coding assistants — running cv4pve-cli inside Claude Code, Codex and similar sandboxed agents

---

Using with AI coding assistants

Tips for running cv4pve-cli inside Claude Code, Codex and similar sandboxed agents (self-signed certs, sandbox permissions, SKILL.md template): see docs/AI-AGENTS.md.

---

Support

Professional support available through Corsinvest.

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

Copyright © Corsinvest Srl