proxmox-cli 0.4.2

A command-line interface for Proxmox Virtual Environment

Proxmox CLI

A powerful command-line interface tool for managing Proxmox Virtual Environment with support for VMs, containers, users, groups, roles, and permissions.

Support

If you find this project helpful, consider supporting its development:

Features

Infrastructure Management

• 🖥️ Virtual Machines - Create, start, stop, and manage VMs
• 📦 LXC Containers - Full container lifecycle management
• 🔧 Nodes - Monitor and manage cluster nodes
• 💾 Storage - Storage configuration and monitoring
• 🗂️ Resource Pools - Organize and manage resource pools

Identity & Access Management (IAM)

• 👤 Users - Create, update, and manage users
• 👥 Groups - Organize users into groups
• 🔐 Roles - Define custom roles with specific privileges
• 🔑 API Tokens - Generate and manage API tokens
• 🛡️ ACLs - Granular permission management

Output & Configuration

• 📊 Multiple Output Formats - JSON (default), Table, YAML, Plain text
• ⚙️ Configuration File - Store credentials and preferences
• 🔒 SSL Control - Flexible SSL verification options
• 🚀 Fast & Efficient - Optimized for automation and scripting

Installation

From PyPI (Recommended)

pip install proxmox-cli

From Source

git clone https://github.com/rwgb/proxmox.cli.git
cd proxmox.cli
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Basic Usage

# List all VMs (JSON output by default)
proxmox-cli vm list

# List containers in table format
proxmox-cli --output table container list

# List users
proxmox-cli user list

# Show help
proxmox-cli --help

Configuration

Create a configuration file at ~/.config/proxmox-cli/config.yaml:

proxmox:
  host: proxmox.example.com
  user: root@pam
  password: your-password
  # Or use API token
  # token_name: mytoken
  # token_value: your-token-value
  verify_ssl: false

output:
  format: json  # or table, yaml, plain

Usage Examples

Virtual Machines

# List all VMs
proxmox-cli vm list

# List VMs on specific node
proxmox-cli vm list --node pve1

# Start a VM
proxmox-cli vm start 100 --node pve1

# Stop a VM
proxmox-cli vm stop 100 --node pve1

# Get VM status
proxmox-cli vm status 100 --node pve1

Containers

# List all containers
proxmox-cli container list

# Start a container
proxmox-cli container start 108 --node pve1

# Stop a container
proxmox-cli container stop 108 --node pve1

# List available templates on storage
proxmox-cli container templates --node pve1

# List templates available for download
proxmox-cli container available-templates --node pve1

# Download a template
proxmox-cli container download-template \
  ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --node pve1 \
  --storage local

# Create container from template
proxmox-cli container create 200 \
  local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --node pve1 \
  --hostname web-server \
  --password "SecurePass123" \
  --memory 1024 \
  --cores 2 \
  --rootfs-size 10 \
  --net0 "name=eth0,bridge=vmbr0,ip=dhcp"

User Management

# List all users
proxmox-cli user list

# Create a new user
proxmox-cli user create developer@pve \
  --password "SecurePass123" \
  --email "[e-mail]" \
  --groups "developers"

# Update user
proxmox-cli user update developer@pve --email "[e-mail]"

# Delete user
proxmox-cli user delete developer@pve

Role & Permission Management

# List all roles
proxmox-cli role list

# Create custom role
proxmox-cli role create CustomRole \
  --privs "VM.Allocate,VM.Audit,VM.PowerMgmt"

# Grant permissions
proxmox-cli acl add \
  --path "/" \
  --roles "PVEAdmin" \
  --users "admin@pve"

API Tokens

# List tokens for a user
proxmox-cli token list user@pve

# Create API token
proxmox-cli token create user@pve mytoken \
  --comment "Automation token" \
  --no-privsep

# Delete token
proxmox-cli token delete user@pve mytoken

Resource Pool Management

# List all resource pools
proxmox-cli pool list

# Create a new resource pool
proxmox-cli pool create production \
  --comment "Production environment resources"

# Show pool details and members
proxmox-cli pool show production

# Add VMs to a pool
proxmox-cli pool add-member production \
  --vm 100 --vm 101 --vm 102

# Add storage to a pool
proxmox-cli pool add-member production \
  --storage local-lvm

# Remove members from a pool
proxmox-cli pool remove-member production \
  --vm 100

# Update pool information
proxmox-cli pool update production \
  --comment "Updated production pool"

# Delete a pool
proxmox-cli pool delete production

Storage Management

# List all storage
proxmox-cli storage list

# Create a directory storage for backups
proxmox-cli storage create backup-storage \
  --path /mnt/backups \
  --content backup

# Create storage for ISOs and templates
proxmox-cli storage create iso-storage \
  --path /mnt/isos \
  --content "iso,vztmpl"

# Create VM disk storage with shared flag
proxmox-cli storage create vm-storage \
  --path /mnt/vms \
  --content "images,rootdir" \
  --shared

# Create snippets storage for custom scripts
proxmox-cli storage create snippets-storage \
  --path /mnt/snippets \
  --content snippets

# Create storage with backup retention
proxmox-cli storage create backup-storage \
  --path /mnt/backups \
  --content backup \
  --maxfiles 10 \
  --prune-backups "keep-last=3,keep-weekly=2"

# Create storage on specific nodes
proxmox-cli storage create local-backup \
  --path /mnt/local-backup \
  --content backup \
  --nodes "node1,node2"

Content Types:

• images - VM disk images (qcow2, raw, vmdk)
• rootdir - Container file systems
• vztmpl - Container templates
• backup - Backup files
• iso - ISO images
• snippets - Custom scripts and configuration snippets

Output Formats

The CLI supports multiple output formats:

# JSON (default) - Perfect for scripting
proxmox-cli vm list

# Table - Human-readable
proxmox-cli --output table vm list

# YAML - Configuration-friendly
proxmox-cli --output yaml user list

# Plain text - Minimal
proxmox-cli --output plain node list

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8 src/
black src/

Configuration

Create a configuration file at ~/.config/proxmox-cli/config.yaml:

proxmox:
  host: your-proxmox-host
  user: root@pam
  verify_ssl: false

License

MIT