proxcli 0.16.0__tar.gz → 0.16.2__tar.gz

{proxcli-0.16.0 → proxcli-0.16.2}/CHANGELOG.md

@@ -5,7 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.15.0] - 2026-06-30
+## [0.16.2] - 2026-06-30
+
+### Added
+- **``proxmox update``**: self-upgrade proxcli from PyPI. Queries the PyPI JSON
+  API to check for new versions and uses ``uv tool install proxcli --reinstall``
+  to upgrade in-place. ``--check`` flag reports available updates without
+  installing. ``--pre`` includes pre-release versions.
+
+## [0.16.1] - 2026-06-30
+
+### Added
+- **``proxmox vm disk import``**: import a disk image into an existing VM.
+  Supports two sources:
+  - ``--image <path>``: a disk image already on the PVE node filesystem
+    (e.g. ``/var/lib/vz/import/deb13.qcow2``).
+  - ``--url <url>``: downloads the image locally, uploads it to Proxmox
+    storage via the API, then imports it into the VM — all in one command.
+    The temp file is cleaned up automatically.  Wraps
+    ``PUT /nodes/{node}/qemu/{vmid}/config`` with `import-from`.
+- **Cloud-init auto-config**: ``vm create`` now automatically adds
+  ``serial0=socket`` and ``vga=serial0`` when any cloud-init flags
+  (``--citype``, ``--ciuser``, etc.) are present.  This matches the
+  official Proxmox documentation and is required by Debian generic
+  cloud images.
+
+### Changed
+- **Docs**: added ``vm disk import`` to README command reference;
+  updated ``docs/cloud-init.md`` with ``--url`` import workflow;
+  updated ``docs/production-automation.md`` with the new commands.
+
+## [0.16.0] - 2026-06-30
 
 ### Added
 - **``proxmox vm set``**: update VM configuration keys. Wraps
@@ -333,6 +363,9 @@ 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.16.2]: https://github.com/xezpeleta/proxcli/releases/tag/v0.16.2
+[0.16.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.16.1
+[0.16.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.16.0
 [0.15.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.15.0
 [0.14.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.14.0
 [0.13.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.13.1

{proxcli-0.16.0 → proxcli-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.16.0
+Version: 0.16.2
 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
@@ -192,6 +192,14 @@ proxmox auth setup             # Create recommended roles + ACLs (needs Administ
 proxmox auth check             # Live permission test table (39 checks)
 ```
 
+### Self-update
+
+```bash
+proxmox update              # Check for updates and install the latest version
+proxmox update --check      # Only check (no install)
+proxmox update --pre        # Include pre-release versions
+```
+
 ### Completion
 
 ```bash
@@ -251,6 +259,13 @@ proxmox vm firewall rules show <vmid> <pos>
 proxmox vm firewall rules update <vmid> <pos> --action DROP
 proxmox vm firewall rules delete <vmid> <pos>
 proxmox vm firewall refs <vmid> [--type alias|ipset|group]
+
+# VM disk management
+proxmox vm disk import <vmid> --image /path/to/image.qcow2 [--disk scsi0] [--storage rbd_ssd]
+proxmox vm disk import <vmid> --url https://.../image.qcow2 [--disk scsi0] [--storage rbd_ssd]
+proxmox vm disk resize <vmid> --disk scsi0 --size +10G
+proxmox vm disk detach <vmid> --disk scsi0
+proxmox vm disk remove <vmid> --disk scsi0 [--force]
 ```
 
 #### Declarative VM specs (`--file`)

{proxcli-0.16.0 → proxcli-0.16.2}/README.md

@@ -169,6 +169,14 @@ proxmox auth setup             # Create recommended roles + ACLs (needs Administ
 proxmox auth check             # Live permission test table (39 checks)
 ```
 
+### Self-update
+
+```bash
+proxmox update              # Check for updates and install the latest version
+proxmox update --check      # Only check (no install)
+proxmox update --pre        # Include pre-release versions
+```
+
 ### Completion
 
 ```bash
@@ -228,6 +236,13 @@ proxmox vm firewall rules show <vmid> <pos>
 proxmox vm firewall rules update <vmid> <pos> --action DROP
 proxmox vm firewall rules delete <vmid> <pos>
 proxmox vm firewall refs <vmid> [--type alias|ipset|group]
+
+# VM disk management
+proxmox vm disk import <vmid> --image /path/to/image.qcow2 [--disk scsi0] [--storage rbd_ssd]
+proxmox vm disk import <vmid> --url https://.../image.qcow2 [--disk scsi0] [--storage rbd_ssd]
+proxmox vm disk resize <vmid> --disk scsi0 --size +10G
+proxmox vm disk detach <vmid> --disk scsi0
+proxmox vm disk remove <vmid> --disk scsi0 [--force]
 ```
 
 #### Declarative VM specs (`--file`)

{proxcli-0.16.0 → proxcli-0.16.2}/TODO.md

@@ -27,6 +27,9 @@ Completed items are marked with a check. Implementation notes are preserved for
 - [x] **Cluster log & options** — `proxmox cluster log [--limit N]` and `proxmox cluster options`.
 - [x] **Storage status** — `proxmox storage status <storage> [--node]` for usage stats.
 - [x] **API coverage doc** — `docs/api-coverage.md` tracking all implemented and remaining endpoints.
+- [x] **VM disk import from URL** — `vm disk import --url` downloads, uploads, and imports a disk image from a remote URL in one command. `--image` for local PVE node paths.
+- [x] **Cloud-init auto serial console** — `vm create` with cloud-init flags now auto-adds `serial0=socket` and `vga=serial0`, required by Debian generic cloud images.
+- [x] **Self-update** — `proxmox update` checks PyPI for newer versions and upgrades via `uv tool install --reinstall`. `--check` for dry-run, `--pre` for pre-releases.
 
 ## v1.1 — Polish & Usability
 

{proxcli-0.16.0 → proxcli-0.16.2}/docs/cloud-init.md

@@ -386,6 +386,8 @@ Stable release URLs follow the pattern:
 
 The `/latest/` symlink always points to the most recent weekly build.
 
+**Option A — Download & upload manually:**
+
 ```bash
 # Download (run on a Proxmox node or any machine with proxcli)
 curl -LO https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2
@@ -402,6 +404,18 @@ proxmox storage content local --node <node>
 # Look for: local:import/debian-13-generic-amd64.qcow2
 ```
 
+**Option B — Use `vm disk import --url` (download + upload + import in one command):**
+
+```bash
+# After creating the VM skeleton, import directly from URL:
+proxmox vm disk import <template-vmid> \
+  --url https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2 \
+  --storage rbd_ssd
+```
+
+This handles downloading, uploading to PVE storage, and importing the disk in a single command.
+The temporary file is cleaned up automatically.
+
 ### Step 2: Create the VM with cloud-init (stopped)
 
 ```bash
@@ -481,8 +495,9 @@ SSH keys).
 
 ```bash
 # --- One-time setup ---
-curl -LO https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2
 
+# Option A: Manual download + upload + create
+curl -LO https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2
 proxmox storage upload \
   --node pve01 --storage local --content-type import \
   --file debian-13-generic-amd64.qcow2
@@ -497,6 +512,20 @@ proxmox vm create \
   --sshkeys ~/.ssh/id_rsa.pub \
   --import-from local:import/debian-13-generic-amd64.qcow2
 
+# Option B: One-liner with --url (no manual download needed)
+proxmox vm create \
+  --node pve01 --vmid 9003 \
+  --name debian13-cloud-template \
+  --memory 2048 --cores 2 \
+  --net 'virtio,bridge=vmbr0' \
+  --scsihw virtio-scsi-pci \
+  --citype nocloud --ciuser debian \
+  --sshkeys ~/.ssh/id_rsa.pub
+proxmox vm disk import 9003 \
+  --url https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2 \
+  --storage rbd_ssd
+proxmox vm set 9003 --option boot=order=scsi0
+
 proxmox vm template 9003 --node pve01
 
 # --- Clone for each new VM (repeat as needed) ---

{proxcli-0.16.0 → proxcli-0.16.2}/docs/production-automation.md

@@ -156,7 +156,7 @@ jobs:
           PROXMOX_TOKEN_ID: ${{ secrets.PROXMOX_TOKEN_ID }}
           PROXMOX_TOKEN_SECRET: ${{ secrets.PROXMOX_TOKEN_SECRET }}
         run: |
-          proxmox auth login
+          proxmox auth status
           for spec in vm-specs/*.yaml; do
             proxmox vm create --file "$spec"
           done

{proxcli-0.16.0 → proxcli-0.16.2}/proxmox/cli/main.py

@@ -74,6 +74,7 @@ def build_root_parser() -> argparse.ArgumentParser:
     from proxmox.cli.role import register_role_parser
     from proxmox.cli.storage import register_storage_parser
     from proxmox.cli.tasks import register_task_parser
+    from proxmox.cli.update import register_update_parser
     from proxmox.cli.user import register_user_parser
     from proxmox.cli.vm import register_vm_parser
 
@@ -93,6 +94,7 @@ def build_root_parser() -> argparse.ArgumentParser:
     register_task_parser(subparsers)
     register_role_parser(subparsers)
     register_user_parser(subparsers)
+    register_update_parser(subparsers)
 
     return parser
 
@@ -224,7 +226,7 @@ GLOBAL_FLAGS_WITH_VALUE = {"--url", "--username", "--password", "--api-token", "
 def _hint_global_flags_order(argv: list[str]) -> None:
     """If user placed global flags after the resource, show a helpful hint."""
     resource_pos = -1
-    resources = {"acl", "api", "auth", "backup", "ceph", "vm", "node", "pool", "container", "storage", "cluster", "completion", "task", "user", "role", "network"}
+    resources = {"acl", "api", "auth", "backup", "ceph", "vm", "node", "pool", "container", "storage", "cluster", "completion", "task", "user", "role", "network", "update"}
     for i, arg in enumerate(argv):
         if arg in resources:
             resource_pos = i
@@ -297,7 +299,7 @@ def main(argv: list[str] | None = None) -> None:
 
     try:
         # auth status (without --permissions) and completion don't need a client
-        if args.resource == "completion" or (
+        if args.resource == "completion" or args.resource == "update" or (
             args.resource == "auth"
             and args.action == "status"
             and not getattr(args, "permissions", False)

proxcli-0.16.2/proxmox/cli/update.py

@@ -0,0 +1,154 @@
+"""proxmox update — self-upgrade proxcli from PyPI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import urllib.request
+from importlib.metadata import version
+
+from proxmox.utils.logging import log_error
+
+
+def register_update_parser(subparsers: argparse._SubParsersAction) -> None:
+    update_parser = subparsers.add_parser("update", help="Check for and install proxcli updates")
+    update_parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Only check if an update is available (do not install)",
+    )
+    update_parser.add_argument(
+        "--pre",
+        action="store_true",
+        help="Include pre-release versions when checking",
+    )
+    update_parser.set_defaults(func=_update, output_format="table")
+
+
+def _get_latest_version(include_pre: bool = False) -> str:
+    """Fetch the latest version tag from PyPI."""
+    url = "https://pypi.org/pypi/proxcli/json"
+    try:
+        with urllib.request.urlopen(url, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+    except Exception as exc:
+        raise RuntimeError(f"Failed to query PyPI: {exc}") from exc
+
+    versions = list(data.get("releases", {}).keys())
+
+    if not versions:
+        raise RuntimeError("No releases found on PyPI")
+
+    if not include_pre:
+        versions = [v for v in versions if _is_stable(v)]
+        if not versions:
+            raise RuntimeError("No stable releases found on PyPI")
+
+    return max(versions, key=_version_key)
+
+
+def _is_stable(ver: str) -> bool:
+    """Return True if version looks like a stable release (no dev/pre markers)."""
+    # Strip epoch if present
+    v = ver
+    # Simple check: no a/b/rc/dev/post markers
+    for marker in ("a", "b", "rc", "dev", "post"):
+        if marker in v:
+            return False
+    return True
+
+
+def _version_key(ver: str) -> tuple:
+    """Parse a version string into a comparable tuple."""
+    parts = ver.split(".")
+    result = []
+    for p in parts:
+        # Try int first
+        try:
+            result.append(int(p))
+        except ValueError:
+            result.append(p)
+    return tuple(result)
+
+
+def _update(args: argparse.Namespace, client: object | None = None) -> dict | str:
+    """Check for updates and optionally install them.
+
+    Returns a dict for the output formatter.
+    """
+    current = version("proxcli")
+
+    try:
+        latest = _get_latest_version(include_pre=args.pre)
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    up_to_date = _version_key(current) >= _version_key(latest)
+
+    if args.check:
+        if up_to_date:
+            return {
+                "current": current,
+                "latest": latest,
+                "status": "up-to-date",
+                "message": f"proxcli {current} is the latest version.",
+            }
+        else:
+            return {
+                "current": current,
+                "latest": latest,
+                "status": "update-available",
+                "message": f"proxcli {latest} is available (you have {current}). Run 'proxmox update' to upgrade.",
+            }
+
+    if up_to_date:
+        return {
+            "current": current,
+            "latest": latest,
+            "status": "up-to-date",
+            "message": f"proxcli {current} is already the latest version.",
+        }
+
+    # Run uv tool install
+    log_error(f"Upgrading proxcli from {current} to {latest}...", file=sys.stderr)
+    try:
+        result = subprocess.run(
+            ["uv", "tool", "install", "proxcli", "--reinstall"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode != 0:
+            error_msg = result.stderr.strip() or result.stdout.strip() or f"exit code {result.returncode}"
+            log_error(error_msg)
+            return {
+                "current": current,
+                "latest": latest,
+                "status": "error",
+                "message": f"Upgrade failed: {error_msg}",
+            }
+    except FileNotFoundError:
+        return {
+            "current": current,
+            "latest": latest,
+            "status": "error",
+            "message": "uv not found in PATH. Install uv (https://docs.astral.sh/uv/) or upgrade manually with 'uv tool install proxcli --reinstall'.",
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "current": current,
+            "latest": latest,
+            "status": "error",
+            "message": "Upgrade timed out. Try again or upgrade manually.",
+        }
+
+    new_version = version("proxcli")
+    return {
+        "current": new_version,
+        "previous": current,
+        "latest": latest,
+        "status": "upgraded",
+        "message": f"proxcli upgraded from {current} to {new_version}.",
+    }

{proxcli-0.16.0 → proxcli-0.16.2}/proxmox/cli/vm.py

@@ -186,6 +186,17 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_disk = vm_sub.add_parser("disk", help="Manage VM disks")
     disk_sub = vm_disk.add_subparsers(dest="disk_action", title="disk actions", required=True)
 
+    disk_import = disk_sub.add_parser("import", help="Import a disk image into a VM")
+    disk_import.add_argument("vmid", type=vmid_type, help="VM ID")
+    disk_import.add_argument("--node", help="Node name (auto-detected if omitted)")
+    disk_import.add_argument("--disk", default="scsi0", help="Disk slot to attach to (default: scsi0)")
+    disk_import.add_argument("--storage", default=None, help="Target storage (default: rbd_ssd)")
+    disk_import.add_argument("--image", default=None, dest="image",
+                              help="Path to disk image on the PVE node (e.g. /var/lib/vz/import/deb13.qcow2)")
+    disk_import.add_argument("--url", default=None, dest="image_url",
+                              help="URL to download the disk image from (downloads locally, uploads to PVE, then imports)")
+    disk_import.set_defaults(func=_vm_disk_import)
+
     disk_resize = disk_sub.add_parser("resize", help="Resize a VM disk")
     disk_resize.add_argument("vmid", type=vmid_type, help="VM ID")
     disk_resize.add_argument("--disk", required=True, help="Disk to resize (e.g. scsi0, virtio0)")
@@ -564,6 +575,13 @@ def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     if has_cloudinit and not has_cdrom:
         data["ide2"] = "local:cloudinit,media=cdrom"
 
+    # Auto-configure serial console and VGA for cloud-init VMs
+    if has_cloudinit:
+        if not data.get("serial0"):
+            data["serial0"] = "socket"
+        if not data.get("vga"):
+            data["vga"] = "serial0"
+
     # Validate required fields
     if "memory" not in data:
         return {"error": "--memory is required (or set 'memory:' in the spec file)"}
@@ -885,6 +903,107 @@ def _vm_ip(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
     return ips if ips else {"message": f"No non-local IPs found for VM {args.vmid}"}
 
 
+def _vm_disk_import(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    """Import a disk image into an existing VM.
+
+    Supports two sources:
+    - ``--image``: a path to a disk image already on the PVE node
+      (e.g. /var/lib/vz/import/deb13.qcow2).
+    - ``--url``: downloads the image locally, uploads it to PVE storage,
+      then imports it — all in one command.
+
+    Wraps ``PUT /nodes/{node}/qemu/{vmid}/config`` with
+    ``{disk}: {storage}:0,import-from={path}``.
+    """
+    import os
+    import tempfile
+    import urllib.error
+    import urllib.request
+
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+
+    if not args.image and not args.image_url:
+        return {"error": "Either --image or --url is required"}
+    if args.image and args.image_url:
+        return {"error": "Only one of --image or --url can be specified"}
+
+    disk_slot = args.disk
+    storage = args.storage or "rbd_ssd"
+
+    def _do_import(image_path: str) -> dict:
+        """Attach the disk via import-from and return result."""
+        import_raw = f"{storage}:0,import-from={image_path}"
+        encoded = import_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+
+        from urllib.parse import urlencode
+        body = urlencode({disk_slot: encoded}, safe="%")
+
+        result = client.request("PUT", f"/nodes/{node}/qemu/{args.vmid}/config", content=body)
+        if isinstance(result, dict) and "data" not in result and "error" not in result:
+            result = {"data": result, "vmid": args.vmid, "disk": disk_slot, "image": image_path, "_node": node}
+        return result
+
+    # --- Option A: local image path on PVE node ---
+    if args.image:
+        return _do_import(args.image)
+
+    # --- Option B: URL download + upload + import ---
+    url = args.image_url
+    tmp_path = None
+
+    try:
+        # 1. Download to a temporary file
+        fname = url.rsplit("/", 1)[-1].split("?")[0] or "disk-image.qcow2"
+        with tempfile.NamedTemporaryFile(suffix=f"-{fname}", delete=False) as tmp:
+            tmp_path = tmp.name
+
+        print(f"Downloading {url} ...")
+        try:
+            urllib.request.urlretrieve(url, tmp_path)
+        except urllib.error.URLError as exc:
+            if tmp_path and os.path.isfile(tmp_path):
+                os.unlink(tmp_path)
+            return {"error": f"Failed to download image: {exc}"}
+
+        file_size = os.path.getsize(tmp_path)
+        print(f"Downloaded {fname} ({file_size} bytes)")
+
+        # 2. Upload to PVE storage as 'import' content
+        print(f"Uploading to node {node}, storage {storage} ...")
+        try:
+            upload_result = client.upload(
+                node=node,
+                storage=storage,
+                file_path=tmp_path,
+                content_type="import",
+            )
+        except Exception as exc:
+            return {"error": f"Failed to upload image: {exc}"}
+
+        # Determine the volid from upload response
+        volid = None
+        if isinstance(upload_result, dict):
+            volid = upload_result.get("volid") or upload_result.get("data", {}).get("volid")
+        if not volid:
+            # Fallback: construct volid from storage + filename
+            volid = f"{storage}:import/{fname}"
+
+        print(f"Uploaded as {volid}")
+
+        # 3. Import the uploaded image into the VM
+        print(f"Importing {volid} as {disk_slot} into VM {args.vmid} ...")
+        result = _do_import(volid)
+
+        return {"vmid": args.vmid, "disk": disk_slot, "image": volid, "_node": node, "data": result}
+
+    finally:
+        # Clean up temp file
+        if tmp_path and os.path.isfile(tmp_path):
+            os.unlink(tmp_path)
+
+
 def _vm_disk_resize(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     """Resize a VM disk.
 

{proxcli-0.16.0 → proxcli-0.16.2}/pyproject.toml

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

{proxcli-0.16.0 → proxcli-0.16.2}/uv.lock

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