---

name: pve_cli description: Interact with Proxmox VE via CLI API wrapper deployed on the PVE host. Manage VMs, containers, cluster status, and execute CLI commands through REST endpoints.

Proxmox CLI API Skill

Interact with Proxmox VE using a RESTful API wrapper that translates HTTP requests to CLI commands.

Prerequisites

The PVE CLI API must be running on the Proxmox host. See Setup below for installation instructions.

Setup (Deploy API Server)

1. SSH into your Proxmox host

ssh root@YOUR_PVE_IP

2. Install Python3 and Flask

apt-get update
apt-get install -y python3-flask

3. Create the API server

Create /opt/pve-cli-api/server.py with the following content:

#!/usr/bin/env python3
"""Proxmox CLI API Wrapper - RESTful API for PVE CLI commands"""

import os
import re
import json
import subprocess
from datetime import datetime
from flask import Flask, request, jsonify

app = Flask(__name__)

CONFIG = {
    'PORT': int(os.environ.get('PORT', 3000)),
    'API_KEY': os.environ.get('PVE_API_KEY', 'pve-cli-api-key'),
    'ALLOWED_COMMANDS': ['qm', 'pct', 'pvesh', 'pvecm', 'pveperf', 'pveversion', 
                         'vzdump', 'qmrestore', 'lvcreate', 'lvremove', 'lvs', 'vgs', 'pvs']
}

def run_command(command, timeout=30):
    """Execute CLI command safely"""
    cmd_base = command.split()[0]
    if cmd_base not in CONFIG['ALLOWED_COMMANDS']:
        return {'success': False, 'error': f"Command '{cmd_base}' not allowed"}
    
    try:
        result = subprocess.run(
            command, shell=True, capture_output=True, text=True, timeout=timeout
        )
        return {
            'success': result.returncode == 0,
            'output': result.stdout or result.stderr,
            'returncode': result.returncode
        }
    except Exception as e:
        return {'success': False, 'error': str(e)}

# Authentication
@app.before_request
def check_auth():
    if request.path == '/health':
        return None
    api_key = request.headers.get('X-API-Key') or request.args.get('api_key')
    if api_key != CONFIG['API_KEY']:
        return jsonify({'error': 'Unauthorized'}), 401

@app.route('/health')
def health():
    return jsonify({'status': 'ok', 'timestamp': datetime.now().isoformat()})

@app.route('/vms')
def list_vms():
    result = run_command('qm list')
    return jsonify(result)

@app.route('/vms/<int:vmid>/start', methods=['POST'])
def start_vm(vmid):
    return jsonify(run_command(f'qm start {vmid}'))

@app.route('/vms/<int:vmid>/stop', methods=['POST'])
def stop_vm(vmid):
    return jsonify(run_command(f'qm stop {vmid}'))

@app.route('/containers')
def list_containers():
    return jsonify(run_command('pct list'))

@app.route('/containers/<int:vmid>/start', methods=['POST'])
def start_container(vmid):
    return jsonify(run_command(f'pct start {vmid}'))

@app.route('/containers/<int:vmid>/stop', methods=['POST'])
def stop_container(vmid):
    return jsonify(run_command(f'pct stop {vmid}'))

@app.route('/containers/<int:vmid>/exec', methods=['POST'])
def exec_container(vmid):
    data = request.get_json()
    command = data.get('command')
    if not command:
        return jsonify({'error': 'Command required'}), 400
    return jsonify(run_command(f'pct exec {vmid} -- {command}'))

@app.route('/cluster/status')
def cluster_status():
    return jsonify(run_command('pvecm status'))

@app.route('/version')
def version():
    return jsonify(run_command('pveversion -v'))

@app.route('/exec', methods=['POST'])
def exec_command():
    data = request.get_json()
    command = data.get('command')
    if not command:
        return jsonify({'error': 'Command required'}), 400
    return jsonify(run_command(command))

if __name__ == '__main__':
    print(f"PVE CLI API running on port {CONFIG['PORT']}")
    app.run(host='0.0.0.0', port=CONFIG['PORT'])

4. Start the server

cd /opt/pve-cli-api
python3 server.py

Or run in background:

nohup python3 server.py > /var/log/pve-cli-api.log 2>&1 &

5. Verify it's working

curl http://localhost:3000/health

Should return: {"status": "ok"}

Configuration

• Default Port: 3000 (set via PORT env var)
• Default API Key: pve-cli-api-key (set via PVE_API_KEY env var)
• URL: http://YOUR_PVE_IP:3000

Usage

Once the API server is running, use this skill to interact with it:

export PVE_CLI_API_URL="http://192.168.68.58:3000"
export PVE_CLI_API_KEY="pve-cli-api-key"

API Endpoints

VMs (QEMU/KVM)

List all VMs:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms

Get VM config:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/config

Get VM status:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/status

Start VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/start

Stop VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/stop

Shutdown VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" "http://192.168.68.58:3000/vms/100/shutdown?timeout=180"

Reset VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/reset

Reboot VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/reboot

Suspend VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/suspend

Resume VM:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/vms/100/resume

Containers (LXC)

List all containers:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/containers

Get container config:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/containers/100/config

Start container:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/containers/100/start

Stop container:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/containers/100/stop

Shutdown container:

curl -X POST -H "X-API-Key: pve-cli-api-key" "http://192.168.68.58:3000/containers/100/shutdown?timeout=60"

Reboot container:

curl -X POST -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/containers/100/reboot

Execute command inside container:

curl -X POST -H "X-API-Key: pve-cli-api-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /"}' \
  http://192.168.68.58:3000/containers/100/exec

Enter container (test connection):

curl -X POST -H "X-API-Key: pve-cli-api-key" \
  http://192.168.68.58:3000/containers/100/enter

Cluster

Get cluster status:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/cluster/status

Get cluster nodes:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/cluster/nodes

Node Information

Get node performance:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/nodes/pve/perf

Get PVE version:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/version

Storage

List LVM volumes:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/storage/lvm

List volume groups:

curl -H "X-API-Key: pve-cli-api-key" http://192.168.68.58:3000/storage/vgs

Raw Commands

Execute raw CLI command:

curl -X POST -H "X-API-Key: pve-cli-api-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "qm list"}' \
  http://192.168.68.58:3000/exec

Allowed Commands

Only these CLI commands are permitted via the API:

• qm - QEMU/KVM VM management
• pct - LXC container management
• pvesh - Proxmox VE shell
• pvecm - Cluster management
• pveperf - Performance test
• pveversion - Version info
• vzdump - Backup utility
• qmrestore - Restore utility
• lvcreate, lvremove, lvs - LVM commands
• vgs, pvs - Volume group commands

Response Format

All responses are JSON:

{
  "success": true|false,
  "output": "command output as string",
  "command": "the executed command",
  "data": { ... },
  "error": "error message if failed"
}

Error Handling

• 401 Unauthorized - Invalid or missing API key
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Examples

List all VMs and their status

#!/bin/bash
API_URL="http://192.168.68.58:3000"
API_KEY="pve-cli-api-key"

curl -s -H "X-API-Key: $API_KEY" "$API_URL/vms" | jq '.data[] | {vmid, name, status}'

Start all stopped VMs

#!/bin/bash
API_URL="http://192.168.68.58:3000"
API_KEY="pve-cli-api-key"

vms=$(curl -s -H "X-API-Key: $API_KEY" "$API_URL/vms" | jq -r '.data[] | select(.status == "stopped") | .vmid')

for vmid in $vms; do
    echo "Starting VM $vmid..."
    curl -s -X POST -H "X-API-Key: $API_KEY" "$API_URL/vms/$vmid/start"
done

Check cluster health

#!/bin/bash
API_URL="http://192.168.68.58:3000"
API_KEY="pve-cli-api-key"

echo "Cluster Status:"
curl -s -H "X-API-Key: $API_KEY" "$API_URL/cluster/status" | jq '.data'

echo -e "\nNode Performance:"
curl -s -H "X-API-Key: $API_KEY" "$API_URL/nodes/pve/perf" | jq '.data'

---

RESTful API for Proxmox VE CLI - bridging HTTP and the command line