proxcli 0.1.0__tar.gz → 0.2.0__tar.gz

proxcli-0.2.0/.env.example

@@ -0,0 +1,3 @@
+# PyPI publish token
+# Get yours at: https://pypi.org/manage/account/token/
+PYPI_TOKEN=pypi-xxxxxxxxxxxxxxxx

{proxcli-0.1.0 → proxcli-0.2.0}/.gitignore

@@ -9,6 +9,9 @@ wheels/
 # Virtual environments
 .venv
 
+# Environment / secrets
+.env
+
 # IDE / Editor
 *.swp
 *.swo

{proxcli-0.1.0 → proxcli-0.2.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-20
+
+### Added
+- `proxmox storage upload` command for uploading ISO, vztmpl, and import files to storage via multipart/form-data.
+- `ProxmoxClient.upload()` method supporting file uploads with content type selection.
+
+### Changed
+- `proxmox vm create --vmid` and `proxmox container create --vmid` are now optional.
+  The next free VMID is auto-assigned via the `/cluster/nextid` API when omitted.
+
 ## [0.1.0] - 2026-06-20
 
 ### Added
@@ -26,4 +36,6 @@ 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.1.0]: https://github.com/xezpeleta/proxmox-cli/releases/tag/v0.1.0
+[0.2.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.2.0
+[0.1.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.1.1
+[0.1.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.1.0

{proxcli-0.1.0 → proxcli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.1.0
+Version: 0.2.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
@@ -36,7 +36,7 @@ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 uv tool install proxmox
 
 # From Git
-uv tool install git+https://github.com/xezpeleta/proxmox-cli.git
+uv tool install git+https://github.com/xezpeleta/proxcli.git
 
 # From local checkout
 uv tool install .
@@ -238,8 +238,8 @@ proxmox vm show 999 || echo "VM not found"
 
 ```bash
 # Clone
-git clone https://github.com/xezpeleta/proxmox-cli.git
-cd proxmox-cli
+git clone https://github.com/xezpeleta/proxcli.git
+cd proxcli
 
 # Install dev dependencies
 uv sync

{proxcli-0.1.0 → proxcli-0.2.0}/README.md

@@ -13,7 +13,7 @@ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 uv tool install proxmox
 
 # From Git
-uv tool install git+https://github.com/xezpeleta/proxmox-cli.git
+uv tool install git+https://github.com/xezpeleta/proxcli.git
 
 # From local checkout
 uv tool install .
@@ -215,8 +215,8 @@ proxmox vm show 999 || echo "VM not found"
 
 ```bash
 # Clone
-git clone https://github.com/xezpeleta/proxmox-cli.git
-cd proxmox-cli
+git clone https://github.com/xezpeleta/proxcli.git
+cd proxcli
 
 # Install dev dependencies
 uv sync

proxcli-0.2.0/TODO.md

@@ -0,0 +1,85 @@
+# TODO
+
+Planned improvements for future releases. Items are roughly ordered by priority.
+
+---
+
+## v1.1 — Polish & Usability
+
+- [ ] **Shell completions**
+  - Add `proxmox completion bash|zsh|fish` subcommand that emits a completion script. Use argparse's built-in completion or a lightweight generator. Makes tab-completion work for all subcommands and flags.
+
+- [ ] **Streaming task logs (`--follow`)**
+  - `proxmox task log <upid>` that streams task output in real time (like `tail -f`). Requires httpx streaming support (already viable — httpx is the chosen HTTP client).
+
+- [ ] **Startup time optimization**
+  - Current `proxmox --help` takes ~350ms. Lazy-load subcommand modules so only the requested resource's code is imported. Move `import rich`, `import yaml` inside formatter functions. Target: <200ms.
+
+- [ ] **`--output table` column selection**
+  - Allow `proxmox vm list --output table --columns vmid,name,status,mem` to pick which columns appear in the table.
+
+- [ ] **Color support in table output**
+  - Use `rich` styling for status values (green= running, red= stopped, yellow= suspended).
+
+---
+
+## v1.2 — Resource Coverage
+
+- [ ] **Backup (`vzdump`) management**
+  - `proxmox backup` subcommand: `list`, `create`, `show`, `delete`. Wrap `/nodes/{node}/vzdump` and `/nodes/{node}/storage/{storage}/content` for backup files.
+
+- [ ] **User & permission management**
+  - `proxmox user` subcommand: `list`, `show`, `create`, `update`, `delete`. Wraps `/access/users`, `/access/acl`, `/access/roles`.
+
+- [ ] **Pool management**
+  - `proxmox pool` subcommand: `list`, `show`, `create`, `update`, `delete`. Wraps `/pools`.
+
+- [ ] **Network management**
+  - `proxmox network` subcommand: `list`, `show`, `update` for bridges, bonds, VLANs. Wraps `/nodes/{node}/network`.
+
+- [ ] **Firewall management**
+  - `proxmox firewall` subcommand: `list`, `show`, `enable`, `disable`, `create rule`, `delete rule`. Wraps `/nodes/{node}/firewall`, `/cluster/firewall`.
+
+- [ ] **SDN (Software-Defined Networking)**
+  - `proxmox sdn` subcommand: `zones`, `vnets`, `subnets`. Wraps `/cluster/sdn/*` endpoints.
+
+- [ ] **HA (High Availability)**
+  - `proxmox ha` subcommand: `status`, `groups`, `resources`. Wraps `/cluster/ha/*` endpoints.
+
+---
+
+## v2.0 — Multi-Cluster & Advanced
+
+- [ ] **Multi-profile / multi-cluster support**
+  - Support `--profile <name>` global flag to switch between multiple saved Proxmox endpoints. Config file format extended from single endpoint to a profiles dict. `proxmox auth login --profile homelab` and `proxmox auth login --profile work` coexist.
+
+- [ ] **Batch / bulk operations**
+  - `proxmox vm start --all-on-node pve01` (start all VMs on a node). `proxmox vm snapshot --vmid 100,101,102` (apply to multiple IDs).
+
+- [ ] **Config file templating**
+  - Ability to define VM/container specs in a YAML/JSON file and create from it: `proxmox vm create --file my-vm.yaml`.
+
+- [ ] **Plugin system for custom commands**
+  - Allow users to extend the CLI with custom subcommands via a plugins directory.
+
+- [ ] **Dry-run diff mode**
+  - `--dry-run` that shows what *would change* on the Proxmox side (e.g., before/after VM config diff) rather than just the HTTP request.
+
+---
+
+## Ideas (not yet scheduled)
+
+- [ ] **Interactive mode / TUI**
+  - A `proxmox tui` command that opens a terminal UI (like `htop` but for Proxmox resources). Low priority — the CLI is designed for automation first.
+
+- [ ] **Webhook / event listener**
+  - Subscribe to Proxmox cluster events and pipe them to a webhook or stdout for external monitoring.
+
+- [ ] **VM migration wizard**
+  - `proxmox vm migrate <vmid> --to <target-node>` with progress tracking and live migration support.
+
+- [ ] **Proxmox Backup Server (PBS) integration**
+  - Separate subcommand or a companion tool (`proxbackup`?) for managing PBS instances via their API.
+
+- [ ] **Terraform / Pulumi bridge**
+  - Export current Proxmox state as Terraform HCL or Pulumi Python/TypeScript, enabling import into IaC.

{proxcli-0.1.0 → proxcli-0.2.0}/proxmox/cli/container.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import argparse
 
 from proxmox.client.client import ProxmoxClient
-from proxmox.utils.helpers import vmid_type
+from proxmox.utils.helpers import resolve_vmid, vmid_type
 
 
 def register_container_parser(subparsers: argparse._SubParsersAction) -> None:
@@ -27,7 +27,7 @@ def register_container_parser(subparsers: argparse._SubParsersAction) -> None:
     # --- 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("--vmid", type=vmid_type, default=None, help="Container ID (auto-assigned if omitted)")
     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")
@@ -117,7 +117,7 @@ def _ct_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
 
 def _ct_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     data: dict = {
-        "vmid": args.vmid,
+        "vmid": resolve_vmid(client, args.vmid),
         "ostemplate": args.ostemplate,
         "memory": args.memory,
         "cores": args.cores,

{proxcli-0.1.0 → proxcli-0.2.0}/proxmox/cli/storage.py

@@ -28,6 +28,19 @@ def register_storage_parser(subparsers: argparse._SubParsersAction) -> None:
     st_content.add_argument("--node", help="Node name (auto-detected if omitted)")
     st_content.set_defaults(func=_st_content)
 
+    # --- storage upload ---
+    st_upload = st_sub.add_parser("upload", help="Upload a file to storage")
+    st_upload.add_argument("--node", required=True, help="Target node")
+    st_upload.add_argument("--storage", required=True, help="Storage ID (e.g. 'local')")
+    st_upload.add_argument("--file", required=True, help="Path to the local file")
+    st_upload.add_argument(
+        "--content-type",
+        default="iso",
+        choices=["iso", "vztmpl", "import"],
+        help="Content type (default: iso)",
+    )
+    st_upload.set_defaults(func=_st_upload)
+
 
 def _st_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
     if args.node:
@@ -61,3 +74,12 @@ def _st_content(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
     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")
+
+
+def _st_upload(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.upload(
+        node=args.node,
+        storage=args.storage,
+        file_path=args.file,
+        content_type=args.content_type,
+    )

{proxcli-0.1.0 → proxcli-0.2.0}/proxmox/cli/vm.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import argparse
 
 from proxmox.client.client import ProxmoxClient
-from proxmox.utils.helpers import vmid_type
+from proxmox.utils.helpers import resolve_vmid, vmid_type
 
 
 def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
@@ -27,7 +27,7 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     # --- 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("--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)")
@@ -141,7 +141,7 @@ def _vm_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
 
 def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     data: dict = {
-        "vmid": args.vmid,
+        "vmid": resolve_vmid(client, args.vmid),
         "memory": args.memory,
         "cores": args.cores,
     }

{proxcli-0.1.0 → proxcli-0.2.0}/proxmox/client/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import time
 from typing import Any
 
@@ -93,6 +94,70 @@ class ProxmoxClient:
     ) -> dict[str, Any] | list[Any]:
         return self.request("DELETE", path, params=params)
 
+    def upload(
+        self,
+        node: str,
+        storage: str,
+        file_path: str,
+        *,
+        content_type: str = "iso",
+    ) -> dict[str, Any]:
+        """Upload a file to a storage via multipart/form-data.
+
+        Args:
+            node: Target node name.
+            storage: Storage ID (e.g. 'local').
+            file_path: Path to the local file to upload.
+            content_type: Proxmox content type ('iso', 'vztmpl', 'import').
+        """
+        path = f"/nodes/{node}/storage/{storage}/upload"
+        full_url = f"{self._base_url}/api2/json{path}"
+
+        if self._dry_run:
+            print(f"POST {full_url}")
+            print(f"Headers: {self._auth.get_headers()}")
+            print(f"File: {file_path} (content={content_type})")
+            return {}
+
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        filename = os.path.basename(file_path)
+        file_size = os.path.getsize(file_path)
+
+        self._debug(f"POST {full_url}")
+        self._debug(f"  file: {file_path} ({file_size} bytes)")
+
+        headers = self._auth.get_headers()
+
+        with open(file_path, "rb") as f:
+            try:
+                resp = httpx.post(
+                    full_url,
+                    files={"filename": (filename, f, "application/octet-stream")},
+                    data={"content": content_type},
+                    headers=headers,
+                    timeout=self._timeout,
+                    verify=self._verify_tls,
+                )
+            except httpx.RequestError as exc:
+                msg = str(exc)
+                if "SSL" in msg or "certificate" in msg.lower():
+                    msg += "\nHint: use --insecure to skip TLS verification"
+                raise ProxmoxAPIError(0, {"message": msg}, full_url) from exc
+
+        self._debug(f"  ← {resp.status_code}")
+
+        if not (200 <= resp.status_code < 300):
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"message": resp.text}
+            raise ProxmoxAPIError(resp.status_code, body, full_url)
+
+        envelope = resp.json()
+        return envelope.get("data", envelope)
+
     def set_credentials(self, username: str, password: str) -> None:
         """Store credentials for lazy / auto-refresh authentication."""
         self._username = username

proxcli-0.2.0/proxmox/utils/helpers.py

@@ -0,0 +1,32 @@
+"""Shared helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from proxmox.client.client import ProxmoxClient
+
+
+def vmid_type(value: str) -> int:
+    """Argparse type for validating VMID (positive integer)."""
+    try:
+        v = int(value)
+    except ValueError:
+        raise ValueError(f"Invalid VMID '{value}': must be an integer")
+    if v <= 0:
+        raise ValueError(f"Invalid VMID '{value}': must be positive")
+    return v
+
+
+def resolve_vmid(client: ProxmoxClient, vmid: int | None) -> int:
+    """Return *vmid* if provided, otherwise fetch the next free VMID from the cluster."""
+    if vmid is not None and vmid > 0:
+        return vmid
+    result = client.get("/cluster/nextid")
+    if isinstance(result, dict):
+        # Proxmox returns {"data": "<nextid>"} or just "<nextid>" as string
+        raw = result.get("data", result)
+        if isinstance(raw, str):
+            return int(raw)
+    return int(result) if isinstance(result, (str, int)) else 0

{proxcli-0.1.0 → proxcli-0.2.0}/pyproject.toml

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

{proxcli-0.1.0 → proxcli-0.2.0}/tests/test_client.py

@@ -8,6 +8,7 @@ import pytest
 from proxmox.client.auth import AuthManager
 from proxmox.client.client import ProxmoxClient
 from proxmox.client.exceptions import ProxmoxAPIError
+from proxmox.utils.helpers import resolve_vmid
 
 
 class TestProxmoxClient:
@@ -119,3 +120,95 @@ class TestProxmoxClient:
         client = ProxmoxClient("https://pve:8006/", AuthManager())
         result = client.get("/nodes")
         assert result == []
+
+
+class TestResolveVmid:
+    def test_returns_provided_vmid(self, mock_httpx_client):
+        """When a vmid is provided, return it without calling the API."""
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        result = resolve_vmid(client, 110)
+        assert result == 110
+        assert len(mock_httpx_client.get_requests()) == 0
+
+    def test_fetches_nextid_when_vmid_is_none(self, mock_httpx_client):
+        """When vmid is None, call /cluster/nextid."""
+        mock_httpx_client.add_response(
+            url="https://pve:8006/api2/json/cluster/nextid",
+            json={"data": "102"},
+        )
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        result = resolve_vmid(client, None)
+        assert result == 102
+        assert len(mock_httpx_client.get_requests()) == 1
+
+    def test_fetches_nextid_when_vmid_is_zero(self, mock_httpx_client):
+        """When vmid is 0, also fetch nextid (0 is not a valid VMID)."""
+        mock_httpx_client.add_response(
+            url="https://pve:8006/api2/json/cluster/nextid",
+            json={"data": "105"},
+        )
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        result = resolve_vmid(client, 0)
+        assert result == 105
+
+    def test_nextid_returns_integer(self, mock_httpx_client):
+        """Some Proxmox versions return nextid as integer."""
+        mock_httpx_client.add_response(
+            url="https://pve:8006/api2/json/cluster/nextid",
+            json={"data": 108},
+        )
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        result = resolve_vmid(client, None)
+        assert result == 108
+
+
+class TestStorageUpload:
+    def test_upload_success(self, mock_httpx_client, tmp_path):
+        """Upload sends multipart request and returns data."""
+        iso_file = tmp_path / "test.iso"
+        iso_file.write_bytes(b"fake iso content")
+
+        mock_httpx_client.add_response(
+            method="POST",
+            url="https://pve:8006/api2/json/nodes/pve01/storage/local/upload",
+            json={"data": "file test.iso uploaded"},
+        )
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        result = client.upload("pve01", "local", str(iso_file))
+        assert result == "file test.iso uploaded"
+
+        # Verify the request was multipart
+        requests = mock_httpx_client.get_requests()
+        assert len(requests) == 1
+        assert "multipart/form-data" in requests[0].headers.get("content-type", "")
+
+    def test_upload_dry_run(self, capsys):
+        """Upload in dry-run mode prints request without executing."""
+        client = ProxmoxClient("https://pve:8006", AuthManager(), dry_run=True)
+        result = client.upload("pve01", "local", "/fake/path.iso")
+        assert result == {}
+        captured = capsys.readouterr()
+        assert "POST https://pve:8006/api2/json/nodes/pve01/storage/local/upload" in captured.out
+        assert "/fake/path.iso" in captured.out
+
+    def test_upload_file_not_found(self):
+        """Upload raises FileNotFoundError for missing files."""
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        with pytest.raises(FileNotFoundError, match="File not found"):
+            client.upload("pve01", "local", "/nonexistent/file.iso")
+
+    def test_upload_error_response(self, mock_httpx_client, tmp_path):
+        """Upload raises ProxmoxAPIError on non-2xx response."""
+        iso_file = tmp_path / "test.iso"
+        iso_file.write_bytes(b"data")
+
+        mock_httpx_client.add_response(
+            method="POST",
+            url="https://pve:8006/api2/json/nodes/pve01/storage/local/upload",
+            status_code=403,
+            json={"message": "permission denied"},
+        )
+        client = ProxmoxClient("https://pve:8006", AuthManager())
+        with pytest.raises(ProxmoxAPIError) as exc_info:
+            client.upload("pve01", "local", str(iso_file))
+        assert exc_info.value.status_code == 403

{proxcli-0.1.0 → proxcli-0.2.0}/uv.lock

@@ -253,8 +253,8 @@ wheels = [
 ]
 
 [[package]]
-name = "proxmox"
-version = "0.1.0"
+name = "proxcli"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

proxcli-0.1.0/proxmox/utils/helpers.py

@@ -1,14 +0,0 @@
-"""Shared helpers."""
-
-from __future__ import annotations
-
-
-def vmid_type(value: str) -> int:
-    """Argparse type for validating VMID (positive integer)."""
-    try:
-        v = int(value)
-    except ValueError:
-        raise ValueError(f"Invalid VMID '{value}': must be an integer")
-    if v <= 0:
-        raise ValueError(f"Invalid VMID '{value}': must be positive")
-    return v