proxcli 0.9.0__tar.gz → 0.10.0__tar.gz

{proxcli-0.9.0 → proxcli-0.10.0}/CHANGELOG.md

@@ -5,7 +5,29 @@ 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).
 
-## [Unreleased]
+## [0.10.0] - 2026-06-20
+
+### Added
+- **Network management**: ``proxmox network`` (list, show).  Wraps
+  ``/nodes/{node}/network[/{iface}]``.  List all network interfaces on a
+  node with optional ``--type`` filtering (bridge, bond, vlan, eth, etc.).
+  Show detailed configuration for a single interface.
+- **Backup (vzdump) management**: ``proxmox backup`` (list, show, create,
+  delete, tasks, defaults).  Wraps ``/nodes/{node}/vzdump`` for creating
+  backups and ``/nodes/{node}/storage/{storage}/content`` for listing
+  and deleting backup files.  Supports snapshot/suspend/stop modes,
+  compression (lzo/zstd), bandwidth limits, prune settings, and PBS
+  Proxmox Backup Server integration.  Backup tasks can be monitored
+  with ``proxmox task log <upid> --follow``.
+
+## [0.9.1] - 2026-06-20
+
+### Added
+- **user, role, and ACL management**: ``proxmox user`` (list, show, create,
+  update, delete), ``proxmox role`` (list, show, create, update, delete),
+  ``proxmox acl`` (list, show, add, delete).  Wraps ``/access/users``,
+  ``/access/roles``, and ``/access/acl`` endpoints.  ACL write operations
+  require ``Permissions.Modify`` (Administrator role).
 
 ## [0.9.0] - 2026-06-20
 
@@ -25,6 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **docs/cloud-init.md**: complete guide on creating and managing
   cloud-init VMs with proxcli, including prerequisites, examples,
   custom user-data, and troubleshooting.
+- **docs/api-permissions.md**: minimum API privilege reference for the
+  cloud-init VM workflow and other proxcli operations.
 
 ## [0.8.2] - 2026-06-20
 
@@ -155,6 +179,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.10.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.10.0
+[0.9.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.9.1
 [0.9.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.9.0
 [0.8.2]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.2
 [0.8.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.1

{proxcli-0.9.0 → proxcli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.9.0
+Version: 0.10.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
@@ -262,6 +262,22 @@ proxmox storage content <storage> [--node <node>]
 proxmox storage upload --node <node> --storage <storage> --file <path> [--content-type iso|vztmpl|import]
 ```
 
+### Network
+
+```bash
+proxmox network list [--node <node>] [--type bridge|bond|eth|vlan|...]
+proxmox network show <iface> [--node <node>]
+```
+
+List and inspect network interfaces (bridges, bonds, VLANs, physical NICs)
+on any node.  Use ``--type`` to filter by interface type.
+
+```
+$ proxmox network list --node sanmarko --type vlan
+vmbr0.10   cidr=192.168.10.14/24   gateway=192.168.10.1
+vmbr0.11   cidr=192.168.11.47/24
+```
+
 ### Pool
 
 ```bash
@@ -311,6 +327,55 @@ proxmox task log <upid> [--follow]
 `proxmox task log --follow` polls `/nodes/{node}/tasks/{upid}/log` every second
 and streams new lines until the task completes (like `tail -f`).
 
+### Backup (vzdump)
+
+```bash
+proxmox backup list [--node <node>] [--storage <storage>] [--vmid <id>]
+proxmox backup show <volid> [--node <node>] [--vmid <id>]
+proxmox backup create [--node <node>] --vmid <id> --storage <storage> \
+    [--mode snapshot|suspend|stop] [--compress 0|1|zstd] \
+    [--bwlimit <kbps>] [--ionice <0-8>] [--prune-backups <spec>]
+proxmox backup delete <volid> [--node <node>]
+proxmox backup tasks [--node <node>] [--limit <n>]
+proxmox backup defaults [--node <node>] [--storage <storage>]
+```
+
+Use `--all` instead of `--vmid` to back up all guests on a node.
+Backup tasks can be monitored with `proxmox task log <upid> --follow`.
+
+### User
+
+```bash
+proxmox user list
+proxmox user show <userid>
+proxmox user create <userid> [--password <pw>] [--email <email>] \
+    [--firstname <name>] [--lastname <name>] [--group <group>] [--disable]
+proxmox user update <userid> [--password <pw>] [--email <email>] [--enable|--disable]
+proxmox user delete <userid>
+```
+
+### Role
+
+```bash
+proxmox role list
+proxmox role show <roleid>
+proxmox role create <roleid> [--privs <priv1,priv2,...>]
+proxmox role update <roleid> [--privs <priv1,priv2,...>]
+proxmox role delete <roleid>
+```
+
+### ACL
+
+```bash
+proxmox acl list
+proxmox acl show <path>
+proxmox acl add <path> --roles <role> [--users <users>] [--groups <groups>] [--tokens <tokens>]
+proxmox acl delete <path> [--roles <role>] [--users <users>] [--groups <groups>]
+```
+
+ACL write operations require the `Permissions.Modify` privilege
+(Administrator role).
+
 ## Output Formats
 
 ### JSON (default)

{proxcli-0.9.0 → proxcli-0.10.0}/README.md

@@ -239,6 +239,22 @@ proxmox storage content <storage> [--node <node>]
 proxmox storage upload --node <node> --storage <storage> --file <path> [--content-type iso|vztmpl|import]
 ```
 
+### Network
+
+```bash
+proxmox network list [--node <node>] [--type bridge|bond|eth|vlan|...]
+proxmox network show <iface> [--node <node>]
+```
+
+List and inspect network interfaces (bridges, bonds, VLANs, physical NICs)
+on any node.  Use ``--type`` to filter by interface type.
+
+```
+$ proxmox network list --node sanmarko --type vlan
+vmbr0.10   cidr=192.168.10.14/24   gateway=192.168.10.1
+vmbr0.11   cidr=192.168.11.47/24
+```
+
 ### Pool
 
 ```bash
@@ -288,6 +304,55 @@ proxmox task log <upid> [--follow]
 `proxmox task log --follow` polls `/nodes/{node}/tasks/{upid}/log` every second
 and streams new lines until the task completes (like `tail -f`).
 
+### Backup (vzdump)
+
+```bash
+proxmox backup list [--node <node>] [--storage <storage>] [--vmid <id>]
+proxmox backup show <volid> [--node <node>] [--vmid <id>]
+proxmox backup create [--node <node>] --vmid <id> --storage <storage> \
+    [--mode snapshot|suspend|stop] [--compress 0|1|zstd] \
+    [--bwlimit <kbps>] [--ionice <0-8>] [--prune-backups <spec>]
+proxmox backup delete <volid> [--node <node>]
+proxmox backup tasks [--node <node>] [--limit <n>]
+proxmox backup defaults [--node <node>] [--storage <storage>]
+```
+
+Use `--all` instead of `--vmid` to back up all guests on a node.
+Backup tasks can be monitored with `proxmox task log <upid> --follow`.
+
+### User
+
+```bash
+proxmox user list
+proxmox user show <userid>
+proxmox user create <userid> [--password <pw>] [--email <email>] \
+    [--firstname <name>] [--lastname <name>] [--group <group>] [--disable]
+proxmox user update <userid> [--password <pw>] [--email <email>] [--enable|--disable]
+proxmox user delete <userid>
+```
+
+### Role
+
+```bash
+proxmox role list
+proxmox role show <roleid>
+proxmox role create <roleid> [--privs <priv1,priv2,...>]
+proxmox role update <roleid> [--privs <priv1,priv2,...>]
+proxmox role delete <roleid>
+```
+
+### ACL
+
+```bash
+proxmox acl list
+proxmox acl show <path>
+proxmox acl add <path> --roles <role> [--users <users>] [--groups <groups>] [--tokens <tokens>]
+proxmox acl delete <path> [--roles <role>] [--users <users>] [--groups <groups>]
+```
+
+ACL write operations require the `Permissions.Modify` privilege
+(Administrator role).
+
 ## Output Formats
 
 ### JSON (default)

{proxcli-0.9.0 → proxcli-0.10.0}/TODO.md

@@ -15,12 +15,15 @@ Completed items are marked with a check. Implementation notes are preserved for
 - [x] **QEMU guest agent interfaces** — `proxmox vm agent interfaces <vmid>`. Wraps `/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces`.
 - [x] **Streaming task logs** — `proxmox task log <upid> [--follow]`. Polls `/nodes/{node}/tasks/{upid}/log`.
 - [x] **Global flag hint** — If user places `--output` / `--dry-run` / etc. after the resource, a hint suggests the correct order.
+- [x] **User & permission management** — `proxmox user` (list/show/create/update/delete), `proxmox role` (list/show/create/update/delete), `proxmox acl` (list/show/add/delete). Wraps `/access/users`, `/access/roles`, `/access/acl`. ACL write requires `Permissions.Modify` (Administrator).
+- [x] **VM cloud-init support** — `vm create` flags for citype, ciuser, cipassword, sshkeys, nameserver, searchdomain, cicustom + auto cloud-init drive creation. `vm cloudinit generate` for regeneration.
+- [x] **VM disk import** — `vm create --import-from <storage:path>` imports an existing disk image as VM boot disk.
+- [x] **Docs** — `docs/cloud-init.md` (cloud-init VM workflow), `docs/api-permissions.md` (minimum API privileges).
+- [x] **Network management** — `proxmox network` (list, show). Wraps `/nodes/{node}/network[/{iface}]`. Shows bridges, bonds, VLANs, physical NICs with config details. Type filtering support.
+- [x] **Backup (vzdump) management** — `proxmox backup` (list/show/create/delete/tasks/defaults). Wraps `/nodes/{node}/vzdump` and storage content endpoints. Supports snapshot/suspend/stop modes, compression, PBS.
 
 ## v1.1 — Polish & Usability
 
-- [ ] **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.
 
@@ -31,17 +34,6 @@ Completed items are marked with a check. Implementation notes are preserved for
 
 ## 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`.
-  - `proxmox role` subcommand: `list`, `show`, `create`, `update`, `delete`.
-  - `proxmox acl` subcommand: `list`, `show`. Wraps `/access/users`, `/access/roles`, `/access/acl`, `/access/groups`.
-
-- [ ] **Network management**
-  - `proxmox network` subcommand: `list`, `show`, `update` for bridges, bonds, VLANs. Wraps `/nodes/{node}/network`.
-
 - [ ] **SDN (Software-Defined Networking)**
   - `proxmox sdn` subcommand: `zones`, `vnets`, `subnets`. Wraps `/cluster/sdn/*` endpoints.
 

proxcli-0.10.0/docs/api-permissions.md

@@ -0,0 +1,153 @@
+# API Token Permissions
+
+proxcli uses the Proxmox VE REST API.  This document describes how to create
+a minimal-permission API token for common workflows.
+
+## Creating an API Token
+
+In the Proxmox VE UI: **Datacenter → Permissions → API Tokens → Add**
+
+1. Select **User**
+2. Enter **Token ID** (e.g. `proxcli`)
+3. Uncheck **Privilege Separation** (for simplicity) or leave it checked
+   if you want to limit the token's permissions
+
+The **Secret** is shown only once — save it immediately.
+
+## Permission Model
+
+Proxmox permissions follow the pattern:
+
+```
+/path/to/resource    PrivilegeName[,PrivilegeName...]
+```
+
+- Paths can be broad (`/`) or specific (`/vms/100`)
+- Privileges are inherited — permissions on `/` propagate to all sub-paths
+- An API token's effective permissions are the **intersection** of:
+  1. The token's own ACLs
+  2. The user's ACLs (if privilege separation is enabled)
+
+## Step-by-Step: Cloud-Init VM Workflow
+
+The complete workflow of uploading a cloud image, creating a VM with
+cloud-init, and starting it uses these endpoints:
+
+| Step | Method | Endpoint | Privilege |
+|------|--------|----------|-----------|
+| 1 | GET | `/cluster/nextid` | `Sys.Audit` |
+| 2 | POST | `/nodes/{node}/storage/{storage}/upload` | `Datastore.AllocateTemplate` |
+| 3 | POST | `/nodes/{node}/qemu` | `VM.Allocate` |
+| 3 | — | (reads imported image from source storage) | `Datastore.Allocate` |
+| 3 | — | (allocates disk on target storage) | `Datastore.AllocateSpace` |
+| 3 | — | (attaches scsi0 disk) | `VM.Config.Disk` |
+| 3 | — | (sets net0) | `VM.Config.Network` |
+| 3 | — | (sets cloud-init: citype, ciuser, sshkeys, etc.) | `VM.Config.Cloudinit` |
+| 3 | — | (sets bios, machine, boot order) | `VM.Config.Options` |
+| 4 | POST | `/nodes/{node}/qemu/{vmid}/status/start` | `VM.PowerMgmt` |
+| 5 | GET | `/nodes/{node}/qemu/{vmid}/status/current` | `VM.Audit` |
+| 5 | GET | `/cluster/resources` | `Sys.Audit` |
+
+## Minimal Role: PVECloudInitAdmin
+
+Create a role with only the 11 required privileges:
+
+```
+Role name: PVECloudInitAdmin
+
+Privileges:
+  Sys.Audit
+  Datastore.Allocate
+  Datastore.AllocateSpace
+  Datastore.AllocateTemplate
+  VM.Allocate
+  VM.Audit
+  VM.Config.Cloudinit
+  VM.Config.Disk
+  VM.Config.Network
+  VM.Config.Options
+  VM.PowerMgmt
+```
+
+### ACLs (broad — covers all storages and VMs)
+
+```
+Add → Path: /
+Add → Path: /storage
+Add → Path: /vms
+```
+
+Assign the `PVECloudInitAdmin` role to all three paths for your user or
+token.  Since permissions inherit, `/vms` covers all VMs and
+`/storage` covers all storages.
+
+### ACLs (narrow — single storage, single node)
+
+If you know exactly which storages you'll use, lock it down further:
+
+```
+Path: /                          Role: PVECloudInitAdmin (only for Sys.Audit)
+Path: /storage/local            Role: PVECloudInitAdmin (for upload + import)
+Path: /storage/rbd_ssd           Role: PVECloudInitAdmin (for disk allocation)
+Path: /vms                       Role: PVECloudInitAdmin (for VM operations)
+```
+
+Or even narrower per-VM:
+
+```
+Path: /vms/100-199              Role: PVECloudInitAdmin
+```
+
+## Additional Privileges for Other Workflows
+
+| Feature | Extra Privileges |
+|---------|-----------------|
+| Snapshots | `VM.Snapshot`, `VM.Snapshot.Rollback` |
+| Clone VM | `VM.Clone` |
+| Change memory/CPU | `VM.Config.Memory`, `VM.Config.CPU` |
+| Attach ISOs | `VM.Config.CDROM` |
+| Migrate VM | `VM.Migrate` |
+| Backup VM | `VM.Backup` |
+| Delete VM | `VM.Allocate` (already included), `Datastore.AllocateSpace` |
+| QEMU guest agent | `VM.GuestAgent.Audit`, `VM.GuestAgent.FileRead` |
+| Containers | `VM.Allocate` (LXC creation), `VM.Audit`, `VM.PowerMgmt` |
+| Pools | `Pool.Allocate`, `Pool.Audit` |
+| Cluster firewall | `Sys.Modify`, `Sys.Audit` |
+| Node firewall | `Sys.Modify` |
+| VM firewall | `VM.Allocate` (already included) |
+| ACL management | `Permissions.Modify` (Administrator role) |
+
+## Full Admin Role (for comparison)
+
+The built-in **PVEVMAdmin** role includes:
+
+```
+VM.Allocate, VM.Audit, VM.Backup, VM.Clone, VM.Config.CDROM,
+VM.Config.Cloudinit, VM.Config.CPU, VM.Config.Disk, VM.Config.HWType,
+VM.Config.Memory, VM.Config.Network, VM.Config.Options, VM.Console,
+VM.Migrate, VM.Monitor, VM.PowerMgmt, VM.Snapshot, VM.Snapshot.Rollback
+```
+
+The built-in **PVEDatastoreAdmin** adds:
+
+```
+Datastore.Allocate, Datastore.AllocateSpace, Datastore.AllocateTemplate,
+Datastore.Audit, Datastore.Copy
+```
+
+## Verifying Permissions
+
+Check your current effective permissions:
+
+```bash
+proxmox auth permissions
+```
+
+Or test a specific action with dry-run:
+
+```bash
+proxmox --dry-run vm create --node <node> --memory 512 --cores 1
+```
+
+The dry-run output shows the exact endpoint and HTTP method — if any
+privilege is missing, Proxmox will return a **403 Forbidden**.

proxcli-0.10.0/proxmox/cli/acl.py

@@ -0,0 +1,95 @@
+"""CLI subcommand for ACL management (`proxmox acl`)."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..client.client import ProxmoxClient
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def _acl_list(args: argparse.Namespace, client: ProxmoxClient) -> list | dict:
+    result = client.get("/access/acl")
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict) and "data" in result:
+        return result["data"]
+    return result
+
+
+def _acl_show(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    params = {"path": args.path}
+    result = client.get("/access/acl", params=params)
+    if isinstance(result, dict) and "data" in result:
+        return result["data"]
+    return result
+
+
+def _acl_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {
+        "path": args.path,
+        "roles": args.roles,
+    }
+    if args.users:
+        data["users"] = args.users
+    if args.groups:
+        data["groups"] = args.groups
+    if args.tokens:
+        data["tokens"] = args.tokens
+    if args.propagate is False:
+        data["propagate"] = 0
+    return client.put("/access/acl", data=data)
+
+
+def _acl_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {"path": args.path}
+    if args.roles:
+        data["roles"] = args.roles
+    if args.users:
+        data["users"] = args.users
+    if args.groups:
+        data["groups"] = args.groups
+    if args.tokens:
+        data["tokens"] = args.tokens
+    return client.put("/access/acl", data={"delete": 1, **data})
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+def register_acl_parser(subparsers: argparse._SubParsersAction) -> None:
+    acl_parser = subparsers.add_parser("acl", help="Manage ACLs")
+    acl_sub = acl_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # acl list
+    acl_list = acl_sub.add_parser("list", help="List all ACLs")
+    acl_list.set_defaults(func=_acl_list)
+
+    # acl show
+    acl_show = acl_sub.add_parser("show", help="Show ACLs for a path")
+    acl_show.add_argument("path", help="ACL path (e.g. /vms/100)")
+    acl_show.set_defaults(func=_acl_show)
+
+    # acl create
+    acl_create = acl_sub.add_parser("add", help="Add ACL entry")
+    acl_create.add_argument("path", help="ACL path (e.g. /vms)")
+    acl_create.add_argument("--roles", help="Comma-separated role IDs")
+    acl_create.add_argument("--users", help="Comma-separated user IDs")
+    acl_create.add_argument("--groups", help="Comma-separated group IDs")
+    acl_create.add_argument("--tokens", help="Comma-separated token IDs")
+    acl_create.add_argument("--no-propagate", dest="propagate", action="store_false",
+                            default=True,
+                            help="Disable permission propagation to children")
+    acl_create.set_defaults(func=_acl_create)
+
+    # acl delete
+    acl_delete = acl_sub.add_parser("delete", help="Remove ACL entry")
+    acl_delete.add_argument("path", help="ACL path (e.g. /vms)")
+    acl_delete.add_argument("--roles", help="Comma-separated role IDs")
+    acl_delete.add_argument("--users", help="Comma-separated user IDs")
+    acl_delete.add_argument("--groups", help="Comma-separated group IDs")
+    acl_delete.add_argument("--tokens", help="Comma-separated token IDs")
+    acl_delete.set_defaults(func=_acl_delete)