proxcli 0.5.0__tar.gz → 0.6.0__tar.gz

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.5.0
+Version: 0.6.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
@@ -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

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

@@ -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

proxcli-0.6.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.6.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.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxcli"
-version = "0.5.0"
+version = "0.6.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.6.0}/uv.lock

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