proxcli 0.1.0__tar.gz → 0.1.1__tar.gz

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

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-06-20
+
+### 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 +32,5 @@ 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.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.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.1.0
+Version: 0.1.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
@@ -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.1.1}/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.1.1/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.1.1}/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.1.1}/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.1/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.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxcli"
-version = "0.1.0"
+version = "0.1.1"
 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.1.1}/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,43 @@ 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

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

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

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