proxcli 0.5.0__tar.gz → 0.7.0__tar.gz

{proxcli-0.5.0 → proxcli-0.7.0}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-20
+
+### Added
+- Task log streaming: `proxmox task log <upid> [--follow]`.
+  Without `--follow`, prints available log lines. With `--follow`,
+  polls every second until the task exits (like `tail -f`).
+  Also added `ProxmoxClient._extract_node_from_upid()` as a static helper.
+
+## [0.6.0] - 2026-06-20
+
+### Added
+- Shell completion support: `proxmox completion bash|zsh|fish`.
+  Generated scripts introspect the parser tree and stay in sync
+  with all registered resources and actions.
+
 ## [0.5.0] - 2026-06-20
 
 ### Added
@@ -67,6 +82,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.7.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.7.0
+[0.6.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.6.0
 [0.5.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.5.0
 [0.4.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.4.0
 [0.3.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.3.0

{proxcli-0.5.0 → proxcli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.5.0
+Version: 0.7.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
@@ -21,7 +21,7 @@ Requires-Dist: pyyaml>=6
 Requires-Dist: rich>=13
 Description-Content-Type: text/markdown
 
-# proxmox
+# proxcli
 
 A CLI tool to interact with [Proxmox VE](https://www.proxmox.com/) nodes and clusters via the REST API.
 
@@ -33,7 +33,7 @@ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 
 ```bash
 # From PyPI
-uv tool install proxmox
+uv tool install proxcli
 
 # From Git
 uv tool install git+https://github.com/xezpeleta/proxcli.git
@@ -51,6 +51,11 @@ proxmox auth login --url https://192.168.1.10:8006 --username root@pam --passwor
 # Or with an API token
 proxmox auth login --url https://192.168.1.10:8006 --username root@pam --api-token 'root@pam!my-token=deadbeef...'
 
+# Enable shell completions
+source <(proxmox completion bash)          # bash
+source <(proxmox completion zsh)           # zsh
+proxmox completion fish | source           # fish  (or save to ~/.config/fish/completions/proxmox.fish)
+
 # Check auth status
 proxmox auth status
 
@@ -129,6 +134,27 @@ proxmox auth status  # Show current auth context
 proxmox auth clear   # Remove saved credentials
 ```
 
+### Completion
+
+```bash
+proxmox completion bash    # Emit bash completion script
+proxmox completion zsh     # Emit zsh completion script
+proxmox completion fish    # Emit fish completion script
+```
+
+Add to your shell's rc file:
+
+```bash
+# bash (~/.bashrc)
+source <(proxmox completion bash)
+
+# zsh (~/.zshrc)
+source <(proxmox completion zsh)
+
+# fish (~/.config/fish/completions/proxmox.fish)
+proxmox completion fish > ~/.config/fish/completions/proxmox.fish
+```
+
 ### VM (QEMU)
 
 ```bash
@@ -250,8 +276,12 @@ proxmox cluster firewall refs [--type alias|ipset|group]
 ```bash
 proxmox task list [--node <node>]
 proxmox task show <upid>
+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`).
+
 ## Output Formats
 
 ### JSON (default)

{proxcli-0.5.0 → proxcli-0.7.0}/README.md

@@ -1,4 +1,4 @@
-# proxmox
+# proxcli
 
 A CLI tool to interact with [Proxmox VE](https://www.proxmox.com/) nodes and clusters via the REST API.
 
@@ -10,7 +10,7 @@ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 
 ```bash
 # From PyPI
-uv tool install proxmox
+uv tool install proxcli
 
 # From Git
 uv tool install git+https://github.com/xezpeleta/proxcli.git
@@ -28,6 +28,11 @@ proxmox auth login --url https://192.168.1.10:8006 --username root@pam --passwor
 # Or with an API token
 proxmox auth login --url https://192.168.1.10:8006 --username root@pam --api-token 'root@pam!my-token=deadbeef...'
 
+# Enable shell completions
+source <(proxmox completion bash)          # bash
+source <(proxmox completion zsh)           # zsh
+proxmox completion fish | source           # fish  (or save to ~/.config/fish/completions/proxmox.fish)
+
 # Check auth status
 proxmox auth status
 
@@ -106,6 +111,27 @@ proxmox auth status  # Show current auth context
 proxmox auth clear   # Remove saved credentials
 ```
 
+### Completion
+
+```bash
+proxmox completion bash    # Emit bash completion script
+proxmox completion zsh     # Emit zsh completion script
+proxmox completion fish    # Emit fish completion script
+```
+
+Add to your shell's rc file:
+
+```bash
+# bash (~/.bashrc)
+source <(proxmox completion bash)
+
+# zsh (~/.zshrc)
+source <(proxmox completion zsh)
+
+# fish (~/.config/fish/completions/proxmox.fish)
+proxmox completion fish > ~/.config/fish/completions/proxmox.fish
+```
+
 ### VM (QEMU)
 
 ```bash
@@ -227,8 +253,12 @@ proxmox cluster firewall refs [--type alias|ipset|group]
 ```bash
 proxmox task list [--node <node>]
 proxmox task show <upid>
+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`).
+
 ## Output Formats
 
 ### JSON (default)

{proxcli-0.5.0 → proxcli-0.7.0}/TODO.md

@@ -2,15 +2,20 @@
 
 Planned improvements for future releases. Items are roughly ordered by priority.
 
+Completed items are marked with a check. Implementation notes are preserved for context.
+
 ---
 
-## v1.1 — Polish & Usability
+## ✅ Done
+
+- [x] **Firewall management** — cluster, node, VM, and container. Options, enable/disable, policy, rules (CRUD), aliases (cluster), ipsets with CIDR mgmt (cluster), refs.
+- [x] **Pool management** — `proxmox pool`: list, show, create, update, delete. Wraps `/pools`.
+- [x] **Shell completions** — `proxmox completion bash|zsh|fish`. Dynamic, introspects the parser tree.
 
-- [ ] **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.
+## v1.1 — Polish & Usability
 
 - [ ] **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).
+  - `proxmox task log <upid> --follow` that streams task output in real time (like `tail -f`). Requires httpx streaming.
 
 - [ ] **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.
@@ -29,17 +34,13 @@ Planned improvements for future releases. Items are roughly ordered by priority.
   - `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`.
+  - `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`.
 
-- [ ] **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.
 

proxcli-0.7.0/proxmox/cli/completion.py

@@ -0,0 +1,214 @@
+"""Shell completion script generation for bash, zsh, and fish."""
+
+from __future__ import annotations
+
+import argparse
+import textwrap
+
+# Each resource has a known list of actions and optional flag completions.
+# We introspect from the parser instead of hardcoding, keeping this DRY.
+
+BASH_SCRIPT = textwrap.dedent("""\
+    _proxmox_completion() {{
+        local cur prev words cword
+        _init_completion || return
+
+        # Global flags
+        local global_flags="--url --username --password --password-stdin --api-token --output --dry-run --insecure --timeout --verbose --version --help"
+
+        # Resources and their actions (autogenerated)
+        declare -A _proxmox_resources
+        {resource_map}
+
+        # If we're at the first positional (after global flags), complete resources
+        if [[ $cword -eq 1 ]] || [[ "${{words[$((cword-1))]}}" =~ ^(--.*) ]]; then
+            COMPREPLY=($(compgen -W "${{!_proxmox_resources[*]}}" -- "$cur"))
+            return
+        fi
+
+        # Find the resource word
+        local resource=""
+        for w in "${{words[@]:1}}"; do
+            if [[ -n "${{_proxmox_resources[$w]}}" ]]; then
+                resource="$w"
+                break
+            fi
+        done
+
+        if [[ -n "$resource" ]]; then
+            local actions="${{_proxmox_resources[$resource]}}"
+            # Complete actions
+            COMPREPLY=($(compgen -W "$actions" -- "$cur"))
+        fi
+    }}
+
+    complete -F _proxmox_completion proxmox
+""")
+
+
+ZSH_SCRIPT = textwrap.dedent("""\
+    #compdef proxmox
+
+    _proxmox() {{
+        local -a resources
+        resources=({resources})
+
+        local -A resource_actions
+        {resource_zsh_map}
+
+        local curcontext="$curcontext" state line
+        typeset -A opt_args
+
+        _arguments -C \\
+            {resource_zsh_flags} \\
+            '1:resource:($resources)' \\
+            '*::arg:->args'
+
+        case $state in
+            args)
+                local resource="$line[1]"
+                if [[ -n "${{resource_actions[$resource]}}" ]]; then
+                    _arguments "*:action:(${{resource_actions[$resource]}})"
+                fi
+                ;;
+        esac
+    }}
+
+    _proxmox "$@"
+""")
+
+
+FISH_SCRIPT = textwrap.dedent("""\
+    function __fish_proxmox_resources
+        echo {resources}
+    end
+
+    function __fish_proxmox_actions
+        set -l resource (commandline -opc)[1]
+        switch $resource
+            {fish_cases}
+        end
+    end
+
+    # Global flags
+    complete -c proxmox -f
+    complete -c proxmox -l url -d 'Proxmox API URL'
+    complete -c proxmox -l username -d 'Username'
+    complete -c proxmox -l password -d 'Password'
+    complete -c proxmox -l password-stdin -d 'Read password from stdin'
+    complete -c proxmox -l api-token -d 'API token'
+    complete -c proxmox -l output -a 'json table yaml' -d 'Output format'
+    complete -c proxmox -l dry-run -d 'Print request without executing'
+    complete -c proxmox -l insecure -d 'Skip TLS verification'
+    complete -c proxmox -l timeout -d 'Request timeout in seconds'
+    complete -c proxmox -l verbose -d 'Enable debug output'
+    complete -c proxmox -l version -d 'Show version'
+    complete -c proxmox -l help -d 'Show help'
+
+    # Resource completion at position 1
+    complete -c proxmox -n 'not __fish_seen_subcommand_from {resources}' \\
+        -a '(__fish_proxmox_resources)'
+
+    # Action completion per resource
+    {fish_action_completions}
+""")
+
+
+def _collect_parser_tree(parser: argparse.ArgumentParser) -> dict[str, list[str]]:
+    """Walk the root parser and collect resource -> action mapping."""
+    resource_actions: dict[str, list[str]] = {}
+
+    for action in parser._actions:
+        if not isinstance(action, argparse._SubParsersAction):
+            continue
+        for name, sub_parser in action.choices.items():
+            sub_actions: list[str] = []
+            for sa in sub_parser._actions:
+                if isinstance(sa, argparse._SubParsersAction):
+                    sub_actions.extend(sa.choices.keys())
+            resource_actions[name] = sorted(sub_actions)
+
+    return resource_actions
+
+
+def generate_bash(parser: argparse.ArgumentParser) -> str:
+    """Generate a bash completion script."""
+    resources = _collect_parser_tree(parser)
+    lines = []
+    for name, actions in sorted(resources.items()):
+        lines.append(f'    _proxmox_resources[{name}]="{ " ".join(actions) }"')
+    return BASH_SCRIPT.format(resource_map="\n".join(lines))
+
+
+def generate_zsh(parser: argparse.ArgumentParser) -> str:
+    """Generate a zsh completion script."""
+    resources = _collect_parser_tree(parser)
+    resources_list = " ".join(sorted(resources.keys()))
+
+    zsh_lines = []
+    for name, actions in sorted(resources.items()):
+        zsh_lines.append(f'    resource_actions[{name}]="{ " ".join(actions) }"')
+
+    return ZSH_SCRIPT.format(
+        resources=resources_list,
+        resource_zsh_map="\n".join(zsh_lines),
+        resource_zsh_flags="",
+    )
+
+
+def generate_fish(parser: argparse.ArgumentParser) -> str:
+    """Generate a fish completion script."""
+    resources = _collect_parser_tree(parser)
+    resources_list = " ".join(sorted(resources.keys()))
+
+    fish_cases = []
+    for name, actions in sorted(resources.items()):
+        fish_cases.append(f"        case {name}\n            echo {' '.join(actions)}")
+
+    fish_completions = []
+    for name, actions in sorted(resources.items()):
+        fish_completions.append(
+            f"complete -c proxmox -n '__fish_seen_subcommand_from {name}' "
+            f"-a '{' '.join(actions)}'"
+        )
+
+    return FISH_SCRIPT.format(
+        resources=resources_list,
+        fish_cases="\n".join(fish_cases),
+        fish_action_completions="\n".join(fish_completions),
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI registration
+# ---------------------------------------------------------------------------
+
+
+def register_completion_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox completion` subcommand."""
+    comp_parser = subparsers.add_parser(
+        "completion", help="Generate shell completion script"
+    )
+    comp_parser.add_argument(
+        "shell",
+        choices=["bash", "zsh", "fish"],
+        help="Target shell",
+    )
+    comp_parser.set_defaults(func=_emit_completion)
+
+
+def _emit_completion(args: argparse.Namespace, _client: object) -> str:
+    """Emit the completion script for the requested shell.
+
+    We need access to the root parser to introspect the subcommand tree,
+    so we import the builder here.
+    """
+    from proxmox.cli.main import build_root_parser
+
+    parser = build_root_parser()
+    generators = {
+        "bash": generate_bash,
+        "zsh": generate_zsh,
+        "fish": generate_fish,
+    }
+    return generators[args.shell](parser)

{proxcli-0.5.0 → proxcli-0.7.0}/proxmox/cli/main.py

@@ -57,6 +57,7 @@ def build_root_parser() -> argparse.ArgumentParser:
     # Import and register subcommands
     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
@@ -71,6 +72,7 @@ def build_root_parser() -> argparse.ArgumentParser:
     register_container_parser(subparsers)
     register_storage_parser(subparsers)
     register_cluster_parser(subparsers)
+    register_completion_parser(subparsers)
     register_task_parser(subparsers)
 
     return parser
@@ -204,13 +206,17 @@ def main(argv: list[str] | None = None) -> None:
         return
 
     try:
-        # auth status and clear don't need a client
-        if args.resource == "auth" and args.action in ("status", "clear"):
+        # auth status, clear, and completion don't need a client
+        if (args.resource == "auth" and args.action in ("status", "clear")) or args.resource == "completion":
             if hasattr(args, "func"):
                 result = args.func(args, None)
                 if result is not None:
-                    output = format_output(result, args.output)
-                    print(output)
+                    if args.resource == "completion":
+                        # Completion scripts are raw shell code, not JSON
+                        print(result)
+                    else:
+                        output = format_output(result, args.output)
+                        print(output)
             return
 
         _, overrides = _merge_config(args)

{proxcli-0.5.0 → proxcli-0.7.0}/proxmox/cli/tasks.py

@@ -22,13 +22,20 @@ def register_task_parser(subparsers: argparse._SubParsersAction) -> None:
     task_show.add_argument("upid", help="Task UPID")
     task_show.set_defaults(func=_task_show)
 
+    # --- task log ---
+    task_log = task_sub.add_parser("log", help="Show task log output")
+    task_log.add_argument("upid", help="Task UPID")
+    task_log.add_argument(
+        "--follow", "-f",
+        action="store_true",
+        help="Follow log output until task completes (like tail -f)",
+    )
+    task_log.set_defaults(func=_task_log)
+
 
 def _extract_node_from_upid(upid: str) -> str | None:
     """Parse node name from a Proxmox UPID string: UPID:{node}:..."""
-    parts = upid.split(":")
-    if len(parts) >= 2:
-        return parts[1]
-    return None
+    return ProxmoxClient._extract_node_from_upid(upid)
 
 
 def _task_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
@@ -63,3 +70,8 @@ def _task_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
     if not node:
         return {"error": f"Could not extract node from UPID: {args.upid}"}
     return client.get(f"/nodes/{node}/tasks/{args.upid}/status")
+
+
+def _task_log(args: argparse.Namespace, client: ProxmoxClient) -> None:
+    """Stream task log (returns None so main.py skips JSON formatting)."""
+    client.stream_task_log(args.upid, follow=args.follow)

{proxcli-0.5.0 → proxcli-0.7.0}/proxmox/client/client.py

@@ -280,3 +280,81 @@ class ProxmoxClient:
             import sys
 
             print(f"[proxmox] {message}", file=sys.stderr)
+
+    # ------------------------------------------------------------------
+    # Task log streaming
+    # ------------------------------------------------------------------
+
+    def stream_task_log(self, upid: str, *, follow: bool = False) -> None:
+        """Stream task log lines to stdout.
+
+        Args:
+            upid: Task UPID string (e.g. UPID:pve01:00000010:...).
+            follow: If True, keep polling until task exits.
+        """
+        import sys
+
+        node = self._extract_node_from_upid(upid)
+        if not node:
+            print(f"Error: could not extract node from UPID: {upid}", file=sys.stderr)
+            return
+
+        if self._dry_run:
+            self._print_dry_run("GET", f"{self._base_url}/api2/json/nodes/{node}/tasks/{upid}/log", None)
+            if follow:
+                print("[dry-run] --follow would poll /tasks/{upid}/status until stopped")
+            return
+
+        start = 0
+        seen_lines: set[int] = set()
+
+        while True:
+            try:
+                log_data = self.request("GET", f"/nodes/{node}/tasks/{upid}/log", params={"start": start})
+            except ProxmoxAPIError:
+                if not follow:
+                    break
+                time.sleep(1)
+                continue
+
+            if isinstance(log_data, dict):
+                log_data = log_data.get("data", []) if "data" in log_data else []
+
+            if isinstance(log_data, list):
+                for entry in log_data:
+                    if not isinstance(entry, dict):
+                        continue
+                    n = entry.get("n", 0)
+                    if n in seen_lines:
+                        continue
+                    seen_lines.add(n)
+                    line = entry.get("t", "")
+                    print(line)
+
+            # Check if task is done
+            if follow:
+                try:
+                    status_data = self.request("GET", f"/nodes/{node}/tasks/{upid}/status")
+                    if isinstance(status_data, dict):
+                        status = status_data.get("status")
+                        if status == "stopped":
+                            exit_code = status_data.get("exitstatus")
+                            if exit_code is not None:
+                                print(f"\nTask completed with exit code: {exit_code}")
+                            break
+                except ProxmoxAPIError:
+                    pass
+
+            if not follow:
+                break
+
+            start = len(seen_lines)
+            time.sleep(1)
+
+    @staticmethod
+    def _extract_node_from_upid(upid: str) -> str | None:
+        """Parse node name from a Proxmox UPID string: UPID:{node}:..."""
+        parts = upid.split(":")
+        if len(parts) >= 2:
+            return parts[1]
+        return None

{proxcli-0.5.0 → proxcli-0.7.0}/pyproject.toml

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

{proxcli-0.5.0 → proxcli-0.7.0}/uv.lock

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