proxmox-cli 0.4.2
A command-line interface for Proxmox Virtual Environment
License: MIT
Requires Python: >=3.8
Keywords: proxmox, cli, virtualization, api, management

# Proxmox CLI

[![PyPI version](https://badge.fury.io/py/proxmox-cli.svg)](https://badge.fury.io/py/proxmox-cli)
[![Python versions](https://img.shields.io/pypi/pyversions/proxmox-cli.svg)](https://pypi.org/project/proxmox-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow.svg)](https://buymeacoffee.com/rwgb)

## 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)

```bash
pip install proxmox-cli
```

### From Source

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

### Development Installation

```bash
pip install -e ".[dev]"
```

## Quick Start

### Basic Usage

```bash
# 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`:

```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

```bash
# 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

```bash
# 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

```bash
# List all users
proxmox-cli user list

# Create a new user
proxmox-cli user create developer@pve \
  --password "SecurePass123" \
  --email "dev@example.com" \
  --groups "developers"

# Update user
proxmox-cli user update developer@pve --email "newemail@example.com"

# Delete user
proxmox-cli user delete developer@pve
```

### Role & Permission Management

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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`:

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

## License

MIT