proxcli 0.9.0__tar.gz → 0.9.1__tar.gz

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

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
 ### Added
@@ -25,6 +34,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 +166,7 @@ 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.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.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.9.0
+Version: 0.9.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.9.0 → proxcli-0.9.1}/TODO.md

@@ -15,6 +15,10 @@ 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).
 
 ## v1.1 — Polish & Usability
 
@@ -34,11 +38,6 @@ Completed items are marked with a check. Implementation notes are preserved for
 - [ ] **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`.
 

proxcli-0.9.1/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.9.1/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)

{proxcli-0.9.0 → proxcli-0.9.1}/proxmox/cli/main.py

@@ -55,16 +55,20 @@ def build_root_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="resource", title="resources", required=False)
 
     # Import and register subcommands
+    from proxmox.cli.acl import register_acl_parser
     from proxmox.cli.auth import register_auth_parser
     from proxmox.cli.cluster import register_cluster_parser
     from proxmox.cli.completion import register_completion_parser
     from proxmox.cli.container import register_container_parser
     from proxmox.cli.node import register_node_parser
     from proxmox.cli.pool import register_pool_parser
+    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.user import register_user_parser
     from proxmox.cli.vm import register_vm_parser
 
+    register_acl_parser(subparsers)
     register_auth_parser(subparsers)
     register_vm_parser(subparsers)
     register_node_parser(subparsers)
@@ -74,6 +78,8 @@ def build_root_parser() -> argparse.ArgumentParser:
     register_cluster_parser(subparsers)
     register_completion_parser(subparsers)
     register_task_parser(subparsers)
+    register_role_parser(subparsers)
+    register_user_parser(subparsers)
 
     return parser
 
@@ -206,7 +212,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 = {"auth", "vm", "node", "pool", "container", "storage", "cluster", "completion", "task"}
+    resources = {"auth", "vm", "node", "pool", "container", "storage", "cluster", "completion", "task", "user", "role", "acl"}
     for i, arg in enumerate(argv):
         if arg in resources:
             resource_pos = i

proxcli-0.9.1/proxmox/cli/role.py

@@ -0,0 +1,78 @@
+"""CLI subcommand for role management (`proxmox role`)."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..client.client import ProxmoxClient
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def _role_list(args: argparse.Namespace, client: ProxmoxClient) -> list | dict:
+    result = client.get("/access/roles")
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict) and "data" in result:
+        return result["data"]
+    return result
+
+
+def _role_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/access/roles/{args.roleid}")
+
+
+def _role_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {"roleid": args.roleid}
+    if args.privs:
+        data["privs"] = args.privs
+    return client.post("/access/roles", data=data)
+
+
+def _role_update(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {}
+    if args.privs:
+        data["privs"] = args.privs
+    if not data:
+        return {"error": "No fields to update"}
+    return client.put(f"/access/roles/{args.roleid}", data=data)
+
+
+def _role_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/access/roles/{args.roleid}")
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+def register_role_parser(subparsers: argparse._SubParsersAction) -> None:
+    role_parser = subparsers.add_parser("role", help="Manage roles")
+    role_sub = role_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # role list
+    role_list = role_sub.add_parser("list", help="List roles")
+    role_list.set_defaults(func=_role_list)
+
+    # role show
+    role_show = role_sub.add_parser("show", help="Show role details")
+    role_show.add_argument("roleid", help="Role ID (e.g. PVEAdmin)")
+    role_show.set_defaults(func=_role_show)
+
+    # role create
+    role_create = role_sub.add_parser("create", help="Create role")
+    role_create.add_argument("roleid", help="Role ID")
+    role_create.add_argument("--privs", help="Comma-separated privilege list")
+    role_create.set_defaults(func=_role_create)
+
+    # role update
+    role_update = role_sub.add_parser("update", help="Update role privileges")
+    role_update.add_argument("roleid", help="Role ID")
+    role_update.add_argument("--privs", help="Comma-separated privilege list")
+    role_update.set_defaults(func=_role_update)
+
+    # role delete
+    role_delete = role_sub.add_parser("delete", help="Delete role")
+    role_delete.add_argument("roleid", help="Role ID")
+    role_delete.set_defaults(func=_role_delete)

proxcli-0.9.1/proxmox/cli/user.py

@@ -0,0 +1,124 @@
+"""CLI subcommand for user management (`proxmox user`)."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..client.client import ProxmoxClient
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def _user_list(args: argparse.Namespace, client: ProxmoxClient) -> list | dict:
+    result = client.get("/access/users")
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict) and "data" in result:
+        return result["data"]
+    return result
+
+
+def _user_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/access/users/{args.userid}")
+
+
+def _user_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {"userid": args.userid}
+    if args.password:
+        data["password"] = args.password
+    if args.email:
+        data["email"] = args.email
+    if args.firstname:
+        data["firstname"] = args.firstname
+    if args.lastname:
+        data["lastname"] = args.lastname
+    if args.enable is False:
+        data["enable"] = 0
+    if args.expire is not None:
+        data["expire"] = args.expire
+    if args.group:
+        data["groups"] = ",".join(args.group)
+    return client.post("/access/users", data=data)
+
+
+def _user_update(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {}
+    if args.password:
+        data["password"] = args.password
+    if args.email:
+        data["email"] = args.email
+    if args.firstname:
+        data["firstname"] = args.firstname
+    if args.lastname:
+        data["lastname"] = args.lastname
+    if args.enable is not False:
+        data["enable"] = 0
+    if args.expire is not None:
+        data["expire"] = args.expire
+    if args.group:
+        data["groups"] = ",".join(args.group)
+    if not data:
+        return {"error": "No fields to update"}
+    return client.put(f"/access/users/{args.userid}", data=data)
+
+
+def _user_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/access/users/{args.userid}")
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+def register_user_parser(subparsers: argparse._SubParsersAction) -> None:
+    user_parser = subparsers.add_parser("user", help="Manage users")
+    user_sub = user_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # user list
+    user_list = user_sub.add_parser("list", help="List users")
+    user_list.set_defaults(func=_user_list)
+
+    # user show
+    user_show = user_sub.add_parser("show", help="Show user details")
+    user_show.add_argument("userid", help="User ID (e.g. xezpeleta@pve)")
+    user_show.set_defaults(func=_user_show)
+
+    # user create
+    user_create = user_sub.add_parser("create", help="Create user")
+    user_create.add_argument("userid", help="User ID (e.g. newuser@pve)")
+    user_create.add_argument("--password", help="User password")
+    user_create.add_argument("--enable", action="store_true", default=True,
+                             help="Enable user (default)")
+    user_create.add_argument("--disable", dest="enable", action="store_false",
+                             help="Disable user account")
+    user_create.add_argument("--firstname", help="First name")
+    user_create.add_argument("--lastname", help="Last name")
+    user_create.add_argument("--email", help="Email address")
+    user_create.add_argument("--expire", type=int, default=0,
+                             help="Account expiration (Unix timestamp, 0 = never)")
+    user_create.add_argument("--group", action="append",
+                             help="Group to add user to (repeatable)")
+    user_create.set_defaults(func=_user_create)
+
+    # user update
+    user_update = user_sub.add_parser("update", help="Update user")
+    user_update.add_argument("userid", help="User ID (e.g. xezpeleta@pve)")
+    user_update.add_argument("--password", help="New password")
+    user_update.add_argument("--enable", action="store_true", default=None,
+                             help="Enable user")
+    user_update.add_argument("--disable", dest="enable", action="store_false",
+                             help="Disable user account")
+    user_update.add_argument("--firstname", help="First name")
+    user_update.add_argument("--lastname", help="Last name")
+    user_update.add_argument("--email", help="Email address")
+    user_update.add_argument("--expire", type=int, default=None,
+                             help="Account expiration (Unix timestamp, 0 = never)")
+    user_update.add_argument("--group", action="append",
+                             help="Group to add user to (repeatable)")
+    user_update.set_defaults(func=_user_update)
+
+    # user delete
+    user_delete = user_sub.add_parser("delete", help="Delete user")
+    user_delete.add_argument("userid", help="User ID (e.g. newuser@pve)")
+    user_delete.set_defaults(func=_user_delete)

{proxcli-0.9.0 → proxcli-0.9.1}/pyproject.toml

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

{proxcli-0.9.0 → proxcli-0.9.1}/uv.lock

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