proxcli 0.7.2__tar.gz → 0.8.1__tar.gz

{proxcli-0.7.2 → proxcli-0.8.1}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-06-20
+
+### Added
+- **vm snapshot** management: ``list``, ``create``, ``show``, ``rollback``,
+  ``delete``.  Wraps ``/nodes/{node}/qemu/{vmid}/snapshot`` endpoints.
+
+## [0.8.0] - 2026-06-20
+
+### Fixed
+- **vm create** now works against real Proxmox 9.x clusters.  The `--ostemplate`
+  flag has been renamed to `--cdrom` (``ostemplate`` is an LXC parameter, not
+  QEMU).  The handler now builds a raw form-encoded body to avoid httpx
+  double-encoding ``%`` characters in IDE and network configuration strings.
+
+### Changed
+- **vm create** ``--net`` now uses ``action="append"`` so you can repeat it
+  for multiple NICs (net0, net1, …).
+
+### Added
+- **vm create** gains new optional flags: ``--scsihw``, ``--bios``,
+  ``--machine``, ``--boot``, ``--disk``.
+- ``ProxmoxClient.request()`` now accepts a ``content`` keyword argument
+  for sending a pre-encoded raw body instead of ``data``.
+
 ## [0.7.2] - 2026-06-20
 
 ### Added
@@ -100,6 +124,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CSRF ticket auto-refresh on 401.
 - AI-agent-friendly: default JSON output, strict exit codes, `--dry-run` mode.
 
+[0.8.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.1
+[0.8.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.0
 [0.7.2]: https://github.com/xezpeleta/proxcli/releases/tag/v0.7.2
 [0.7.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.7.1
 [0.7.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.7.0

{proxcli-0.7.2 → proxcli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.7.2
+Version: 0.8.1
 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

{proxcli-0.7.2 → proxcli-0.8.1}/proxmox/cli/vm.py

@@ -31,10 +31,19 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_create.add_argument("--vmid", type=vmid_type, default=None, help="VM ID (auto-assigned if omitted)")
     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(
+        "--net", default=None, action="append", dest="net_ifaces",
+        help="Network config (e.g. virtio=MAC,bridge=vmbr0). Repeat for multiple NICs."
+    )
     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("--cdrom", default=None, help="ISO volume for install (e.g. local:iso/debian.iso)")
     vm_create.add_argument("--name", default=None, help="VM name")
+    vm_create.add_argument("--scsihw", default=None, choices=["lsi", "lsi53c810", "virtio-scsi-pci", "virtio-scsi-single", "megasas", "pvscsi"],
+                           help="SCSI controller type")
+    vm_create.add_argument("--bios", default=None, choices=["seabios", "ovmf"], help="BIOS type")
+    vm_create.add_argument("--machine", default=None, help="Machine type (e.g. q35)")
+    vm_create.add_argument("--boot", default=None, help="Boot order (e.g. order=cd;net)")
+    vm_create.add_argument("--disk", default=None, help="Disk size (e.g. 32G). Uses --storage if set, else local-lvm.")
     vm_create.set_defaults(func=_vm_create)
 
     # --- vm start ---
@@ -75,6 +84,46 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_delete.add_argument("--purge", action="store_true", help="Purge VM from all configurations")
     vm_delete.set_defaults(func=_vm_delete)
 
+    # --- snapshot ---
+    snap = vm_sub.add_parser("snapshot", help="Manage VM snapshots")
+    snap_sub = snap.add_subparsers(dest="snap_action", title="snapshot actions", required=True)
+
+    snap_list = snap_sub.add_parser("list", help="List snapshots")
+    snap_list.add_argument("vmid", type=vmid_type, help="VM ID")
+    snap_list.add_argument("--node", help="Node name (auto-detected if omitted)")
+    snap_list.set_defaults(func=_vm_snapshot_list)
+
+    snap_create = snap_sub.add_parser("create", help="Create a snapshot")
+    snap_create.add_argument("vmid", type=vmid_type, help="VM ID")
+    snap_create.add_argument("snapname", help="Snapshot name")
+    snap_create.add_argument("--node", help="Node name (auto-detected if omitted)")
+    snap_create.add_argument("--description", default=None, help="Snapshot description")
+    snap_create.add_argument("--vmstate", type=int, choices=[0, 1], default=0,
+                             help="Include RAM state (1=yes, 0=no, default: 0)")
+    snap_create.set_defaults(func=_vm_snapshot_create)
+
+    snap_show = snap_sub.add_parser("show", help="Show snapshot details")
+    snap_show.add_argument("vmid", type=vmid_type, help="VM ID")
+    snap_show.add_argument("snapname", help="Snapshot name")
+    snap_show.add_argument("--node", help="Node name (auto-detected if omitted)")
+    snap_show.set_defaults(func=_vm_snapshot_show)
+
+    snap_rollback = snap_sub.add_parser("rollback", help="Rollback to a snapshot")
+    snap_rollback.add_argument("vmid", type=vmid_type, help="VM ID")
+    snap_rollback.add_argument("snapname", help="Snapshot name")
+    snap_rollback.add_argument("--node", help="Node name (auto-detected if omitted)")
+    snap_rollback.add_argument("--start", type=int, choices=[0, 1], default=0,
+                               help="Start VM after rollback (1=yes, 0=no, default: 0)")
+    snap_rollback.set_defaults(func=_vm_snapshot_rollback)
+
+    snap_delete = snap_sub.add_parser("delete", help="Delete a snapshot")
+    snap_delete.add_argument("vmid", type=vmid_type, help="VM ID")
+    snap_delete.add_argument("snapname", help="Snapshot name")
+    snap_delete.add_argument("--node", help="Node name (auto-detected if omitted)")
+    snap_delete.add_argument("--force", type=int, choices=[0, 1], default=0,
+                             help="Force removal (1=yes, 0=no, default: 0)")
+    snap_delete.set_defaults(func=_vm_snapshot_delete)
+
     # --- firewall ---
     fw = vm_sub.add_parser("firewall", help="Manage VM firewall")
     fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
@@ -215,21 +264,51 @@ def _vm_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
 
 
 def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    vmid = resolve_vmid(client, args.vmid)
     data: dict = {
-        "vmid": resolve_vmid(client, args.vmid),
-        "memory": args.memory,
-        "cores": args.cores,
+        "vmid": str(vmid),
+        "memory": str(args.memory),
+        "cores": str(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)
+    if args.bios:
+        data["bios"] = args.bios
+    if args.machine:
+        data["machine"] = args.machine
+    if args.scsihw:
+        data["scsihw"] = args.scsihw
+    if args.boot:
+        data["boot"] = args.boot
+
+    # Network interfaces: net0, net1, ...
+    if args.net_ifaces:
+        for i, net_cfg in enumerate(args.net_ifaces):
+            # Pre-encode the net config for form body: = → %3D, : → %3A, , → %2C
+            encoded = net_cfg.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+            data[f"net{i}"] = encoded
+
+    # CD-ROM / ISO
+    if args.cdrom:
+        # Build: file=storage:iso/file.iso,media=cdrom
+        # Pre-encode: = → %3D, : → %3A, , → %2C
+        ide_raw = f"file={args.cdrom},media=cdrom"
+        data["ide2"] = ide_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+
+    # Disk
+    if args.disk:
+        storage = args.storage or "local-lvm"
+        if ":" not in args.disk:
+            disk_raw = f"{storage}:{args.disk}"
+        else:
+            disk_raw = args.disk
+        data["scsi0"] = disk_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+
+    # Build form-encoded body manually — httpx's data= would double-encode %
+    from urllib.parse import urlencode
+    body = urlencode(data, safe="%")  # safe="%" means don't re-encode existing %XX
+
+    result = client.request("POST", f"/nodes/{args.node}/qemu", content=body)
     return result if isinstance(result, dict) else {"data": result}
 
 
@@ -286,6 +365,76 @@ def _vm_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     return result if isinstance(result, dict) else {"data": result}
 
 
+# ---------------------------------------------------------------------------
+# VM snapshot handlers
+# ---------------------------------------------------------------------------
+
+def _vm_snapshot_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    result = client.get(f"/nodes/{node}/qemu/{args.vmid}/snapshot")
+    # Add _node for consistency
+    if isinstance(result, list):
+        for snap in result:
+            if isinstance(snap, dict):
+                snap["_node"] = node
+                snap["_vmid"] = args.vmid
+    return result
+
+
+def _vm_snapshot_create(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"}
+    data: dict = {"snapname": args.snapname}
+    if args.description:
+        data["description"] = args.description
+    if args.vmstate:
+        data["vmstate"] = args.vmstate
+    result = client.post(f"/nodes/{node}/qemu/{args.vmid}/snapshot", data=data)
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_snapshot_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"}
+    result = client.get(f"/nodes/{node}/qemu/{args.vmid}/snapshot/{args.snapname}")
+    if isinstance(result, dict):
+        result["_node"] = node
+        result["_vmid"] = args.vmid
+    return result
+
+
+def _vm_snapshot_rollback(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"}
+    data: dict = {}
+    if args.start:
+        data["start"] = args.start
+    result = client.post(
+        f"/nodes/{node}/qemu/{args.vmid}/snapshot/{args.snapname}/rollback",
+        data=data or None,
+    )
+    return result if isinstance(result, dict) else {"data": result}
+
+
+def _vm_snapshot_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"] = args.force
+    result = client.delete(
+        f"/nodes/{node}/qemu/{args.vmid}/snapshot/{args.snapname}",
+        params=params or None,
+    )
+    return result if isinstance(result, dict) else {"data": result}
+
+
 # ---------------------------------------------------------------------------
 # VM firewall handlers
 # ---------------------------------------------------------------------------

{proxcli-0.7.2 → proxcli-0.8.1}/proxmox/client/client.py

@@ -58,23 +58,29 @@ class ProxmoxClient:
         *,
         params: dict[str, Any] | None = None,
         data: dict[str, Any] | None = None,
+        content: str | None = None,
     ) -> dict[str, Any] | list[Any]:
         """Send an HTTP request and unwrap the Proxmox JSON envelope.
 
         Returns ``response.json()["data"]`` on success.
+
+        Set ``content`` to send a raw string body (e.g. pre-encoded form data)
+        instead of ``data`` which gets form-encoded by httpx.
         """
         path = self._normalise_path(path)
         full_url = f"{self._base_url}/api2/json{path}"
 
         self._debug(f"{method} {full_url}")
-        if data:
+        if content:
+            self._debug(f"  content: {content[:200]}")
+        elif data:
             self._debug(f"  body: {data}")
 
         if self._dry_run:
-            self._print_dry_run(method, full_url, data)
+            self._print_dry_run(method, full_url, data or {"content": content})
             return {}
 
-        return self._send_with_retry(method, full_url, params, data)
+        return self._send_with_retry(method, full_url, params, data, content)
 
     def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any] | list[Any]:
         return self.request("GET", path, params=params)
@@ -186,12 +192,13 @@ class ProxmoxClient:
         url: str,
         params: dict[str, Any] | None,
         data: dict[str, Any] | None,
+        content: str | None = None,
     ) -> dict[str, Any] | list[Any]:
         last_exc: Exception | None = None
 
         for attempt in range(self._max_retries + 1):
             try:
-                return self._send_one(method, url, params, data)
+                return self._send_one(method, url, params, data, content)
             except AuthError:
                 raise  # don't retry auth errors
             except ProxmoxAPIError as exc:
@@ -219,19 +226,27 @@ class ProxmoxClient:
         url: str,
         params: dict[str, Any] | None,
         data: dict[str, Any] | None,
+        content: str | None = None,
     ) -> dict[str, Any] | list[Any]:
         headers = self._auth.get_headers()
 
+        # Build the httpx kwargs
+        httpx_kwargs: dict[str, Any] = dict(
+            method=method,
+            url=url,
+            params=params,
+            headers=headers,
+            timeout=self._timeout,
+            verify=self._verify_tls,
+        )
+        if content is not None:
+            httpx_kwargs["content"] = content
+            httpx_kwargs["headers"] = {**headers, "Content-Type": "application/x-www-form-urlencoded"}
+        else:
+            httpx_kwargs["data"] = data
+
         try:
-            resp = httpx.request(
-                method=method,
-                url=url,
-                params=params,
-                data=data,
-                headers=headers,
-                timeout=self._timeout,
-                verify=self._verify_tls,
-            )
+            resp = httpx.request(**httpx_kwargs)
         except httpx.TimeoutException:
             raise
         except httpx.RequestError as exc:
@@ -247,16 +262,10 @@ class ProxmoxClient:
             # Auto-refresh ticket once
             self._debug("  🔄 re-authenticating ...")
             self.authenticate()
-            headers = self._auth.get_headers()
-            resp = httpx.request(
-                method=method,
-                url=url,
-                params=params,
-                data=data,
-                headers=headers,
-                timeout=self._timeout,
-                verify=self._verify_tls,
-            )
+            retry_headers = self._auth.get_headers()
+            retry_kwargs = dict(httpx_kwargs)
+            retry_kwargs["headers"] = retry_headers
+            resp = httpx.request(**retry_kwargs)
 
         if not (200 <= resp.status_code < 300):
             try:

{proxcli-0.7.2 → proxcli-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxcli"
-version = "0.7.2"
+version = "0.8.1"
 description = "A CLI tool to interact with Proxmox VE nodes and clusters via the REST API"
 readme = "README.md"
 authors = [

{proxcli-0.7.2 → proxcli-0.8.1}/uv.lock

@@ -254,7 +254,7 @@ wheels = [
 
 [[package]]
 name = "proxcli"
-version = "0.7.2"
+version = "0.8.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },