proxcli 0.8.2__tar.gz → 0.9.1__tar.gz

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

@@ -7,6 +7,36 @@ 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
+- **vm create cloud-init support**: ``--citype``, ``--ciuser``,
+  ``--cipassword``, ``--sshkeys`` (file path or inline),
+  ``--nameserver``, ``--searchdomain``, ``--cicustom``.
+- **vm create --import-from**: import an existing disk image from storage
+  as the VM's boot disk (e.g. ``--import-from local:import/deb12.qcow2``).
+  Requires a Proxmox storage with ``images`` or ``import`` content types.
+- **vm cloud-init drive auto-creation**: when cloud-init flags are used
+  on ``vm create``, an ``ide2`` cloud-init drive is automatically attached.
+  Proxmox VE 9 regenerates the ISO on config change — no separate generate step.
+- **vm cloudinit generate**: re-submits the current ``citype`` to trigger
+  regeneration.  Adapted for Proxmox VE 9 which removed the
+  ``POST /cloudinit`` endpoint.
+- **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
 
 ### Added
@@ -136,6 +166,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.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
 [0.8.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.0

{proxcli-0.8.2 → proxcli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.8.2
+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.8.2 → 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/docs/cloud-init.md

@@ -0,0 +1,255 @@
+# Cloud-Init VM Management with proxcli
+
+Cloud-init allows you to create and fully configure VMs declaratively — users,
+SSH keys, networking, and packages are defined via `proxcli` flags rather than
+manual post-install steps.
+
+## Prerequisites
+
+### 1. Storage with `images` and `import` content types
+
+You need a Proxmox storage that supports both `images` (for VM disks) and
+`import` (for uploading disk images).  On Proxmox VE, edit the storage in
+**Datacenter → Storage → Edit** and add the content types:
+
+- `Disk image` — to store VM disks
+- `ISO image` — optional, if you also want to store ISOs there
+
+Example: a `dir` type storage with path `/var/lib/vz` that has `images`, `iso`,
+and `import` enabled.
+
+Verify with:
+```bash
+proxmox storage list
+```
+
+Look for a storage where `content` includes `images` and (for uploads) `import`.
+
+### 2. Download a cloud-init image
+
+Cloud images are pre-built OS images with cloud-init installed.  You can find
+them at:
+
+- **Debian**: https://cloud.debian.org/images/cloud/bookworm/latest/
+  - File: `debian-12-genericcloud-amd64.qcow2` (333 MB)
+- **Ubuntu**: https://cloud-images.ubuntu.com/releases/24.04/release/
+  - File: `ubuntu-24.04-server-cloudimg-amd64.img` (593 MB)
+
+```bash
+# Download examples
+curl -LO https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
+curl -LO https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64.img
+```
+
+### 3. Upload the image to Proxmox storage
+
+```bash
+proxmox storage upload \
+  --node <node> \
+  --storage <storage> \
+  --content-type import \
+  --file debian-12-genericcloud-amd64.qcow2
+```
+
+After upload, the image will be available as `<storage>:import/<filename>`.
+You can verify with:
+
+```bash
+proxmox storage content <storage> --node <node>
+```
+
+---
+
+## Creating a Cloud-Init VM
+
+The complete workflow is a **single `vm create` command** — Proxmox handles
+disk import, cloud-init drive creation, and ISO generation automatically:
+
+```bash
+proxmox vm create \
+  --node sanmarko \
+  --memory 4096 \
+  --cores 2 \
+  --name my-cloud-vm \
+  --import-from local:import/debian-12-genericcloud-amd64.qcow2 \
+  --citype nocloud \
+  --ciuser debian \
+  --cipassword 'SecurePassword123!' \
+  --sshkeys ~/.ssh/id_rsa.pub \
+  --nameserver 1.1.1.1 \
+  --searchdomain mydomain.lan \
+  --net 'virtio,bridge=vmbr0'
+```
+
+### Flag reference
+
+| Flag | Description |
+|------|-------------|
+| `--import-from <storage:path>` | Import the boot disk from an existing volume |
+| `--citype nocloud\|configdrive2` | Cloud-init data source type |
+| `--ciuser <username>` | Default user (e.g. `debian`, `ubuntu`) |
+| `--cipassword <password>` | User password (hashed by cloud-init) |
+| `--sshkeys <file\|inline>` | SSH public keys (reads file if it exists, otherwise uses inline) |
+| `--nameserver <ip>` | DNS server |
+| `--searchdomain <domain>` | DNS search domain |
+| `--cicustom <config>` | Custom cloud-init config (`user=...,vendor=...`) |
+| `--storage <name>` | Target storage for the imported disk (defaults to `rbd_ssd`) |
+
+### What happens
+
+1. Proxmox assigns a VM ID (or use `--vmid` to specify)
+2. The cloud image is **streamed from the import storage to the target storage**
+   and attached as `scsi0`
+3. A cloud-init drive is created (`ide2`) with the configured user, password,
+   SSH keys, and network settings
+4. The VM is created in *stopped* state, ready to start
+
+### Verify the configuration
+
+```bash
+proxmox vm show <vmid>
+```
+
+The output includes:
+- `scsi0` pointing to the imported disk on the target storage
+- `citype`, `ciuser`, `cipassword`, `nameserver`, etc.
+- `ide2` with the cloud-init ISO
+
+---
+
+## Managing Cloud-Init VMs
+
+### Updating cloud-init configuration
+
+After the VM is created, you can update cloud-init parameters using
+`PUT /nodes/{node}/qemu/{vmid}/config` (no dedicated proxcli command yet):
+
+```bash
+# Currently via curl; a proxcli vm update command is planned
+# This triggers automatic cloud-init ISO regeneration in Proxmox VE 9
+```
+
+In Proxmox VE 9+, the cloud-init ISO is **regenerated automatically** whenever
+cloud-init config parameters change.  There is no separate "generate" step.
+
+### Dumping current cloud-init config
+
+```bash
+proxmox vm cloudinit generate <vmid>
+```
+
+This reads the current `citype` from the VM config and re-submits it to
+trigger regeneration.  (In Proxmox VE 9, config changes auto-regenerate,
+but this command is provided for environments where explicit generation
+is needed.)
+
+### Starting the VM
+
+```bash
+proxmox vm start <vmid>
+```
+
+On first boot, cloud-init will:
+1. Set the hostname
+2. Create the specified user with the given password
+3. Install the SSH keys
+4. Configure networking
+5. Run any `#cloud-config` directives (if using `--cicustom`)
+
+---
+
+## Complete Example: Debian 12 Cloud VM
+
+```bash
+# 1. Upload the cloud image (one-time)
+proxmox storage upload \
+  --node sanmarko --storage local --content-type import \
+  --file debian-12-genericcloud-amd64.qcow2
+
+# 2. Create the VM
+proxmox vm create \
+  --node sanmarko \
+  --name webserver \
+  --memory 4096 --cores 2 \
+  --import-from local:import/debian-12-genericcloud-amd64.qcow2 \
+  --citype nocloud \
+  --ciuser debian \
+  --cipassword 'ChangeMe123!' \
+  --sshkeys ~/.ssh/id_rsa.pub \
+  --nameserver 1.1.1.1 \
+  --searchdomain tknika.net \
+  --net 'virtio,bridge=vmbr0'
+
+# 3. Start it
+proxmox vm start <vmid>
+
+# 4. SSH in (after boot completes)
+ssh debian@<ip>
+```
+
+---
+
+## Custom Cloud-Init Config
+
+For advanced customization (packages, runcmd, write_files), use `--cicustom`
+with a user-data YAML file:
+
+```bash
+proxmox vm create \
+  ... \
+  --cicustom 'user=local:snippets/user-data.yaml'
+```
+
+Upload the snippet first:
+```bash
+proxmox storage upload \
+  --node sanmarko --storage local --content-type snippets \
+  --file user-data.yaml
+```
+
+Example `user-data.yaml`:
+```yaml
+#cloud-config
+packages:
+  - nginx
+  - htop
+  - curl
+
+package_update: true
+package_upgrade: true
+
+runcmd:
+  - systemctl enable --now nginx
+  - echo "Hello from cloud-init" > /etc/motd
+```
+
+---
+
+## Troubleshooting
+
+### "storage does not support 'import' content"
+
+Your storage only has `iso` or `images` enabled.  Go to **Datacenter → Storage**
+in the Proxmox UI and add `Disk image` and `Import` content types to the storage.
+
+### "has wrong type 'iso' - needs to be 'images' or 'import'"
+
+You uploaded the image with `--content-type iso` instead of `--content-type import`.
+Re-upload with the correct content type, or change the storage's content types.
+
+### "Only root can pass arbitrary filesystem paths"
+
+The `import-from` parameter uses a **volume ID** (`local:import/file.qcow2`),
+not a filesystem path (`/var/lib/vz/...`).  Make sure the image is uploaded to
+Proxmox storage first via `storage upload`.
+
+### Cloud-init not running on boot
+
+Check that the cloud-init drive is attached:
+```bash
+proxmox vm show <vmid>
+# Look for: ide2: local:XXX/vm-XXX-cloudinit.qcow2,media=cdrom
+```
+
+If missing, the cloud-init drive wasn't created.  This happens when no
+cloud-init flags (`--ciuser`, `--citype`, etc.) are passed to `vm create`.

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.8.2 → 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.8.2 → proxcli-0.9.1}/proxmox/cli/vm.py

@@ -44,6 +44,16 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_create.add_argument("--machine", default=None, help="Machine type (e.g. q35)")
     vm_create.add_argument("--boot", default=None, help="Boot order (e.g. order=cd;net)")
     vm_create.add_argument("--disk", default=None, help="Disk size (e.g. 32G). Uses --storage if set, else local-lvm.")
+    vm_create.add_argument("--citype", default=None, choices=["nocloud", "configdrive2"],
+                           help="Cloud-init type")
+    vm_create.add_argument("--ciuser", default=None, help="Cloud-init user")
+    vm_create.add_argument("--cipassword", default=None, help="Cloud-init password")
+    vm_create.add_argument("--sshkeys", default=None, help="Cloud-init SSH public keys (file path or inline)")
+    vm_create.add_argument("--nameserver", default=None, help="Cloud-init DNS server")
+    vm_create.add_argument("--searchdomain", default=None, help="Cloud-init DNS search domain")
+    vm_create.add_argument("--cicustom", default=None, help="Cloud-init custom config (user=...,vendor=...)")
+    vm_create.add_argument("--import-from", default=None, dest="import_from",
+                           help="Import disk from existing volume (e.g. local:import/deb12.qcow2)")
     vm_create.set_defaults(func=_vm_create)
 
     # --- vm start ---
@@ -133,6 +143,15 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     agent_ifaces.add_argument("--node", help="Node name (auto-detected if omitted)")
     agent_ifaces.set_defaults(func=_vm_agent_interfaces)
 
+    # --- cloudinit ---
+    cloudinit = vm_sub.add_parser("cloudinit", help="Manage cloud-init")
+    cloudinit_sub = cloudinit.add_subparsers(dest="cloudinit_action", title="cloud-init actions", required=True)
+
+    ci_generate = cloudinit_sub.add_parser("generate", help="Regenerate cloud-init ISO from current config")
+    ci_generate.add_argument("vmid", type=vmid_type, help="VM ID")
+    ci_generate.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ci_generate.set_defaults(func=_vm_cloudinit_generate)
+
     # --- firewall ---
     fw = vm_sub.add_parser("firewall", help="Manage VM firewall")
     fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
@@ -312,6 +331,46 @@ def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
         else:
             disk_raw = args.disk
         data["scsi0"] = disk_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+    elif args.import_from:
+        # Import from existing volume: storage_id=0,import-from=<volid>
+        parts = args.import_from.split(":", 1)
+        if len(parts) == 2:
+            src_storage, src_file = parts
+        else:
+            return {"error": f"Invalid import-from format: {args.import_from}. Use <storage>:<path>"}
+        # Build: dst_storage:0,import-from=src_storage:path
+        target_storage = args.storage or "rbd_ssd"
+        import_raw = f"{target_storage}:0,import-from={args.import_from}"
+        data["scsi0"] = import_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+
+    # Cloud-init
+    cloudinit_used = bool(args.citype or args.ciuser or args.cipassword or args.sshkeys
+                        or args.nameserver or args.searchdomain or args.cicustom)
+    if args.citype:
+        data["citype"] = args.citype
+    if args.ciuser:
+        data["ciuser"] = args.ciuser
+    if args.cipassword:
+        data["cipassword"] = args.cipassword
+    if args.nameserver:
+        data["nameserver"] = args.nameserver
+    if args.searchdomain:
+        data["searchdomain"] = args.searchdomain
+    if args.cicustom:
+        data["cicustom"] = args.cicustom
+    if args.sshkeys:
+        # sshkeys can be a file path or inline content
+        try:
+            with open(args.sshkeys) as f:
+                sshkeys_value = f.read().strip()
+        except (OSError, FileNotFoundError):
+            sshkeys_value = args.sshkeys
+        # URL-encode the SSH keys for form body
+        # Replace newlines with %0A
+        data["sshkeys"] = sshkeys_value.replace("\n", "%0A").replace("\r", "%0D").replace("=", "%3D").replace(",", "%2C").replace(":", "%3A")
+    # Add cloud-init drive if cloud-init is being used and no cdrom is set
+    if cloudinit_used and not args.cdrom:
+        data["ide2"] = "local:cloudinit,media=cdrom"
 
     # Build form-encoded body manually — httpx's data= would double-encode %
     from urllib.parse import urlencode
@@ -396,6 +455,34 @@ def _vm_agent_interfaces(args: argparse.Namespace, client: ProxmoxClient) -> dic
     return result
 
 
+# ---------------------------------------------------------------------------
+# VM cloud-init handlers
+# ---------------------------------------------------------------------------
+
+def _vm_cloudinit_generate(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    """Regenerate the cloud-init ISO from the VM's current cloud-init config.
+
+    In Proxmox VE 9, cloud-init ISOs are regenerated automatically when
+    config changes. This triggers regeneration by re-setting the citype.
+    """
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    # Proxmox VE 9 regenerates cloud-init on config change.
+    # Re-submit the current citype to trigger regeneration.
+    config = client.get(f"/nodes/{node}/qemu/{args.vmid}/config")
+    if not isinstance(config, dict):
+        return {"error": f"Could not read config for VM {args.vmid}"}
+    citype = config.get("citype")
+    if not citype:
+        return {"error": f"VM {args.vmid} has no cloud-init configured (missing citype)"}
+    result = client.put(
+        f"/nodes/{node}/qemu/{args.vmid}/config",
+        data={"citype": citype},
+    )
+    return {"data": result} if isinstance(result, (str, type(None))) or not isinstance(result, dict) else result
+
+
 # ---------------------------------------------------------------------------
 # VM snapshot handlers
 # ---------------------------------------------------------------------------

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

@@ -1,6 +1,6 @@
 [project]
 name = "proxcli"
-version = "0.8.2"
+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.8.2 → proxcli-0.9.1}/uv.lock

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