proxcli 0.1.0__py3-none-any.whl

proxmox/cli/main.py

@@ -0,0 +1,231 @@
+"""Root CLI parser and main entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Any
+
+from proxmox.client.auth import AuthManager
+from proxmox.client.client import ProxmoxClient
+from proxmox.client.exceptions import ConfigError, ProxmoxAPIError, ProxmoxError
+from proxmox.config.config import ConfigLoader
+from proxmox.config.models import AuthMethod as AuthMethodModel
+from proxmox.config.models import Credentials
+from proxmox.output.formatter import format_output
+from proxmox.utils.logging import log_error
+
+
+def build_root_parser() -> argparse.ArgumentParser:
+    """Build the root argument parser with global flags and subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="proxmox",
+        description="CLI tool to interact with Proxmox VE via the REST API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Global flags
+    parser.add_argument("--url", help="Proxmox API URL (e.g. https://pve:8006)")
+    parser.add_argument("--username", help="Username (e.g. root@pam)")
+    parser.add_argument("--password", help="Password (for password auth)")
+    parser.add_argument("--password-stdin", action="store_true", help="Read password from stdin")
+    parser.add_argument("--api-token", help="API token in format: user!tokenid=secret")
+    parser.add_argument(
+        "--output",
+        choices=["json", "table", "yaml"],
+        default="json",
+        help="Output format (default: json)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Print the API request without executing it"
+    )
+    parser.add_argument(
+        "--insecure", action="store_true", help="Skip TLS certificate verification"
+    )
+    parser.add_argument(
+        "--timeout", type=int, default=30, help="Request timeout in seconds (default: 30)"
+    )
+    parser.add_argument("--verbose", action="store_true", help="Enable debug output to stderr")
+    parser.add_argument(
+        "--version", action="version", version="proxmox 0.1.0"
+    )
+
+    subparsers = parser.add_subparsers(dest="resource", title="resources", required=False)
+
+    # Import and register subcommands
+    from proxmox.cli.auth import register_auth_parser
+    from proxmox.cli.cluster import register_cluster_parser
+    from proxmox.cli.container import register_container_parser
+    from proxmox.cli.node import register_node_parser
+    from proxmox.cli.storage import register_storage_parser
+    from proxmox.cli.tasks import register_task_parser
+    from proxmox.cli.vm import register_vm_parser
+
+    register_auth_parser(subparsers)
+    register_vm_parser(subparsers)
+    register_node_parser(subparsers)
+    register_container_parser(subparsers)
+    register_storage_parser(subparsers)
+    register_cluster_parser(subparsers)
+    register_task_parser(subparsers)
+
+    return parser
+
+
+def _merge_config(args: argparse.Namespace) -> tuple[Credentials | None, dict[str, Any]]:
+    """Merge config file, env vars, and CLI flags.
+
+    Returns (credentials, overrides) where overrides has keys: url, username, password,
+    api_token_id, api_token_secret, verify_tls. CLI flags win over env vars and config file.
+    """
+    loader = ConfigLoader()
+    creds = loader.load_or_none()
+
+    overrides: dict[str, Any] = {
+        "url": None,
+        "username": None,
+        "password": None,
+        "api_token_id": None,
+        "api_token_secret": None,
+    }
+
+    # Apply config file values first
+    if creds:
+        overrides["url"] = creds.url
+        overrides["username"] = creds.username
+        overrides["verify_tls"] = creds.verify_tls
+        if creds.auth_method == AuthMethodModel.PASSWORD:
+            overrides["password"] = creds.password
+        elif creds.auth_method == AuthMethodModel.API_TOKEN:
+            overrides["api_token_id"] = creds.api_token_id
+            overrides["api_token_secret"] = creds.api_token_secret
+
+    # Env var override
+    env_password = os.environ.get("PROXMOX_PASSWORD")
+    if env_password:
+        overrides["password"] = env_password
+
+    # CLI flag overrides (highest priority)
+    if args.url:
+        overrides["url"] = args.url
+    if args.username:
+        overrides["username"] = args.username
+    if args.password:
+        overrides["password"] = args.password
+    if args.password_stdin:
+        overrides["password"] = sys.stdin.readline().rstrip("\n")
+    if args.api_token:
+        parts = args.api_token.split("=", 1)
+        if len(parts) == 2:
+            user_token, secret = parts
+            if "!" in user_token:
+                user, token_id = user_token.split("!", 1)
+                overrides["username"] = user
+                overrides["api_token_id"] = token_id
+                overrides["api_token_secret"] = secret
+            else:
+                overrides["username"] = user_token
+                overrides["api_token_secret"] = secret
+        else:
+            log_error("Invalid --api-token format. Expected: user!tokenid=secret")
+    if args.insecure:
+        overrides["verify_tls"] = False
+    elif "verify_tls" not in overrides:
+        overrides["verify_tls"] = True
+
+    return creds, overrides
+
+
+def _build_client(overrides: dict[str, Any], args: argparse.Namespace) -> ProxmoxClient:
+    """Build a ProxmoxClient from merged config overrides."""
+    if not overrides["url"]:
+        raise ConfigError("No Proxmox URL configured. Use --url or run 'proxmox auth login'.")
+
+    auth_mgr = AuthManager()
+
+    # Don't authenticate if dry-run (no actual API calls will be made)
+    if not args.dry_run:
+        if overrides["api_token_id"] and overrides["api_token_secret"]:
+            auth_mgr.set_api_token(
+                overrides["username"] or "root@pam",
+                overrides["api_token_id"],
+                overrides["api_token_secret"],
+            )
+        elif overrides["password"]:
+            auth_mgr.authenticate_password(
+                overrides["url"],
+                overrides["username"] or "root@pam",
+                overrides["password"],
+                verify=overrides["verify_tls"],
+            )
+
+    client = ProxmoxClient(
+        base_url=overrides["url"],
+        auth_manager=auth_mgr,
+        timeout=args.timeout,
+        verify_tls=overrides["verify_tls"],
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+    )
+
+    # Store for lazy re-auth
+    if overrides["password"]:
+        client.set_credentials(overrides["username"] or "root@pam", overrides["password"])
+
+    return client
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Main entry point."""
+    parser = build_root_parser()
+    args = parser.parse_args(argv)
+
+    # --help or no subcommand: just show help
+    if args.resource is None:
+        parser.print_help()
+        return
+
+    try:
+        # auth status and clear don't need a client
+        if args.resource == "auth" and args.action in ("status", "clear"):
+            if hasattr(args, "func"):
+                result = args.func(args, None)
+                if result is not None:
+                    output = format_output(result, args.output)
+                    print(output)
+            return
+
+        _, overrides = _merge_config(args)
+        client = _build_client(overrides, args)
+
+        # Each subcommand sets args.func during registration
+        if hasattr(args, "func"):
+            result = args.func(args, client)
+            if result is not None:
+                output = format_output(result, args.output)
+                print(output)
+        else:
+            # Subcommand registered but no func set (cli module not implemented yet)
+            log_error(f"Command 'proxmox {args.resource}' is not yet implemented.")
+
+    except ConfigError as exc:
+        log_error(str(exc))
+        sys.exit(1)
+    except ProxmoxAPIError as exc:
+        if args.output == "json":
+            print(
+                format_output(
+                    {"error": exc.message, "status_code": exc.status_code}, "json"
+                )
+            )
+        else:
+            log_error(str(exc))
+        sys.exit(exc.status_code if exc.status_code > 0 else 1)
+    except ProxmoxError as exc:
+        log_error(str(exc))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

proxmox/cli/node.py

@@ -0,0 +1,55 @@
+"""`proxmox node` subcommand — node management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+
+
+def register_node_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox node` subcommand tree."""
+    node_parser = subparsers.add_parser("node", help="Manage Proxmox nodes")
+    node_sub = node_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- node list ---
+    node_list = node_sub.add_parser("list", help="List all nodes")
+    node_list.set_defaults(func=_node_list)
+
+    # --- node show ---
+    node_show = node_sub.add_parser("show", help="Show node details")
+    node_show.add_argument("node_name", help="Node name")
+    node_show.set_defaults(func=_node_show)
+
+    # --- node status ---
+    node_status = node_sub.add_parser("status", help="Show node status")
+    node_status.add_argument("node_name", nargs="?", help="Node name (omit for all nodes)")
+    node_status.set_defaults(func=_node_status)
+
+
+def _node_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/nodes")
+
+
+def _node_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/nodes/{args.node_name}/status")
+
+
+def _node_status(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node_name:
+        return client.get(f"/nodes/{args.node_name}/status")
+    # Return all nodes' statuses
+    nodes = client.get("/nodes")
+    if isinstance(nodes, list):
+        result = []
+        for n in nodes:
+            node_name = n.get("node") if isinstance(n, dict) else n
+            try:
+                status = client.get(f"/nodes/{node_name}/status")
+                if isinstance(status, dict):
+                    status["node"] = node_name
+                result.append(status)
+            except Exception:
+                result.append({"node": node_name, "status": "error"})
+        return result
+    return nodes

proxmox/cli/storage.py

@@ -0,0 +1,63 @@
+"""`proxmox storage` subcommand — storage management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+
+
+def register_storage_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox storage` subcommand tree."""
+    st_parser = subparsers.add_parser("storage", help="Manage Proxmox storage")
+    st_sub = st_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- storage list ---
+    st_list = st_sub.add_parser("list", help="List all storages")
+    st_list.add_argument("--node", help="Filter by node name")
+    st_list.set_defaults(func=_st_list)
+
+    # --- storage show ---
+    st_show = st_sub.add_parser("show", help="Show storage details")
+    st_show.add_argument("storage_name", help="Storage name")
+    st_show.set_defaults(func=_st_show)
+
+    # --- storage content ---
+    st_content = st_sub.add_parser("content", help="List storage contents")
+    st_content.add_argument("storage_name", help="Storage name")
+    st_content.add_argument("--node", help="Node name (auto-detected if omitted)")
+    st_content.set_defaults(func=_st_content)
+
+
+def _st_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node:
+        return client.get(f"/nodes/{args.node}/storage")
+    return client.get("/storage")
+
+
+def _st_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/storage/{args.storage_name}/status")
+
+
+def _resolve_storage_node(client: ProxmoxClient, storage: str) -> str | None:
+    """Find which node a storage belongs to."""
+    try:
+        storages = client.get("/storage")
+        if isinstance(storages, list):
+            for s in storages:
+                if isinstance(s, dict) and s.get("storage") == storage:
+                    return s.get("node")
+        elif isinstance(storages, dict):
+            for s in storages.get("data", []):
+                if isinstance(s, dict) and s.get("storage") == storage:
+                    return s.get("node")
+    except Exception:
+        pass
+    return None
+
+
+def _st_content(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    node = args.node or _resolve_storage_node(client, args.storage_name)
+    if not node:
+        return {"error": f"Could not determine node for storage '{args.storage_name}'"}
+    return client.get(f"/nodes/{node}/storage/{args.storage_name}/content")

proxmox/cli/tasks.py

@@ -0,0 +1,65 @@
+"""`proxmox task` subcommand — task management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+
+
+def register_task_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox task` subcommand tree."""
+    task_parser = subparsers.add_parser("task", help="Manage Proxmox tasks/logs")
+    task_sub = task_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- task list ---
+    task_list = task_sub.add_parser("list", help="List recent tasks")
+    task_list.add_argument("--node", help="Filter by node name")
+    task_list.set_defaults(func=_task_list)
+
+    # --- task show ---
+    task_show = task_sub.add_parser("show", help="Show task details")
+    task_show.add_argument("upid", help="Task UPID")
+    task_show.set_defaults(func=_task_show)
+
+
+def _extract_node_from_upid(upid: str) -> str | None:
+    """Parse node name from a Proxmox UPID string: UPID:{node}:..."""
+    parts = upid.split(":")
+    if len(parts) >= 2:
+        return parts[1]
+    return None
+
+
+def _task_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node:
+        return client.get(f"/nodes/{args.node}/tasks")
+    # Iterate all nodes
+    nodes = client.get("/nodes")
+    if isinstance(nodes, dict):
+        nodes = nodes.get("data", [])
+    tasks: list[dict] = []
+    for n in (nodes if isinstance(nodes, list) else []):
+        node_name = n.get("node") if isinstance(n, dict) else n
+        try:
+            node_tasks = client.get(f"/nodes/{node_name}/tasks")
+            if isinstance(node_tasks, list):
+                for t in node_tasks:
+                    if isinstance(t, dict):
+                        t["_node"] = node_name
+                    tasks.append(t)
+            elif isinstance(node_tasks, dict):
+                for t in node_tasks.get("data", []):
+                    if isinstance(t, dict):
+                        t["_node"] = node_name
+                    tasks.append(t)
+        except Exception:
+            pass
+    return tasks
+
+
+def _task_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _extract_node_from_upid(args.upid)
+    if not node:
+        return {"error": f"Could not extract node from UPID: {args.upid}"}
+    return client.get(f"/nodes/{node}/tasks/{args.upid}/status")

proxmox/cli/vm.py

@@ -0,0 +1,211 @@
+"""`proxmox vm` subcommand — QEMU virtual machine management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.client.client import ProxmoxClient
+from proxmox.utils.helpers import vmid_type
+
+
+def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox vm` subcommand tree."""
+    vm_parser = subparsers.add_parser("vm", help="Manage QEMU virtual machines")
+    vm_sub = vm_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- vm list ---
+    vm_list = vm_sub.add_parser("list", help="List virtual machines")
+    vm_list.add_argument("--node", help="Filter by node name")
+    vm_list.set_defaults(func=_vm_list)
+
+    # --- vm show ---
+    vm_show = vm_sub.add_parser("show", help="Show VM details")
+    vm_show.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_show.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_show.set_defaults(func=_vm_show)
+
+    # --- vm create ---
+    vm_create = vm_sub.add_parser("create", help="Create a new VM")
+    vm_create.add_argument("--node", required=True, help="Target node")
+    vm_create.add_argument("--vmid", type=vmid_type, required=True, help="VM ID")
+    vm_create.add_argument("--memory", type=int, required=True, help="Memory in MB")
+    vm_create.add_argument("--cores", type=int, default=1, help="CPU cores (default: 1)")
+    vm_create.add_argument("--net", default=None, help="Network config (e.g. model=virtio,bridge=vmbr0)")
+    vm_create.add_argument("--storage", default=None, help="Storage for the VM disk")
+    vm_create.add_argument("--ostemplate", default=None, help="OS template/ISO")
+    vm_create.add_argument("--name", default=None, help="VM name")
+    vm_create.set_defaults(func=_vm_create)
+
+    # --- vm start ---
+    vm_start = vm_sub.add_parser("start", help="Start a VM")
+    vm_start.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_start.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_start.set_defaults(func=_vm_start)
+
+    # --- vm stop ---
+    vm_stop = vm_sub.add_parser("stop", help="Stop a VM")
+    vm_stop.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_stop.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_stop.set_defaults(func=_vm_stop)
+
+    # --- vm reboot ---
+    vm_reboot = vm_sub.add_parser("reboot", help="Reboot a VM")
+    vm_reboot.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_reboot.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_reboot.set_defaults(func=_vm_reboot)
+
+    # --- vm suspend ---
+    vm_suspend = vm_sub.add_parser("suspend", help="Suspend a VM")
+    vm_suspend.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_suspend.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_suspend.set_defaults(func=_vm_suspend)
+
+    # --- vm resume ---
+    vm_resume = vm_sub.add_parser("resume", help="Resume a VM")
+    vm_resume.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_resume.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_resume.set_defaults(func=_vm_resume)
+
+    # --- vm delete ---
+    vm_delete = vm_sub.add_parser("delete", help="Delete a VM")
+    vm_delete.add_argument("vmid", type=vmid_type, help="VM ID")
+    vm_delete.add_argument("--node", help="Node name (auto-detected if omitted)")
+    vm_delete.add_argument("--force", action="store_true", help="Force removal")
+    vm_delete.add_argument("--purge", action="store_true", help="Purge VM from all configurations")
+    vm_delete.set_defaults(func=_vm_delete)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_node(client: ProxmoxClient, node: str | None, vmid: int) -> str | None:
+    """Resolve which node hosts a given VMID, unless node is already provided."""
+    if node:
+        return node
+    # Try cluster resources lookup
+    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 _vm_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node:
+        result = client.get(f"/nodes/{args.node}/qemu")
+        return result if isinstance(result, list) else result.get("data", result)
+    # All nodes: iterate
+    nodes = client.get("/nodes")
+    if isinstance(nodes, dict):
+        nodes = nodes.get("data", [])
+    vms: list[dict] = []
+    for n in (nodes if isinstance(nodes, list) else []):
+        node_name = n.get("node") if isinstance(n, dict) else n
+        try:
+            node_vms = client.get(f"/nodes/{node_name}/qemu")
+            if isinstance(node_vms, list):
+                for vm in node_vms:
+                    if isinstance(vm, dict):
+                        vm["_node"] = node_name
+                    vms.append(vm)
+            elif isinstance(node_vms, dict):
+                for vm in node_vms.get("data", []):
+                    if isinstance(vm, dict):
+                        vm["_node"] = node_name
+                    vms.append(vm)
+        except Exception:
+            pass
+    return vms
+
+
+def _vm_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found on any node"}
+    resources = client.get(f"/nodes/{node}/qemu/{args.vmid}/status/current")
+    if isinstance(resources, dict):
+        resources["_node"] = node
+    else:
+        resources = {"data": resources, "_node": node}
+    return resources
+
+
+def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {
+        "vmid": args.vmid,
+        "memory": args.memory,
+        "cores": args.cores,
+    }
+    if args.net:
+        data["net0"] = args.net
+    if args.name:
+        data["name"] = args.name
+    if args.ostemplate:
+        data["ostemplate"] = args.ostemplate
+    if args.storage:
+        data["storage"] = args.storage
+
+    result = client.post(f"/nodes/{args.node}/qemu", data=data)
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_start(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/status/start")
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_stop(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/status/stop")
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_reboot(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/status/reboot")
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_suspend(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/status/suspend")
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_resume(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/status/resume")
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    params: dict = {}
+    if args.force:
+        params["force"] = 1
+    if args.purge:
+        params["purge"] = 1
+    result = client.delete(f"/nodes/{node}/qemu/{args.vmid}", params=params or None)
+    return result if isinstance(result, dict) else {"data": result}