proxcli 0.1.0__py3-none-any.whl

proxcli-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: proxcli
+Version: 0.1.0
+Summary: A CLI tool to interact with Proxmox VE nodes and clusters via the REST API
+Author-email: Xabi Ezpeleta <xezpeleta@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# proxmox
+
+A CLI tool to interact with [Proxmox VE](https://www.proxmox.com/) nodes and clusters via the REST API.
+
+Designed to be easy for humans (table output, ergonomic flags) and AI agents (structured JSON, strict exit codes, `--dry-run`). Provides a higher-level abstraction over the raw Proxmox API.
+
+## Installation
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# From PyPI
+uv tool install proxmox
+
+# From Git
+uv tool install git+https://github.com/xezpeleta/proxmox-cli.git
+
+# From local checkout
+uv tool install .
+```
+
+## Quickstart
+
+```bash
+# Authenticate (password-based)
+proxmox auth login --url https://192.168.1.10:8006 --username root@pam --password your_password
+
+# Or with an API token
+proxmox auth login --url https://192.168.1.10:8006 --username root@pam --api-token 'root@pam!my-token=deadbeef...'
+
+# Check auth status
+proxmox auth status
+
+# List VMs
+proxmox vm list
+
+# Show a specific VM
+proxmox vm show 100
+
+# Create a VM
+proxmox vm create --node pve01 --vmid 110 --memory 2048 --cores 2 --name webserver
+
+# Start / stop / reboot
+proxmox vm start 110
+proxmox vm stop 110
+proxmox vm reboot 110
+
+# Delete (with purge)
+proxmox vm delete 110 --purge
+```
+
+## Authentication
+
+Credentials are stored in `~/.config/proxmox-cli/credentials.json` with restrictive permissions (`0600`).
+
+### Auth methods
+
+| Method | Command |
+|---|---|
+| Password | `proxmox auth login --url ... --username ... --password ...` |
+| Password (stdin) | `echo "$PASS" \| proxmox auth login --url ... --username ... --password-stdin` |
+| API token | `proxmox auth login --url ... --username ... --api-token 'user!tokenid=secret'` |
+
+### Override credentials per command
+
+```bash
+proxmox --url https://other-pve:8006 --username admin@pam --password pass123 vm list
+```
+
+### Environment variable
+
+```bash
+export PROXMOX_PASSWORD=mysecret
+proxmox vm list --username root@pam --url https://pve:8006
+```
+
+### Self-signed certificates
+
+```bash
+proxmox --insecure vm list
+```
+
+## Command Reference
+
+### Global flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--url` | (config file) | Proxmox API URL |
+| `--username` | (config file) | Username |
+| `--password` | — | Password |
+| `--password-stdin` | — | Read password from stdin |
+| `--api-token` | — | API token (`user!tokenid=secret`) |
+| `--output` | `json` | Output format: `json`, `table`, `yaml` |
+| `--dry-run` | off | Print the API request without executing |
+| `--insecure` | off | Skip TLS verification |
+| `--timeout` | `30` | Request timeout in seconds |
+| `--verbose` | off | Debug output to stderr |
+| `--version` | — | Show version |
+
+### Auth
+
+```bash
+proxmox auth login   # Save credentials
+proxmox auth status  # Show current auth context
+proxmox auth clear   # Remove saved credentials
+```
+
+### VM (QEMU)
+
+```bash
+proxmox vm list [--node <node>]
+proxmox vm show <vmid> [--node <node>]
+proxmox vm create --node <node> --vmid <id> --memory <mb> [--cores <n>] [--name <name>] [--storage <name>] [--net <config>]
+proxmox vm start <vmid> [--node <node>]
+proxmox vm stop <vmid> [--node <node>]
+proxmox vm reboot <vmid> [--node <node>]
+proxmox vm suspend <vmid> [--node <node>]
+proxmox vm resume <vmid> [--node <node>]
+proxmox vm delete <vmid> [--node <node>] [--force] [--purge]
+```
+
+### Container (LXC)
+
+```bash
+proxmox container list [--node <node>]
+proxmox container show <vmid> [--node <node>]
+proxmox container create --node <node> --vmid <id> --ostemplate <tmpl> [--memory <mb>] [--cores <n>] [--storage <name>]
+proxmox container start <vmid> [--node <node>]
+proxmox container stop <vmid> [--node <node>]
+proxmox container delete <vmid> [--node <node>] [--force] [--purge]
+```
+
+### Node
+
+```bash
+proxmox node list
+proxmox node show <node>
+proxmox node status [<node>]
+```
+
+### Storage
+
+```bash
+proxmox storage list [--node <node>]
+proxmox storage show <storage>
+proxmox storage content <storage> [--node <node>]
+```
+
+### Cluster
+
+```bash
+proxmox cluster status
+```
+
+### Task
+
+```bash
+proxmox task list [--node <node>]
+proxmox task show <upid>
+```
+
+## Output Formats
+
+### JSON (default)
+
+```json
+[
+  {
+    "vmid": 100,
+    "name": "webserver",
+    "status": "running",
+    "cpu": 0.05,
+    "mem": 2048
+  }
+]
+```
+
+### Table
+
+```
+┌──────┬───────────┬─────────┬───────┬──────┐
+│ vmid │ name      │ status  │ cpu   │ mem  │
+├──────┼───────────┼─────────┼───────┼──────┤
+│ 100  │ webserver │ running │ 0.05  │ 2048 │
+└──────┴───────────┴─────────┴───────┴──────┘
+```
+
+### YAML
+
+```yaml
+- vmid: 100
+  name: webserver
+  status: running
+  cpu: 0.05
+  mem: 2048
+```
+
+## AI Agent Usage
+
+Every command emits valid JSON by default (stdout) and diagnostic messages on stderr. Exit codes follow Unix conventions.
+
+```bash
+# Dry-run to preview the API call
+proxmox --dry-run vm create --node pve01 --vmid 110 --memory 1024
+
+# Machine-parseable JSON output
+proxmox --output json vm list | jq '.[] | {vmid, status}'
+
+# Check exit code
+proxmox vm show 999 || echo "VM not found"
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/xezpeleta/proxmox-cli.git
+cd proxmox-cli
+
+# Install dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=proxmox --cov-report=term-missing
+
+# Lint
+uv run ruff check .
+
+# Build
+uv build
+```
+
+## License
+
+MIT

proxcli-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+proxmox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/cli/auth.py,sha256=9JAI4yW3THC0mWDgCjjWqSvcOTF07OsTuFdVDK7Zi7U,4779
+proxmox/cli/cluster.py,sha256=zZOFYh9Sa9bO3UBP-qEXyJloan7tHmWPn2lRXgk6TRI,732
+proxmox/cli/container.py,sha256=EpypF2MbqhpJX1zdtXYV6PrRjHwtxGV4sTWspruAA3k,6402
+proxmox/cli/main.py,sha256=wyKx3cc-vGhoV5CrLedWvuVHaNDRwN1F3wUOi4QFIHc,8238
+proxmox/cli/node.py,sha256=mKGShu89TQjSy8cH3ql901gQpZARLqVklIvNTfELlDs,2001
+proxmox/cli/storage.py,sha256=n-TT61nqxOQhic1rnweXxJhmU5Ivth1fb281r49cZzk,2435
+proxmox/cli/tasks.py,sha256=yGPGmm6GXuSiNBf1MH9KqOXpndOcVvnESqn-ebOR6wM,2353
+proxmox/cli/vm.py,sha256=aj9OKBLrW0f4s6ZeRMZxpkSxF2ANbubT2e73t2QdlZ4,8743
+proxmox/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/client/auth.py,sha256=FFxPlE3dW-jusHxkZDLqP3Fu-53CiLJ0uW0b6H4_KZk,3797
+proxmox/client/client.py,sha256=1-BkObMG0W0SJoJXLZ3jeyJOCQSjUH7orB-epuf-7fI,7067
+proxmox/client/exceptions.py,sha256=LbhE_ZqMx9ESFi9Pwyarba9rceE2GaOdCH79HqSuOJk,1175
+proxmox/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/config/config.py,sha256=Jv1OlGDh5ExYchethHTRQV3g-OGqldfGXNeKGkKUBbY,3205
+proxmox/config/models.py,sha256=XgAGFabGBT1WkhhROYO-ZCitovAJ84vK707wNe33wz0,2118
+proxmox/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/output/formatter.py,sha256=l8DI4GvtWHxD-GVqpQdZ39JGA_YqFxGVgsEI2ZBJJvo,757
+proxmox/output/json_fmt.py,sha256=ltylV9vfs_-yu_QTW99fK68-NGSBqyFfnc7x-dTDTCo,277
+proxmox/output/table_fmt.py,sha256=S9eGQwGogJm9F1HQHe-fkmCApSSu9_QZxVNAY3p6XYQ,1844
+proxmox/output/yaml_fmt.py,sha256=lGS1HRtBYeibK0tRsLbd5jnia-Hhlv48SpWbEGpE6oo,260
+proxmox/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxmox/utils/helpers.py,sha256=8mASmzgVozEQ_RA_V9db4V66-gT87wQi8lGlF658jVk,383
+proxmox/utils/logging.py,sha256=Grld09w3zdsByacCOl_u1RvB07_bF-QMdG7KhyK3Zl8,329
+proxcli-0.1.0.dist-info/METADATA,sha256=5cn7rVXcnpVUIapx3ceOnZjQP7QgudVCXtLWdQYFExw,6415
+proxcli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+proxcli-0.1.0.dist-info/entry_points.txt,sha256=v5r_PXC8CApMzQCZqgX80CeGgQdIDZv32hvpBNL2mOc,50
+proxcli-0.1.0.dist-info/RECORD,,

proxcli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

proxcli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proxmox = proxmox.cli.main:main

proxmox/cli/auth.py

@@ -0,0 +1,130 @@
+"""`proxmox auth` subcommand — manage credentials."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from proxmox.client.auth import AuthManager
+from proxmox.client.client import ProxmoxClient
+from proxmox.config.config import ConfigLoader
+from proxmox.config.models import AuthMethod, Credentials
+from proxmox.utils.logging import log_error, log_info
+
+
+def register_auth_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox auth` subcommand tree."""
+    auth_parser = subparsers.add_parser("auth", help="Manage Proxmox credentials")
+    auth_sub = auth_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- auth login ---
+    login = auth_sub.add_parser("login", help="Authenticate and save credentials")
+    login.add_argument("--url", required=True, help="Proxmox API URL")
+    login.add_argument("--username", required=True, help="Username (e.g. root@pam)")
+    login.add_argument("--password", help="Password")
+    login.add_argument("--password-stdin", action="store_true", help="Read password from stdin")
+    login.add_argument("--api-token", help="API token (user!tokenid=secret)")
+    login.add_argument(
+        "--insecure", action="store_true", help="Skip TLS verification (save preference)"
+    )
+    login.set_defaults(func=_auth_login)
+
+    # --- auth status ---
+    status = auth_sub.add_parser("status", help="Show current authentication status")
+    status.set_defaults(func=_auth_status)
+
+    # --- auth clear ---
+    clear = auth_sub.add_parser("clear", help="Remove saved credentials")
+    clear.set_defaults(func=_auth_clear)
+
+
+def _auth_login(args: argparse.Namespace, client: ProxmoxClient | None = None) -> dict | None:
+    """Authenticate and persist credentials."""
+    loader = ConfigLoader()
+    url = args.url.rstrip("/")
+
+    # Determine password
+    password = args.password
+    if args.password_stdin:
+        password = sys.stdin.readline().rstrip("\n")
+
+    verify_tls = not args.insecure
+
+    # Validate credentials
+    if args.api_token:
+        parts = args.api_token.split("=", 1)
+        if len(parts) != 2:
+            log_error("Invalid --api-token format. Expected: user!tokenid=secret")
+            sys.exit(1)
+        user_token, secret = parts
+        if "!" in user_token:
+            user, token_id = user_token.split("!", 1)
+        else:
+            user = args.username
+            token_id = user_token
+        creds = Credentials(
+            url=url,
+            username=user,
+            auth_method=AuthMethod.API_TOKEN,
+            api_token_id=token_id,
+            api_token_secret=secret,
+            verify_tls=verify_tls,
+        )
+        # Quick validation: attempt a version check
+        auth_mgr = AuthManager()
+        auth_mgr.set_api_token(user, token_id, secret)
+        test_client = ProxmoxClient(url, auth_mgr, verify_tls=verify_tls, timeout=10)
+        try:
+            test_client.get("/version")
+        except Exception as exc:
+            log_error(f"Failed to validate token: {exc}")
+            sys.exit(1)
+    elif password:
+        creds = Credentials(
+            url=url,
+            username=args.username,
+            auth_method=AuthMethod.PASSWORD,
+            password=password,
+            verify_tls=verify_tls,
+        )
+        # Quick validation: attempt a version check
+        auth_mgr = AuthManager()
+        auth_mgr.authenticate_password(url, args.username, password, verify=verify_tls)
+        test_client = ProxmoxClient(url, auth_mgr, verify_tls=verify_tls, timeout=10)
+        try:
+            test_client.get("/version")
+        except Exception as exc:
+            log_error(f"Failed to validate credentials: {exc}")
+            sys.exit(1)
+    else:
+        log_error("Either --password, --password-stdin, or --api-token is required")
+        sys.exit(1)
+
+    path = loader.save(creds)
+    log_info(f"Credentials saved to {path}")
+    return {"status": "authenticated", "url": url, "user": creds.username}
+
+
+def _auth_status(args: argparse.Namespace, client: ProxmoxClient | None = None) -> dict:
+    """Display current authentication status."""
+    loader = ConfigLoader()
+    creds = loader.load_or_none()
+    if creds is None:
+        return {"status": "not authenticated"}
+
+    return {
+        "status": "authenticated",
+        "url": creds.url,
+        "username": creds.username,
+        "auth_method": creds.auth_method.value,
+        "verify_tls": creds.verify_tls,
+        "config_file": str(loader._user_dir / "credentials.json"),
+    }
+
+
+def _auth_clear(args: argparse.Namespace, client: ProxmoxClient | None = None) -> dict:
+    """Remove saved credentials."""
+    loader = ConfigLoader()
+    loader.clear()
+    log_info("Credentials cleared.")
+    return {"status": "cleared"}

proxmox/cli/cluster.py

@@ -0,0 +1,21 @@
+"""`proxmox cluster` subcommand — cluster management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+
+
+def register_cluster_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox cluster` subcommand tree."""
+    cl_parser = subparsers.add_parser("cluster", help="Manage Proxmox cluster")
+    cl_sub = cl_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- cluster status ---
+    cl_status = cl_sub.add_parser("status", help="Show cluster status")
+    cl_status.set_defaults(func=_cl_status)
+
+
+def _cl_status(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/cluster/status")

proxmox/cli/container.py

@@ -0,0 +1,157 @@
+"""`proxmox container` subcommand — LXC container management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+from proxmox.utils.helpers import vmid_type
+
+
+def register_container_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox container` subcommand tree."""
+    ct_parser = subparsers.add_parser("container", help="Manage LXC containers")
+    ct_sub = ct_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- container list ---
+    ct_list = ct_sub.add_parser("list", help="List containers")
+    ct_list.add_argument("--node", help="Filter by node name")
+    ct_list.set_defaults(func=_ct_list)
+
+    # --- container show ---
+    ct_show = ct_sub.add_parser("show", help="Show container details")
+    ct_show.add_argument("vmid", type=vmid_type, help="Container ID")
+    ct_show.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ct_show.set_defaults(func=_ct_show)
+
+    # --- container create ---
+    ct_create = ct_sub.add_parser("create", help="Create a new container")
+    ct_create.add_argument("--node", required=True, help="Target node")
+    ct_create.add_argument("--vmid", type=vmid_type, required=True, help="Container ID")
+    ct_create.add_argument("--ostemplate", required=True, help="OS template")
+    ct_create.add_argument("--storage", default=None, help="Storage for the container")
+    ct_create.add_argument("--memory", type=int, default=512, help="Memory in MB")
+    ct_create.add_argument("--cores", type=int, default=1, help="CPU cores")
+    ct_create.add_argument("--net", default=None, help="Network config (e.g. name=eth0,bridge=vmbr0,ip=dhcp)")
+    ct_create.add_argument("--password", default=None, help="Root password")
+    ct_create.set_defaults(func=_ct_create)
+
+    # --- container start ---
+    ct_start = ct_sub.add_parser("start", help="Start a container")
+    ct_start.add_argument("vmid", type=vmid_type, help="Container ID")
+    ct_start.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ct_start.set_defaults(func=_ct_start)
+
+    # --- container stop ---
+    ct_stop = ct_sub.add_parser("stop", help="Stop a container")
+    ct_stop.add_argument("vmid", type=vmid_type, help="Container ID")
+    ct_stop.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ct_stop.set_defaults(func=_ct_stop)
+
+    # --- container delete ---
+    ct_delete = ct_sub.add_parser("delete", help="Delete a container")
+    ct_delete.add_argument("vmid", type=vmid_type, help="Container ID")
+    ct_delete.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ct_delete.add_argument("--force", action="store_true", help="Force removal")
+    ct_delete.add_argument("--purge", action="store_true", help="Purge from all configurations")
+    ct_delete.set_defaults(func=_ct_delete)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_ct_node(client: ProxmoxClient, node: str | None, vmid: int) -> str | None:
+    if node:
+        return node
+    try:
+        resources = client.get("/cluster/resources", params={"type": "vm"})
+        if isinstance(resources, list):
+            for r in resources:
+                if r.get("vmid") == vmid:
+                    return r.get("node")
+    except Exception:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+def _ct_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node:
+        return client.get(f"/nodes/{args.node}/lxc")
+    nodes = client.get("/nodes")
+    if isinstance(nodes, dict):
+        nodes = nodes.get("data", [])
+    cts: list[dict] = []
+    for n in (nodes if isinstance(nodes, list) else []):
+        node_name = n.get("node") if isinstance(n, dict) else n
+        try:
+            node_cts = client.get(f"/nodes/{node_name}/lxc")
+            if isinstance(node_cts, list):
+                for ct in node_cts:
+                    if isinstance(ct, dict):
+                        ct["_node"] = node_name
+                    cts.append(ct)
+            elif isinstance(node_cts, dict):
+                for ct in node_cts.get("data", []):
+                    if isinstance(ct, dict):
+                        ct["_node"] = node_name
+                    cts.append(ct)
+        except Exception:
+            pass
+    return cts
+
+
+def _ct_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_ct_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"Container {args.vmid} not found"}
+    result = client.get(f"/nodes/{node}/lxc/{args.vmid}/status/current")
+    if isinstance(result, dict):
+        result["_node"] = node
+    return result
+
+
+def _ct_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {
+        "vmid": args.vmid,
+        "ostemplate": args.ostemplate,
+        "memory": args.memory,
+        "cores": args.cores,
+    }
+    if args.storage:
+        data["storage"] = args.storage
+    if args.net:
+        data["net0"] = args.net
+    if args.password:
+        data["password"] = args.password
+    return client.post(f"/nodes/{args.node}/lxc", data=data)
+
+
+def _ct_start(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_ct_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"Container {args.vmid} not found"}
+    return client.post(f"/nodes/{node}/lxc/{args.vmid}/status/start")
+
+
+def _ct_stop(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_ct_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"Container {args.vmid} not found"}
+    return client.post(f"/nodes/{node}/lxc/{args.vmid}/status/stop")
+
+
+def _ct_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_ct_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"Container {args.vmid} not found"}
+    params: dict = {}
+    if args.force:
+        params["force"] = 1
+    if args.purge:
+        params["purge"] = 1
+    return client.delete(f"/nodes/{node}/lxc/{args.vmid}", params=params or None)