proxcli 0.2.0__tar.gz → 0.3.0__tar.gz

{proxcli-0.2.0 → proxcli-0.3.0}/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+      - uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
         with:
           enable-cache: true
 
@@ -27,7 +27,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+      - uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
         with:
           enable-cache: true
 
@@ -41,7 +41,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+      - uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
         with:
           enable-cache: true
 
@@ -52,3 +52,22 @@ jobs:
         with:
           name: dist
           path: dist/
+
+  publish:
+    runs-on: ubuntu-24.04
+    if: github.ref == 'refs/heads/main'
+    needs: [build]
+    environment: pypi
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+        with:
+          enable-cache: true
+
+      - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
+        with:
+          name: dist
+          path: dist/
+
+      - run: uv publish --token "${{ secrets.PYPI_TOKEN }}"

proxcli-0.3.0/AGENTS.md

@@ -0,0 +1,123 @@
+# Agent Guidelines for proxmox CLI
+
+## CLI Command Convention
+
+All commands follow a strict **`<resource> <action> [positional_id] [--flags]`** pattern:
+
+```
+proxmox <resource> <action> [id_or_name] [--options]
+```
+
+### Resource-level (top-level subcommands)
+
+Every resource is a noun: `vm`, `container`, `node`, `storage`, `cluster`, `task`, `auth`.
+
+Each has actions as verbs: `list`, `show`, `create`, `start`, `stop`, `delete`, etc.
+
+```
+proxmox vm list
+proxmox vm show 100
+proxmox vm start 100
+proxmox node show pve01
+proxmox container list
+```
+
+### Nested resources (firewall, etc.)
+
+When a resource has sub-resources, use the same **`<resource> <action> <subresource> [subaction]`** pattern:
+
+```
+proxmox cluster firewall rules                         # list (shorthand)
+proxmox cluster firewall rules list                    # list (explicit)
+proxmox cluster firewall rules add --action ACCEPT ...
+proxmox cluster firewall rules show <pos>
+proxmox cluster firewall rules delete <pos>
+proxmox vm firewall rules list <vmid>
+proxmox vm firewall rules add <vmid> --action ACCEPT ...
+proxmox node firewall rules list <node_name>
+proxmox node firewall rules add <node_name> --action ACCEPT ...
+proxmox cluster firewall aliases                       # list (shorthand)
+proxmox cluster firewall aliases add <name> --cidr ...
+proxmox cluster firewall ipsets                        # list (shorthand)
+proxmox cluster firewall ipsets add <name> ...
+```
+
+### Key rules
+
+1. **Nouns before verbs** — `proxmox vm firewall rules list`, NOT `proxmox vm firewall list-rules`.
+2. **Resource identifiers are positional arguments**, placed after the action verb:
+   - `proxmox vm show 100` (vmid is positional)
+   - `proxmox node show pve01` (node_name is positional)
+   - `proxmox vm firewall rules show 100 3` (vmid then pos)
+3. **`--node` is always an optional flag** for VM/container commands (auto-detected if omitted), except on `create` where it's required.
+4. **No shorthand noun squeezing** — `proxmox vm fw` is NOT acceptable. Always use full resource names.
+5. **Subcommands inherit `--flags` from parents** via `set_defaults(func=handler)`. Each handler function receives the merged `Namespace`.
+
+## Parser Registration
+
+Each CLI module has a `register_<resource>_parser(subparsers)` function that adds subparsers to the passed-in `_SubParsersAction`. Example:
+
+```python
+def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
+    vm_parser = subparsers.add_parser("vm", help="Manage QEMU virtual machines")
+    vm_sub = vm_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    vm_list = vm_sub.add_parser("list", help="List virtual machines")
+    vm_list.add_argument("--node", help="Filter by node name")
+    vm_list.set_defaults(func=_vm_list)
+```
+
+For nested resources (like firewall), use a second `dest` name to track the sub-resource:
+
+```python
+fw = vm_sub.add_parser("firewall", help="Manage VM firewall")
+fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
+
+rules = fw_sub.add_parser("rules", help="Manage VM firewall rules")
+rules_sub = rules.add_subparsers(dest="fw_action", title="rule actions", required=False)
+rules_list = rules_sub.add_parser("list", help="List rules")
+rules_list.add_argument("vmid", type=vmid_type, help="VM ID")
+rules_list.set_defaults(func=_vm_fw_rules)
+```
+
+## Handler Functions
+
+Every handler has the signature:
+
+```python
+def _handler(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+```
+
+- `args` contains all parsed arguments (global + resource-specific)
+- `client` is the authenticated `ProxmoxClient` instance
+- Returns a dict or list that will be formatted by the output system
+- For errors, return `{"error": "message"}` dict
+
+## Shared Helpers
+
+Shared argument definitions go in helper modules (e.g., `firewall_helpers.py`). They export two functions:
+
+```python
+def add_firewall_rule_args(parser: argparse.ArgumentParser) -> None:
+    """Add common rule-form arguments to a parser."""
+
+def build_rule_data(args: argparse.Namespace) -> dict[str, Any]:
+    """Convert parsed args into the POST/PUT body dict."""
+```
+
+## Testing
+
+- Unit tests use `pytest-httpx` to mock API responses
+- Integration tests use `subprocess.run` to invoke the CLI binary
+- Dry-run tests verify the URL, method, and body without real network calls
+
+## Versioning
+
+The version string is read from `importlib.metadata.version('proxcli')` — never hardcoded in source.
+
+## PyPI
+
+- Package name: `proxcli`
+- CLI binary: `proxmox`
+- Publish via `uv publish --token $PYPI_TOKEN`
+- CI auto-publishes on push to `main` (after lint + test + build)

{proxcli-0.2.0 → proxcli-0.3.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-20
+
+### Added
+- Cluster firewall management: options, enable/disable, policy, rules (CRUD), aliases, ipsets (with CIDR management), refs.
+- Node firewall management: options, enable/disable, policy, rules (CRUD), refs.
+- VM firewall management: options, enable/disable, policy, rules (CRUD), refs.
+- Shared `firewall_helpers.py` for consistent rule argument building across all levels.
+- CI `publish` job: auto-publishes to PyPI on push to main (uses `PYPI_TOKEN` repo secret with `environment: pypi`).
+- `AGENTS.md` with CLI convention and contribution guidelines.
+
+### Changed
+- Removed `.env` file with PyPI token; now uses GitHub Actions secrets.
+- Firewall subcommands refactored to consistent `<resource> <action> <subresource> [subaction]` pattern.
+
+## [0.2.1] - 2026-06-20
+
+### Fixed
+- `--version` now reads from installed package metadata (`importlib.metadata`) instead of a hardcoded string.
+
 ## [0.2.0] - 2026-06-20
 
 ### Added
@@ -36,6 +55,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.3.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.3.0
+[0.2.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.2.1
 [0.2.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.2.0
 [0.1.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.1.1
 [0.1.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.1.0

{proxcli-0.2.0 → proxcli-0.3.0}/PKG-INFO

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

proxcli-0.3.0/proxmox/cli/cluster.py

@@ -0,0 +1,239 @@
+"""`proxmox cluster` subcommand — cluster management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.cli.firewall_helpers import add_firewall_rule_args, build_rule_data
+from proxmox.client.client import ProxmoxClient
+
+
+def register_cluster_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox cluster` subcommand tree."""
+    cl_parser = subparsers.add_parser("cluster", help="Manage Proxmox cluster")
+    cl_sub = cl_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- cluster status ---
+    cl_status = cl_sub.add_parser("status", help="Show cluster status")
+    cl_status.set_defaults(func=_cl_status)
+
+    # --- firewall ---
+    fw = cl_sub.add_parser("firewall", help="Manage cluster firewall")
+    fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
+
+    # firewall options
+    fw_opts = fw_sub.add_parser("options", help="Show cluster firewall options")
+    fw_opts.set_defaults(func=_cl_fw_options)
+
+    fw_opts_set = fw_sub.add_parser("enable", help="Enable cluster firewall")
+    fw_opts_set.set_defaults(func=_cl_fw_enable)
+
+    fw_opts_disable = fw_sub.add_parser("disable", help="Disable cluster firewall")
+    fw_opts_disable.set_defaults(func=_cl_fw_disable)
+
+    fw_policy = fw_sub.add_parser("policy", help="Set default firewall policy")
+    fw_policy.add_argument("--in-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default input policy")
+    fw_policy.add_argument("--out-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default output policy")
+    fw_policy.set_defaults(func=_cl_fw_policy)
+
+    # firewall rules
+    rules = fw_sub.add_parser("rules", help="Manage cluster firewall rules")
+    rules.set_defaults(func=_cl_fw_rules)
+    rules_sub = rules.add_subparsers(dest="fw_action", title="rule actions", required=False)
+
+    rules_list = rules_sub.add_parser("list", help="List rules")
+    rules_list.set_defaults(func=_cl_fw_rules)
+
+    rules_add = rules_sub.add_parser("add", help="Add a rule")
+    add_firewall_rule_args(rules_add)
+    rules_add.set_defaults(func=_cl_fw_rule_add)
+
+    rules_show = rules_sub.add_parser("show", help="Show a rule by position")
+    rules_show.add_argument("pos", type=int, help="Rule position")
+    rules_show.set_defaults(func=_cl_fw_rule_show)
+
+    rules_upd = rules_sub.add_parser("update", help="Update a rule by position")
+    rules_upd.add_argument("pos", type=int, help="Rule position")
+    add_firewall_rule_args(rules_upd)
+    for action in rules_upd._actions:
+        if action.dest == "action":
+            action.required = False
+            action.default = None
+    rules_upd.set_defaults(func=_cl_fw_rule_upd)
+
+    rules_del = rules_sub.add_parser("delete", help="Delete a rule by position")
+    rules_del.add_argument("pos", type=int, help="Rule position")
+    rules_del.set_defaults(func=_cl_fw_rule_del)
+
+    # firewall aliases
+    aliases = fw_sub.add_parser("aliases", help="Manage firewall aliases")
+    aliases.set_defaults(func=_cl_fw_aliases)
+    aliases_sub = aliases.add_subparsers(dest="fw_action", title="alias actions", required=False)
+
+    aliases_list = aliases_sub.add_parser("list", help="List aliases")
+    aliases_list.set_defaults(func=_cl_fw_aliases)
+
+    aliases_add = aliases_sub.add_parser("add", help="Add an alias")
+    aliases_add.add_argument("name", help="Alias name")
+    aliases_add.add_argument("--cidr", required=True, help="CIDR notation (e.g. 10.0.0.0/8)")
+    aliases_add.add_argument("--comment", default=None, help="Comment / description")
+    aliases_add.set_defaults(func=_cl_fw_alias_add)
+
+    aliases_del = aliases_sub.add_parser("delete", help="Delete an alias")
+    aliases_del.add_argument("name", help="Alias name")
+    aliases_del.set_defaults(func=_cl_fw_alias_del)
+
+    # firewall ipsets
+    ipsets = fw_sub.add_parser("ipsets", help="Manage firewall ipsets")
+    ipsets.set_defaults(func=_cl_fw_ipsets)
+    ipsets_sub = ipsets.add_subparsers(dest="fw_action", title="ipset actions", required=False)
+
+    ipsets_list = ipsets_sub.add_parser("list", help="List ipsets")
+    ipsets_list.set_defaults(func=_cl_fw_ipsets)
+
+    ipsets_add = ipsets_sub.add_parser("add", help="Add an ipset")
+    ipsets_add.add_argument("name", help="IPset name")
+    ipsets_add.add_argument("--comment", default=None, help="Comment / description")
+    ipsets_add.set_defaults(func=_cl_fw_ipset_add)
+
+    ipsets_show = ipsets_sub.add_parser("show", help="Show ipset contents")
+    ipsets_show.add_argument("name", help="IPset name")
+    ipsets_show.set_defaults(func=_cl_fw_ipset_show)
+
+    ipsets_del = ipsets_sub.add_parser("delete", help="Delete an ipset")
+    ipsets_del.add_argument("name", help="IPset name")
+    ipsets_del.set_defaults(func=_cl_fw_ipset_del)
+
+    ipsets_add_cidr = ipsets_sub.add_parser("add-cidr", help="Add a CIDR to an ipset")
+    ipsets_add_cidr.add_argument("name", help="IPset name")
+    ipsets_add_cidr.add_argument("--cidr", required=True, help="CIDR to add")
+    ipsets_add_cidr.add_argument("--comment", default=None, help="Comment")
+    ipsets_add_cidr.add_argument("--nomatch", action="store_true", help="Exclude match")
+    ipsets_add_cidr.set_defaults(func=_cl_fw_ipset_add_cidr)
+
+    ipsets_del_cidr = ipsets_sub.add_parser("delete-cidr", help="Remove a CIDR from an ipset")
+    ipsets_del_cidr.add_argument("name", help="IPset name")
+    ipsets_del_cidr.add_argument("--cidr", required=True, help="CIDR to remove")
+    ipsets_del_cidr.set_defaults(func=_cl_fw_ipset_del_cidr)
+
+    # firewall refs
+    fw_refs = fw_sub.add_parser("refs", help="List firewall references")
+    fw_refs.add_argument("--type", default=None, choices=["alias", "ipset", "group"],
+                         help="Filter by reference type")
+    fw_refs.set_defaults(func=_cl_fw_refs)
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def _cl_status(_args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/cluster/status")
+
+
+# --- Firewall options ---
+
+def _cl_fw_options(_args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get("/cluster/firewall/options")
+
+
+def _cl_fw_enable(_args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.put("/cluster/firewall/options", data={"enable": 1})
+
+
+def _cl_fw_disable(_args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.put("/cluster/firewall/options", data={"enable": 0})
+
+
+def _cl_fw_policy(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {}
+    if args.in_policy is not None:
+        data["policy_in"] = args.in_policy
+    if args.out_policy is not None:
+        data["policy_out"] = args.out_policy
+    if not data:
+        return {"error": "No policy specified. Use --in-policy or --out-policy"}
+    return client.put("/cluster/firewall/options", data=data)
+
+
+# --- Firewall rules ---
+
+def _cl_fw_rules(_args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/cluster/firewall/rules")
+
+
+def _cl_fw_rule_add(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.post("/cluster/firewall/rules", data=build_rule_data(args))
+
+
+def _cl_fw_rule_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/cluster/firewall/rules/{args.pos}")
+
+
+def _cl_fw_rule_upd(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data = {k: v for k, v in build_rule_data(args).items() if v is not None and v != 0}
+    return client.put(f"/cluster/firewall/rules/{args.pos}", data=data)
+
+
+def _cl_fw_rule_del(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/cluster/firewall/rules/{args.pos}")
+
+
+# --- Firewall aliases ---
+
+def _cl_fw_aliases(_args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/cluster/firewall/aliases")
+
+
+def _cl_fw_alias_add(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data = {"name": args.name, "cidr": args.cidr}
+    if args.comment:
+        data["comment"] = args.comment
+    return client.post("/cluster/firewall/aliases", data=data)
+
+
+def _cl_fw_alias_del(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/cluster/firewall/aliases/{args.name}")
+
+
+# --- Firewall ipsets ---
+
+def _cl_fw_ipsets(_args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/cluster/firewall/ipset")
+
+
+def _cl_fw_ipset_add(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {"name": args.name}
+    if args.comment:
+        data["comment"] = args.comment
+    return client.post("/cluster/firewall/ipset", data=data)
+
+
+def _cl_fw_ipset_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/cluster/firewall/ipset/{args.name}")
+
+
+def _cl_fw_ipset_del(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/cluster/firewall/ipset/{args.name}")
+
+
+def _cl_fw_ipset_add_cidr(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {"cidr": args.cidr}
+    if args.comment:
+        data["comment"] = args.comment
+    if args.nomatch:
+        data["nomatch"] = 1
+    return client.post(f"/cluster/firewall/ipset/{args.name}", data=data)
+
+
+def _cl_fw_ipset_del_cidr(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/cluster/firewall/ipset/{args.name}/{args.cidr}")
+
+
+# --- Firewall refs ---
+
+def _cl_fw_refs(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    params = {"type": args.type} if args.type else None
+    return client.get("/cluster/firewall/refs", params=params)

proxcli-0.3.0/proxmox/cli/firewall_helpers.py

@@ -0,0 +1,60 @@
+"""Firewall helpers shared across cluster, node, and VM subcommands."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Rule argument builder — shared across all firewall levels
+# ---------------------------------------------------------------------------
+
+
+def add_firewall_rule_args(parser: argparse.ArgumentParser) -> None:
+    """Add common rule-form arguments to a parser."""
+    parser.add_argument("--action", required=True, choices=["ACCEPT", "DENY", "REJECT"],
+                        help="Rule action")
+    parser.add_argument("--type", default="in", choices=["in", "out"],
+                        help="Traffic direction (default: in)")
+    parser.add_argument("--iface", default=None, help="Network interface (e.g. net0)")
+    parser.add_argument("--source", default=None, help="Source IP/CIDR")
+    parser.add_argument("--dest", default=None, help="Destination IP/CIDR")
+    parser.add_argument("--dport", default=None, help="Destination port")
+    parser.add_argument("--sport", default=None, help="Source port")
+    parser.add_argument("--proto", default=None, choices=["tcp", "udp", "icmp", "any"],
+                        help="Protocol")
+    parser.add_argument("--comment", default=None, help="Comment / description")
+    parser.add_argument("--enable", type=int, default=1, choices=[0, 1],
+                        help="Enable the rule (default: 1)")
+    parser.add_argument("--macro", default=None, help="Pre-defined macro (e.g. SSH, HTTP)")
+    parser.add_argument("--log", default=None, choices=["emerg", "alert", "crit", "err",
+                          "warning", "notice", "info", "debug", "nolog"],
+                        help="Log level")
+
+
+def build_rule_data(args: argparse.Namespace) -> dict[str, Any]:
+    """Convert parsed firewall rule args into the POST body dict."""
+    data: dict[str, Any] = {
+        "action": args.action,
+        "type": args.type,
+        "enable": args.enable,
+    }
+    if args.macro:
+        data["macro"] = args.macro
+    if args.iface:
+        data["iface"] = args.iface
+    if args.source:
+        data["source"] = args.source
+    if args.dest:
+        data["dest"] = args.dest
+    if args.dport:
+        data["dport"] = args.dport
+    if args.sport:
+        data["sport"] = args.sport
+    if args.proto and not args.macro:
+        data["proto"] = args.proto
+    if args.comment:
+        data["comment"] = args.comment
+    if args.log:
+        data["log"] = args.log
+    return data

{proxcli-0.2.0 → proxcli-0.3.0}/proxmox/cli/main.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import os
 import sys
+from importlib.metadata import version
 from typing import Any
 
 from proxmox.client.auth import AuthManager
@@ -48,7 +49,7 @@ def build_root_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument("--verbose", action="store_true", help="Enable debug output to stderr")
     parser.add_argument(
-        "--version", action="version", version="proxmox 0.1.0"
+        "--version", action="version", version=f"proxmox {version('proxcli')}"
     )
 
     subparsers = parser.add_subparsers(dest="resource", title="resources", required=False)
@@ -176,6 +177,20 @@ def _build_client(overrides: dict[str, Any], args: argparse.Namespace) -> Proxmo
     return client
 
 
+def _print_command_help(args: argparse.Namespace) -> None:
+    """When a subcommand has no explicit handler set, print the parent parser's help."""
+    # Try to reconstruct the appropriate parser and show its help
+    cmd_parts = ["proxmox", args.resource]
+    if hasattr(args, "fw_resource"):
+        cmd_parts.append("firewall")
+        cmd_parts.append(args.fw_resource)
+    elif hasattr(args, "action"):
+        cmd_parts.append(args.action)
+    log_error(
+        f"Missing required argument. Run '{' '.join(cmd_parts)} --help' for usage."
+    )
+
+
 def main(argv: list[str] | None = None) -> None:
     """Main entry point."""
     parser = build_root_parser()
@@ -206,8 +221,8 @@ def main(argv: list[str] | None = None) -> None:
                 output = format_output(result, args.output)
                 print(output)
         else:
-            # Subcommand registered but no func set (cli module not implemented yet)
-            log_error(f"Command 'proxmox {args.resource}' is not yet implemented.")
+            # No handler was set — show relevant help
+            _print_command_help(args)
 
     except ConfigError as exc:
         log_error(str(exc))

proxcli-0.3.0/proxmox/cli/node.py

@@ -0,0 +1,177 @@
+"""`proxmox node` subcommand — node management."""
+
+from __future__ import annotations
+
+import argparse
+
+from proxmox.cli.firewall_helpers import add_firewall_rule_args, build_rule_data
+from proxmox.client.client import ProxmoxClient
+
+
+def register_node_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the `proxmox node` subcommand tree."""
+    node_parser = subparsers.add_parser("node", help="Manage Proxmox nodes")
+    node_sub = node_parser.add_subparsers(dest="action", title="actions", required=True)
+
+    # --- node list ---
+    node_list = node_sub.add_parser("list", help="List all nodes")
+    node_list.set_defaults(func=_node_list)
+
+    # --- node show ---
+    node_show = node_sub.add_parser("show", help="Show node details")
+    node_show.add_argument("node_name", help="Node name")
+    node_show.set_defaults(func=_node_show)
+
+    # --- node status ---
+    node_status = node_sub.add_parser("status", help="Show node status")
+    node_status.add_argument("node_name", nargs="?", help="Node name (omit for all nodes)")
+    node_status.set_defaults(func=_node_status)
+
+    # --- firewall ---
+    fw = node_sub.add_parser("firewall", help="Manage node firewall")
+    fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
+
+    fw_opts = fw_sub.add_parser("options", help="Show node firewall options")
+    fw_opts.add_argument("node_name", help="Node name")
+    fw_opts.set_defaults(func=_node_fw_options)
+
+    fw_enable = fw_sub.add_parser("enable", help="Enable node firewall")
+    fw_enable.add_argument("node_name", help="Node name")
+    fw_enable.set_defaults(func=_node_fw_enable)
+
+    fw_disable = fw_sub.add_parser("disable", help="Disable node firewall")
+    fw_disable.add_argument("node_name", help="Node name")
+    fw_disable.set_defaults(func=_node_fw_disable)
+
+    fw_policy = fw_sub.add_parser("policy", help="Set default input/output policy")
+    fw_policy.add_argument("node_name", help="Node name")
+    fw_policy.add_argument("--in-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default input policy")
+    fw_policy.add_argument("--out-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default output policy")
+    fw_policy.set_defaults(func=_node_fw_policy)
+
+    # firewall rules
+    rules = fw_sub.add_parser("rules", help="Manage node firewall rules")
+    rules.set_defaults(func=_node_fw_rules)
+    rules_sub = rules.add_subparsers(dest="fw_action", title="rule actions", required=False)
+
+    rules_list = rules_sub.add_parser("list", help="List rules")
+    rules_list.add_argument("node_name", help="Node name")
+    rules_list.set_defaults(func=_node_fw_rules)
+
+    rules_add = rules_sub.add_parser("add", help="Add a rule")
+    rules_add.add_argument("node_name", help="Node name")
+    add_firewall_rule_args(rules_add)
+    rules_add.set_defaults(func=_node_fw_rule_add)
+
+    rules_show = rules_sub.add_parser("show", help="Show a rule by position")
+    rules_show.add_argument("node_name", help="Node name")
+    rules_show.add_argument("pos", type=int, help="Rule position")
+    rules_show.set_defaults(func=_node_fw_rule_show)
+
+    rules_upd = rules_sub.add_parser("update", help="Update a rule by position")
+    rules_upd.add_argument("node_name", help="Node name")
+    rules_upd.add_argument("pos", type=int, help="Rule position")
+    add_firewall_rule_args(rules_upd)
+    for action in rules_upd._actions:
+        if action.dest == "action":
+            action.required = False
+            action.default = None
+    rules_upd.set_defaults(func=_node_fw_rule_upd)
+
+    rules_del = rules_sub.add_parser("delete", help="Delete a rule by position")
+    rules_del.add_argument("node_name", help="Node name")
+    rules_del.add_argument("pos", type=int, help="Rule position")
+    rules_del.set_defaults(func=_node_fw_rule_del)
+
+    # firewall refs
+    fw_refs = fw_sub.add_parser("refs", help="List firewall references for node")
+    fw_refs.add_argument("node_name", help="Node name")
+    fw_refs.add_argument("--type", default=None, choices=["alias", "ipset", "group"],
+                         help="Filter by reference type")
+    fw_refs.set_defaults(func=_node_fw_refs)
+
+
+# ---------------------------------------------------------------------------
+# Node handlers
+# ---------------------------------------------------------------------------
+
+def _node_list(_args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get("/nodes")
+
+
+def _node_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/nodes/{args.node_name}/status")
+
+
+def _node_status(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    if args.node_name:
+        return client.get(f"/nodes/{args.node_name}/status")
+    nodes = client.get("/nodes")
+    if isinstance(nodes, list):
+        result = []
+        for n in nodes:
+            node_name = n.get("node") if isinstance(n, dict) else n
+            try:
+                status = client.get(f"/nodes/{node_name}/status")
+                if isinstance(status, dict):
+                    status["node"] = node_name
+                result.append(status)
+            except Exception:
+                result.append({"node": node_name, "status": "error"})
+        return result
+    return nodes
+
+
+# ---------------------------------------------------------------------------
+# Node firewall handlers
+# ---------------------------------------------------------------------------
+
+def _node_fw_options(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/nodes/{args.node_name}/firewall/options")
+
+
+def _node_fw_enable(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.put(f"/nodes/{args.node_name}/firewall/options", data={"enable": 1})
+
+
+def _node_fw_disable(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.put(f"/nodes/{args.node_name}/firewall/options", data={"enable": 0})
+
+
+def _node_fw_policy(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data: dict = {}
+    if args.in_policy:
+        data["policy_in"] = args.in_policy
+    if args.out_policy:
+        data["policy_out"] = args.out_policy
+    if not data:
+        return {"error": "No policy specified. Use --in-policy or --out-policy"}
+    return client.put(f"/nodes/{args.node_name}/firewall/options", data=data)
+
+
+def _node_fw_rules(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    return client.get(f"/nodes/{args.node_name}/firewall/rules")
+
+
+def _node_fw_rule_add(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.post(f"/nodes/{args.node_name}/firewall/rules", data=build_rule_data(args))
+
+
+def _node_fw_rule_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.get(f"/nodes/{args.node_name}/firewall/rules/{args.pos}")
+
+
+def _node_fw_rule_upd(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    data = {k: v for k, v in build_rule_data(args).items() if v is not None and v != 0}
+    return client.put(f"/nodes/{args.node_name}/firewall/rules/{args.pos}", data=data)
+
+
+def _node_fw_rule_del(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    return client.delete(f"/nodes/{args.node_name}/firewall/rules/{args.pos}")
+
+
+def _node_fw_refs(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    params = {"type": args.type} if args.type else None
+    return client.get(f"/nodes/{args.node_name}/firewall/refs", params=params)

{proxcli-0.2.0 → proxcli-0.3.0}/proxmox/cli/vm.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 
+from proxmox.cli.firewall_helpers import add_firewall_rule_args, build_rule_data
 from proxmox.client.client import ProxmoxClient
 from proxmox.utils.helpers import resolve_vmid, vmid_type
 
@@ -74,6 +75,80 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_delete.add_argument("--purge", action="store_true", help="Purge VM from all configurations")
     vm_delete.set_defaults(func=_vm_delete)
 
+    # --- firewall ---
+    fw = vm_sub.add_parser("firewall", help="Manage VM firewall")
+    fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
+
+    fw_opts = fw_sub.add_parser("options", help="Show VM firewall options")
+    fw_opts.add_argument("vmid", type=vmid_type, help="VM ID")
+    fw_opts.add_argument("--node", help="Node name (auto-detected if omitted)")
+    fw_opts.set_defaults(func=_vm_fw_options)
+
+    fw_enable = fw_sub.add_parser("enable", help="Enable VM firewall")
+    fw_enable.add_argument("vmid", type=vmid_type, help="VM ID")
+    fw_enable.add_argument("--node", help="Node name (auto-detected if omitted)")
+    fw_enable.set_defaults(func=_vm_fw_enable)
+
+    fw_disable = fw_sub.add_parser("disable", help="Disable VM firewall")
+    fw_disable.add_argument("vmid", type=vmid_type, help="VM ID")
+    fw_disable.add_argument("--node", help="Node name (auto-detected if omitted)")
+    fw_disable.set_defaults(func=_vm_fw_disable)
+
+    fw_policy = fw_sub.add_parser("policy", help="Set default input/output policy for VM")
+    fw_policy.add_argument("vmid", type=vmid_type, help="VM ID")
+    fw_policy.add_argument("--node", help="Node name (auto-detected if omitted)")
+    fw_policy.add_argument("--in-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default input policy")
+    fw_policy.add_argument("--out-policy", choices=["ACCEPT", "DENY", "REJECT"], default=None,
+                           help="Default output policy")
+    fw_policy.set_defaults(func=_vm_fw_policy)
+
+    # firewall rules
+    rules = fw_sub.add_parser("rules", help="Manage VM firewall rules")
+    rules_sub = rules.add_subparsers(dest="fw_action", title="rule actions", required=False)
+
+    rules_list = rules_sub.add_parser("list", help="List rules")
+    rules_list.add_argument("vmid", type=vmid_type, help="VM ID")
+    rules_list.add_argument("--node", help="Node name (auto-detected if omitted)")
+    rules_list.set_defaults(func=_vm_fw_rules)
+
+    rules_add = rules_sub.add_parser("add", help="Add a rule")
+    rules_add.add_argument("vmid", type=vmid_type, help="VM ID")
+    rules_add.add_argument("--node", help="Node name (auto-detected if omitted)")
+    add_firewall_rule_args(rules_add)
+    rules_add.set_defaults(func=_vm_fw_rule_add)
+
+    rules_show = rules_sub.add_parser("show", help="Show a rule by position")
+    rules_show.add_argument("vmid", type=vmid_type, help="VM ID")
+    rules_show.add_argument("--node", help="Node name (auto-detected if omitted)")
+    rules_show.add_argument("pos", type=int, help="Rule position")
+    rules_show.set_defaults(func=_vm_fw_rule_show)
+
+    rules_upd = rules_sub.add_parser("update", help="Update a rule by position")
+    rules_upd.add_argument("vmid", type=vmid_type, help="VM ID")
+    rules_upd.add_argument("--node", help="Node name (auto-detected if omitted)")
+    rules_upd.add_argument("pos", type=int, help="Rule position")
+    add_firewall_rule_args(rules_upd)
+    for action in rules_upd._actions:
+        if action.dest == "action":
+            action.required = False
+            action.default = None
+    rules_upd.set_defaults(func=_vm_fw_rule_upd)
+
+    rules_del = rules_sub.add_parser("delete", help="Delete a rule by position")
+    rules_del.add_argument("vmid", type=vmid_type, help="VM ID")
+    rules_del.add_argument("--node", help="Node name (auto-detected if omitted)")
+    rules_del.add_argument("pos", type=int, help="Rule position")
+    rules_del.set_defaults(func=_vm_fw_rule_del)
+
+    # firewall refs
+    fw_refs = fw_sub.add_parser("refs", help="List VM firewall references")
+    fw_refs.add_argument("vmid", type=vmid_type, help="VM ID")
+    fw_refs.add_argument("--node", help="Node name (auto-detected if omitted)")
+    fw_refs.add_argument("--type", default=None, choices=["alias", "ipset", "group"],
+                         help="Filter by reference type")
+    fw_refs.set_defaults(func=_vm_fw_refs)
+
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -209,3 +284,87 @@ def _vm_delete(args: argparse.Namespace, client: ProxmoxClient) -> dict:
         params["purge"] = 1
     result = client.delete(f"/nodes/{node}/qemu/{args.vmid}", params=params or None)
     return result if isinstance(result, dict) else {"data": result}
+
+
+# ---------------------------------------------------------------------------
+# VM firewall handlers
+# ---------------------------------------------------------------------------
+
+def _vm_fw_options(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.get(f"/nodes/{node}/qemu/{args.vmid}/firewall/options")
+
+
+def _vm_fw_enable(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.put(f"/nodes/{node}/qemu/{args.vmid}/firewall/options", data={"enable": 1})
+
+
+def _vm_fw_disable(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.put(f"/nodes/{node}/qemu/{args.vmid}/firewall/options", data={"enable": 0})
+
+
+def _vm_fw_policy(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    data: dict = {}
+    if args.in_policy:
+        data["policy_in"] = args.in_policy
+    if args.out_policy:
+        data["policy_out"] = args.out_policy
+    if not data:
+        return {"error": "No policy specified. Use --in-policy or --out-policy"}
+    return client.put(f"/nodes/{node}/qemu/{args.vmid}/firewall/options", data=data)
+
+
+def _vm_fw_rules(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.get(f"/nodes/{node}/qemu/{args.vmid}/firewall/rules")
+
+
+def _vm_fw_rule_add(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.post(f"/nodes/{node}/qemu/{args.vmid}/firewall/rules",
+                       data=build_rule_data(args))
+
+
+def _vm_fw_rule_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.get(f"/nodes/{node}/qemu/{args.vmid}/firewall/rules/{args.pos}")
+
+
+def _vm_fw_rule_upd(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    data = {k: v for k, v in build_rule_data(args).items() if v is not None and v != 0}
+    return client.put(f"/nodes/{node}/qemu/{args.vmid}/firewall/rules/{args.pos}", data=data)
+
+
+def _vm_fw_rule_del(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    return client.delete(f"/nodes/{node}/qemu/{args.vmid}/firewall/rules/{args.pos}")
+
+
+def _vm_fw_refs(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    params: dict | None = {"type": args.type} if args.type else None
+    return client.get(f"/nodes/{node}/qemu/{args.vmid}/firewall/refs", params=params)

{proxcli-0.2.0 → proxcli-0.3.0}/pyproject.toml

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

{proxcli-0.2.0 → proxcli-0.3.0}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.10"
 
 [[package]]
@@ -254,7 +254,7 @@ wheels = [
 
 [[package]]
 name = "proxcli"
-version = "0.1.1"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

proxcli-0.2.0/proxmox/cli/cluster.py

@@ -1,21 +0,0 @@
-"""`proxmox cluster` subcommand — cluster management."""
-
-from __future__ import annotations
-
-import argparse
-
-from proxmox.client.client import ProxmoxClient
-
-
-def register_cluster_parser(subparsers: argparse._SubParsersAction) -> None:
-    """Register the `proxmox cluster` subcommand tree."""
-    cl_parser = subparsers.add_parser("cluster", help="Manage Proxmox cluster")
-    cl_sub = cl_parser.add_subparsers(dest="action", title="actions", required=True)
-
-    # --- cluster status ---
-    cl_status = cl_sub.add_parser("status", help="Show cluster status")
-    cl_status.set_defaults(func=_cl_status)
-
-
-def _cl_status(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
-    return client.get("/cluster/status")

proxcli-0.2.0/proxmox/cli/node.py

@@ -1,55 +0,0 @@
-"""`proxmox node` subcommand — node management."""
-
-from __future__ import annotations
-
-import argparse
-
-from proxmox.client.client import ProxmoxClient
-
-
-def register_node_parser(subparsers: argparse._SubParsersAction) -> None:
-    """Register the `proxmox node` subcommand tree."""
-    node_parser = subparsers.add_parser("node", help="Manage Proxmox nodes")
-    node_sub = node_parser.add_subparsers(dest="action", title="actions", required=True)
-
-    # --- node list ---
-    node_list = node_sub.add_parser("list", help="List all nodes")
-    node_list.set_defaults(func=_node_list)
-
-    # --- node show ---
-    node_show = node_sub.add_parser("show", help="Show node details")
-    node_show.add_argument("node_name", help="Node name")
-    node_show.set_defaults(func=_node_show)
-
-    # --- node status ---
-    node_status = node_sub.add_parser("status", help="Show node status")
-    node_status.add_argument("node_name", nargs="?", help="Node name (omit for all nodes)")
-    node_status.set_defaults(func=_node_status)
-
-
-def _node_list(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
-    return client.get("/nodes")
-
-
-def _node_show(args: argparse.Namespace, client: ProxmoxClient) -> dict:
-    return client.get(f"/nodes/{args.node_name}/status")
-
-
-def _node_status(args: argparse.Namespace, client: ProxmoxClient) -> dict | list:
-    if args.node_name:
-        return client.get(f"/nodes/{args.node_name}/status")
-    # Return all nodes' statuses
-    nodes = client.get("/nodes")
-    if isinstance(nodes, list):
-        result = []
-        for n in nodes:
-            node_name = n.get("node") if isinstance(n, dict) else n
-            try:
-                status = client.get(f"/nodes/{node_name}/status")
-                if isinstance(status, dict):
-                    status["node"] = node_name
-                result.append(status)
-            except Exception:
-                result.append({"node": node_name, "status": "error"})
-        return result
-    return nodes