proxcli 0.2.1__tar.gz → 0.4.0__tar.gz

{proxcli-0.2.1 → proxcli-0.4.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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        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.4.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.1 → proxcli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-20
+
+### Added
+- Container firewall management: options, enable/disable, policy, rules (CRUD), refs.
+  Uses `/nodes/{node}/lxc/{vmid}/firewall/*` endpoints.
+
+## [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
@@ -41,6 +61,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.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
 [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

{proxcli-0.2.1 → proxcli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.2.1
+Version: 0.4.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.4.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)