pxinv 0.3.0__py3-none-any.whl

pxinv/__init__.py

@@ -0,0 +1,3 @@
+"""pxinv — Proxmox VM & container inventory CLI."""
+
+__version__ = "0.3.0"

pxinv/cli.py

@@ -0,0 +1,308 @@
+import time
+import warnings
+
+warnings.filterwarnings("ignore", category=UserWarning, module="urllib3")
+
+import click  # noqa: E402
+from rich.console import Console  # noqa: E402
+
+from .client import ProxmoxClient, PxinvAuthError, PxinvConnectionError, PxinvNotFoundError  # noqa: E402
+from .config import load_config  # noqa: E402
+from .output import print_summary, print_table, build_watch_panel  # noqa: E402
+
+
+@click.group()
+@click.version_option(package_name="pxinv")
+@click.option("--host", envvar="PXINV_HOST", help="Proxmox host (e.g. 192.168.1.10)")
+@click.option("--user", envvar="PXINV_USER", default="root@pam", show_default=True)
+@click.option("--token-name", envvar="PXINV_TOKEN_NAME", help="API token name")
+@click.option("--token-value", envvar="PXINV_TOKEN_VALUE", help="API token value")
+@click.option("--config", "config_path", default=None, help="Path to config file")
+@click.option("--verify-ssl/--no-verify-ssl", default=True, envvar="PXINV_VERIFY_SSL")
+@click.pass_context
+def cli(ctx, host, user, token_name, token_value, config_path, verify_ssl):
+    """pxinv — Proxmox VM & container inventory CLI."""
+    ctx.ensure_object(dict)
+
+    cfg = load_config(config_path)
+
+    ctx.obj["host"] = host or cfg.get("host")
+    ctx.obj["user"] = user or cfg.get("user", "root@pam")
+    ctx.obj["token_name"] = token_name or cfg.get("token_name")
+    ctx.obj["token_value"] = token_value or cfg.get("token_value")
+    ctx.obj["verify_ssl"] = verify_ssl
+
+    if not ctx.obj["host"]:
+        raise click.UsageError(
+            "Proxmox host is required. Use --host, PXINV_HOST env var, or config file."
+        )
+
+
+def _get_client(ctx):
+    obj = ctx.obj
+    missing = [k for k in ("host", "token_name", "token_value") if not obj.get(k)]
+    if missing:
+        raise click.UsageError(
+            f"Missing required config: {', '.join(missing)}. "
+            "Use CLI flags, env vars (PXINV_*), or a config file."
+        )
+    try:
+        return ProxmoxClient(
+            host=obj["host"],
+            user=obj["user"],
+            token_name=obj["token_name"],
+            token_value=obj["token_value"],
+            verify_ssl=obj["verify_ssl"],
+        )
+    except (PxinvConnectionError, PxinvAuthError) as e:
+        raise click.ClickException(str(e))
+
+
+def _catch(exc):
+    """Re-raise pxinv domain errors as clean ClickExceptions."""
+    if isinstance(exc, (PxinvConnectionError, PxinvAuthError, PxinvNotFoundError)):
+        raise click.ClickException(str(exc))
+    raise exc
+
+
+def _wait_for_status(client, vmid, target_status, timeout):
+    """Poll until VM reaches target_status or timeout."""
+    console = Console()
+    deadline = time.time() + timeout
+    with console.status(f"Waiting for {target_status}..."):
+        while time.time() < deadline:
+            current = client.get_vm_status(vmid)
+            if current == target_status:
+                return
+            time.sleep(2)
+    raise click.ClickException(
+        f"Timeout after {timeout}s — last status: {client.get_vm_status(vmid)}"
+    )
+
+
+@cli.command()
+@click.option("--node", default=None, help="Filter by node name")
+@click.option(
+    "--type", "vm_type", default=None,
+    type=click.Choice(["vm", "ct"]),
+    help="Filter by type: vm or ct",
+)
+@click.option(
+    "--status", default=None,
+    type=click.Choice(["running", "stopped", "paused"]),
+    help="Filter by status",
+)
+@click.option(
+    "--output", "-o", default="table",
+    type=click.Choice(["table", "json", "yaml"]),
+    show_default=True, help="Output format",
+)
+@click.option("--tags", default=None, help="Filter by tag (e.g. --tags homelab)")
+@click.pass_context
+def list(ctx, node, vm_type, status, output, tags):
+    """List all VMs and containers."""
+    try:
+        client = _get_client(ctx)
+        resources = client.get_resources(node=node, vm_type=vm_type, status=status)
+    except (PxinvConnectionError, PxinvAuthError, PxinvNotFoundError) as e:
+        _catch(e)
+
+    if tags:
+        resources = [
+            r for r in resources
+            if tags.lower() in [t.strip().lower() for t in r.get("tags", "").split(";") if t.strip()]
+        ]
+
+    if output == "table":
+        print_table(resources)
+    elif output == "json":
+        import json
+        click.echo(json.dumps(resources, indent=2))
+    elif output == "yaml":
+        import yaml
+        click.echo(yaml.dump(resources, default_flow_style=False))
+
+
+@cli.command()
+@click.option(
+    "--output", "-o", default="table",
+    type=click.Choice(["table", "json", "yaml"]),
+    show_default=True,
+)
+@click.pass_context
+def summary(ctx, output):
+    """Show cluster resource summary."""
+    try:
+        client = _get_client(ctx)
+        resources = client.get_resources()
+        nodes = client.get_nodes()
+    except (PxinvConnectionError, PxinvAuthError) as e:
+        _catch(e)
+
+    if output == "table":
+        print_summary(resources, nodes)
+    elif output == "json":
+        import json
+        click.echo(json.dumps({"resources": resources, "nodes": nodes}, indent=2))
+    elif output == "yaml":
+        import yaml
+        click.echo(yaml.dump({"resources": resources, "nodes": nodes}, default_flow_style=False))
+
+
+@cli.command()
+@click.option("--interval", "-i", default=5, show_default=True, help="Refresh interval in seconds")
+@click.option("--node", default=None, help="Filter by node name")
+@click.option(
+    "--type", "vm_type", default=None,
+    type=click.Choice(["vm", "ct"]),
+    help="Filter by type: vm or ct",
+)
+@click.option(
+    "--status", default=None,
+    type=click.Choice(["running", "stopped", "paused"]),
+    help="Filter by status",
+)
+@click.option("--tags", default=None, help="Filter by tag")
+@click.pass_context
+def watch(ctx, interval, node, vm_type, status, tags):
+    """Live-refresh the VM/container list. Press Ctrl+C to exit."""
+    from rich.live import Live
+    client = _get_client(ctx)
+
+    def fetch():
+        try:
+            resources = client.get_resources(node=node, vm_type=vm_type, status=status)
+            if tags:
+                resources = [
+                    r for r in resources
+                    if tags.lower() in [t.strip().lower() for t in r.get("tags", "").split(";") if t.strip()]
+                ]
+            return resources
+        except (PxinvConnectionError, PxinvAuthError) as e:
+            raise click.ClickException(str(e))
+
+    resources = fetch()
+    try:
+        with Live(build_watch_panel(resources, interval), refresh_per_second=1, screen=True) as live:
+            while True:
+                time.sleep(interval)
+                resources = fetch()
+                live.update(build_watch_panel(resources, interval))
+    except KeyboardInterrupt:
+        pass
+
+
+
+@cli.command()
+@click.argument("vmid", type=int)
+@click.option("--wait", is_flag=True, default=False, help="Wait until VM is running")
+@click.option("--timeout", default=60, show_default=True, help="Timeout in seconds when using --wait")
+@click.pass_context
+def start(ctx, vmid, wait, timeout):
+    """Start a VM or container by VMID."""
+    client = _get_client(ctx)
+    try:
+        _, vm = client.start_vm(vmid)
+        click.echo(f"Starting {vm['name']} ({vmid})...")
+        if wait:
+            _wait_for_status(client, vmid, "running", timeout)
+            click.echo(f"{vm['name']} is running.")
+        else:
+            click.echo("Task sent. Use 'pxinv list' to check status.")
+    except (PxinvConnectionError, PxinvAuthError, PxinvNotFoundError, ValueError) as e:
+        if isinstance(e, ValueError):
+            raise click.ClickException(str(e))
+        _catch(e)
+
+
+@cli.command()
+@click.argument("vmid", type=int)
+@click.option("--wait", is_flag=True, default=False, help="Wait until VM is stopped")
+@click.option("--timeout", default=60, show_default=True, help="Timeout in seconds when using --wait")
+@click.pass_context
+def stop(ctx, vmid, wait, timeout):
+    """Gracefully shut down a VM or container by VMID."""
+    client = _get_client(ctx)
+    try:
+        _, vm = client.stop_vm(vmid)
+        click.echo(f"Stopping {vm['name']} ({vmid})...")
+        if wait:
+            _wait_for_status(client, vmid, "stopped", timeout)
+            click.echo(f"{vm['name']} is stopped.")
+        else:
+            click.echo("Task sent. Use 'pxinv list' to check status.")
+    except (PxinvConnectionError, PxinvAuthError, PxinvNotFoundError, ValueError) as e:
+        if isinstance(e, ValueError):
+            raise click.ClickException(str(e))
+        _catch(e)
+
+
+def main():
+    cli()
+
+
+@cli.command("ansible-inventory")
+@click.option("--with-ips", is_flag=True, default=False,
+              help="Fetch IPs via QEMU guest agent (requires qemu-guest-agent installed in VMs)")
+@click.option("--running-only", is_flag=True, default=False,
+              help="Only include running VMs and containers")
+@click.pass_context
+def ansible_inventory(ctx, with_ips, running_only):
+    """Export inventory in Ansible dynamic inventory JSON format."""
+    import json
+
+    client = _get_client(ctx)
+    try:
+        status_filter = "running" if running_only else None
+        resources = client.get_resources(status=status_filter)
+    except (PxinvConnectionError, PxinvAuthError) as e:
+        _catch(e)
+
+    hostvars = {}
+    groups = {"all": {"hosts": [], "children": []}, "_meta": {"hostvars": {}}}
+
+    # Group by status and by tag
+    status_groups = {}
+    tag_groups = {}
+
+    for r in resources:
+        hostname = r["name"]
+        groups["all"]["hosts"].append(hostname)
+
+        # Build hostvars
+        hvars = {
+            "proxmox_vmid": r["vmid"],
+            "proxmox_node": r["node"],
+            "proxmox_type": r["type"],
+            "proxmox_status": r["status"],
+            "proxmox_tags": [t.strip() for t in r.get("tags", "").split(";") if t.strip()],
+        }
+
+        if with_ips and r["status"] == "running":
+            ip = client.get_vm_ip(r["vmid"], r["node"], r["type"])
+            if ip:
+                hvars["ansible_host"] = ip
+
+        hostvars[hostname] = hvars
+
+        # Group by status
+        s = r["status"]
+        status_groups.setdefault(s, []).append(hostname)
+
+        # Group by tag
+        for tag in hvars["proxmox_tags"]:
+            tag_groups.setdefault(tag, []).append(hostname)
+
+    # Build final structure
+    for s, hosts in status_groups.items():
+        groups[s] = {"hosts": hosts}
+        groups["all"]["children"].append(s)
+
+    for tag, hosts in tag_groups.items():
+        groups[f"tag_{tag}"] = {"hosts": hosts}
+        groups["all"]["children"].append(f"tag_{tag}")
+
+    groups["_meta"]["hostvars"] = hostvars
+    groups["all"]["children"] = sorted(set(groups["all"]["children"]))
+
+    click.echo(json.dumps(groups, indent=2))

pxinv/client.py

@@ -0,0 +1,175 @@
+from proxmoxer import ProxmoxAPI
+from proxmoxer.backends.https import AuthenticationError
+from requests.exceptions import ConnectionError, SSLError
+
+
+class PxinvConnectionError(Exception):
+    pass
+
+
+class PxinvAuthError(Exception):
+    pass
+
+
+class PxinvNotFoundError(Exception):
+    pass
+
+
+def _wrap_api_call(func):
+    """Decorator that converts proxmoxer/requests exceptions into clean pxinv errors."""
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except AuthenticationError:
+            raise PxinvAuthError(
+                "Authentication failed. Check your token name and token value."
+            )
+        except SSLError:
+            raise PxinvConnectionError(
+                "SSL verification failed. Use --no-verify-ssl if your Proxmox uses a self-signed certificate."
+            )
+        except ConnectionError as e:
+            if "No route to host" in str(e) or "refused" in str(e).lower():
+                raise PxinvConnectionError(
+                    "Cannot connect to Proxmox. Check that the host is reachable and port 8006 is open."
+                )
+            raise PxinvConnectionError(f"Connection error: {e}")
+    return wrapper
+
+
+class ProxmoxClient:
+    def __init__(self, host, user, token_name, token_value, verify_ssl=True):
+        try:
+            self._px = ProxmoxAPI(
+                host,
+                user=user,
+                token_name=token_name,
+                token_value=token_value,
+                verify_ssl=verify_ssl,
+            )
+        except SSLError:
+            raise PxinvConnectionError(
+                "SSL verification failed. Use --no-verify-ssl if your Proxmox uses a self-signed certificate."
+            )
+        except ConnectionError as e:
+            raise PxinvConnectionError(
+                f"Cannot connect to {host}:8006 — {e}"
+            )
+
+    @_wrap_api_call
+    def get_nodes(self):
+        """Return list of nodes with basic stats."""
+        nodes = []
+        for node in self._px.nodes.get():
+            nodes.append(
+                {
+                    "name": node["node"],
+                    "status": node.get("status", "unknown"),
+                    "cpu": round(node.get("cpu", 0) * 100, 1),
+                    "mem_used": node.get("mem", 0),
+                    "mem_total": node.get("maxmem", 0),
+                    "uptime": node.get("uptime", 0),
+                }
+            )
+        return nodes
+
+    @_wrap_api_call
+    def get_vm(self, vmid):
+        """Find a VM/CT by VMID and return its node and type."""
+        for item in self._px.cluster.resources.get(type="vm"):
+            if item.get("vmid") == vmid:
+                return {
+                    "vmid": vmid,
+                    "node": item["node"],
+                    "type": "qemu" if item["type"] == "qemu" else "lxc",
+                    "status": item["status"],
+                    "name": item.get("name", f"vm-{vmid}"),
+                }
+        return None
+
+    @_wrap_api_call
+    def start_vm(self, vmid):
+        """Start a VM or container."""
+        vm = self.get_vm(vmid)
+        if not vm:
+            raise PxinvNotFoundError(f"VMID {vmid} not found")
+        if vm["status"] == "running":
+            raise ValueError(f"{vm['name']} is already running")
+        node = self._px.nodes(vm["node"])
+        if vm["type"] == "qemu":
+            return node.qemu(vmid).status.start.post(), vm
+        return node.lxc(vmid).status.start.post(), vm
+
+    @_wrap_api_call
+    def stop_vm(self, vmid):
+        """Gracefully shutdown a VM or container."""
+        vm = self.get_vm(vmid)
+        if not vm:
+            raise PxinvNotFoundError(f"VMID {vmid} not found")
+        if vm["status"] == "stopped":
+            raise ValueError(f"{vm['name']} is already stopped")
+        node = self._px.nodes(vm["node"])
+        if vm["type"] == "qemu":
+            return node.qemu(vmid).status.shutdown.post(), vm
+        return node.lxc(vmid).status.shutdown.post(), vm
+
+    @_wrap_api_call
+    def get_vm_status(self, vmid):
+        """Return current status of a VM/CT."""
+        vm = self.get_vm(vmid)
+        return vm["status"] if vm else None
+
+    @_wrap_api_call
+    def get_resources(self, node=None, vm_type=None, status=None):
+        """Return VMs and containers, optionally filtered."""
+        resources = []
+
+        for item in self._px.cluster.resources.get(type="vm"):
+            vm_type_raw = item.get("type", "")  # "qemu" or "lxc"
+            inferred_type = "vm" if vm_type_raw == "qemu" else "ct"
+
+            if vm_type and vm_type != inferred_type:
+                continue
+            if node and item.get("node") != node:
+                continue
+            if status and item.get("status") != status:
+                continue
+
+            resources.append(
+                {
+                    "vmid": item.get("vmid"),
+                    "name": item.get("name", f"vm-{item.get('vmid')}"),
+                    "node": item.get("node"),
+                    "type": inferred_type,
+                    "status": item.get("status", "unknown"),
+                    "cpu_usage": round(item.get("cpu", 0) * 100, 1),
+                    "mem_used": item.get("mem", 0),
+                    "mem_total": item.get("maxmem", 0),
+                    "disk_used": item.get("disk", 0),
+                    "disk_total": item.get("maxdisk", 0),
+                    "uptime": item.get("uptime", 0),
+                    "tags": item.get("tags", ""),
+                }
+            )
+
+        return sorted(resources, key=lambda r: (r["node"], r["name"]))
+
+    @_wrap_api_call
+    def get_vm_ip(self, vmid, node, vm_type):
+        """Try to get the primary IP of a running VM via QEMU guest agent.
+        Returns None if the agent is not available or the VM is stopped.
+        Only works for VMs (qemu), not containers (lxc).
+        """
+        if vm_type != "vm":
+            return None
+        try:
+            ifaces = self._px.nodes(node).qemu(vmid).agent("network-get-interfaces").get()
+            for iface in ifaces.get("result", []):
+                if iface.get("name") == "lo":
+                    continue
+                for addr in iface.get("ip-addresses", []):
+                    if addr.get("ip-address-type") == "ipv4":
+                        return addr["ip-address"]
+        except Exception:
+            return None
+        return None

pxinv/config.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+import yaml
+
+
+DEFAULT_CONFIG_PATHS = [
+    Path.home() / ".config" / "pxinv" / "config.yaml",
+    Path.home() / ".pxinv.yaml",
+    Path("pxinv.yaml"),
+]
+
+
+def load_config(path=None):
+    """Load config from file. Returns empty dict if not found."""
+    candidates = [Path(path)] if path else DEFAULT_CONFIG_PATHS
+
+    for candidate in candidates:
+        if candidate.exists():
+            with open(candidate) as f:
+                return yaml.safe_load(f) or {}
+
+    return {}

pxinv/output.py

@@ -0,0 +1,173 @@
+from datetime import datetime
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+
+def _fmt_bytes(b):
+    if b == 0:
+        return "—"
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if b < 1024:
+            return f"{b:.1f}{unit}"
+        b /= 1024
+    return f"{b:.1f}PB"
+
+
+def _fmt_uptime(seconds):
+    if not seconds:
+        return "—"
+    days, rem = divmod(int(seconds), 86400)
+    hours, rem = divmod(rem, 3600)
+    mins = rem // 60
+    parts = []
+    if days:
+        parts.append(f"{days}d")
+    if hours:
+        parts.append(f"{hours}h")
+    if mins and not days:
+        parts.append(f"{mins}m")
+    return " ".join(parts) or "< 1m"
+
+
+def _status_style(status):
+    return {
+        "running": "[green]running[/green]",
+        "stopped": "[red]stopped[/red]",
+        "paused": "[yellow]paused[/yellow]",
+    }.get(status, status)
+
+
+def _type_style(t):
+    return "[cyan]VM[/cyan]" if t == "vm" else "[magenta]CT[/magenta]"
+
+
+def build_table(resources):
+    """Build and return a Rich Table from a list of resources."""
+    table = Table(box=box.SIMPLE_HEAD, show_header=True, header_style="bold")
+    table.add_column("VMID", style="dim", width=6)
+    table.add_column("NAME", min_width=20)
+    table.add_column("NODE", style="dim")
+    table.add_column("TYPE", width=4)
+    table.add_column("STATUS", width=9)
+    table.add_column("CPU", justify="right", width=6)
+    table.add_column("RAM", justify="right", width=14)
+    table.add_column("DISK", justify="right", width=14)
+    table.add_column("UPTIME", justify="right", width=10)
+    table.add_column("TAGS", style="dim")
+
+    for r in resources:
+        mem = f"{_fmt_bytes(r['mem_used'])}/{_fmt_bytes(r['mem_total'])}"
+        disk = f"{_fmt_bytes(r['disk_used'])}/{_fmt_bytes(r['disk_total'])}"
+        cpu = f"{r['cpu_usage']}%" if r["status"] == "running" else "—"
+        tags = r.get("tags", "").replace(";", " ") if r.get("tags") else ""
+
+        table.add_row(
+            str(r["vmid"]),
+            r["name"],
+            r["node"],
+            _type_style(r["type"]),
+            _status_style(r["status"]),
+            cpu,
+            mem,
+            disk,
+            _fmt_uptime(r["uptime"]),
+            tags,
+        )
+
+    return table
+
+
+def build_footer(resources):
+    """Return a footer Text with running/stopped counts."""
+    running = sum(1 for r in resources if r["status"] == "running")
+    stopped = sum(1 for r in resources if r["status"] == "stopped")
+    return Text(
+        f"{len(resources)} resource(s) — {running} running, {stopped} stopped",
+        style="dim",
+    )
+
+
+def print_table(resources):
+    if not resources:
+        console.print("[yellow]No resources found.[/yellow]")
+        return
+    console.print(build_table(resources))
+    console.print(build_footer(resources))
+
+
+def build_watch_panel(resources, interval):
+    """Build a Panel containing the table + footer for use with rich.Live."""
+    if not resources:
+        content = Text("No resources found.", style="yellow")
+    else:
+        from rich.console import Group
+        content = Group(build_table(resources), build_footer(resources))
+
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    return Panel(
+        content,
+        title="[bold]pxinv watch[/bold]",
+        subtitle=f"[dim]refreshing every {interval}s — last update {timestamp} — press Ctrl+C to exit[/dim]",
+        border_style="dim",
+    )
+
+
+def print_summary(resources, nodes):
+    node_table = Table(
+        title="Nodes", box=box.SIMPLE_HEAD, show_header=True, header_style="bold"
+    )
+    node_table.add_column("NODE")
+    node_table.add_column("STATUS")
+    node_table.add_column("CPU", justify="right")
+    node_table.add_column("RAM", justify="right", width=16)
+    node_table.add_column("UPTIME", justify="right")
+
+    for n in nodes:
+        mem = f"{_fmt_bytes(n['mem_used'])}/{_fmt_bytes(n['mem_total'])}"
+        node_table.add_row(
+            n["name"],
+            _status_style(n["status"]),
+            f"{n['cpu']}%",
+            mem,
+            _fmt_uptime(n["uptime"]),
+        )
+
+    console.print(node_table)
+
+    total = len(resources)
+    running = sum(1 for r in resources if r["status"] == "running")
+    stopped = sum(1 for r in resources if r["status"] == "stopped")
+    vms = sum(1 for r in resources if r["type"] == "vm")
+    cts = sum(1 for r in resources if r["type"] == "ct")
+    total_mem = sum(r["mem_total"] for r in resources)
+    used_mem = sum(r["mem_used"] for r in resources)
+    total_disk = sum(r["disk_total"] for r in resources if r["disk_total"] > 0)
+    used_disk = sum(r["disk_used"] for r in resources if r["disk_total"] > 0)
+
+    summary_table = Table(
+        title="Cluster totals", box=box.SIMPLE_HEAD, header_style="bold"
+    )
+    summary_table.add_column("METRIC")
+    summary_table.add_column("VALUE", justify="right")
+
+    summary_table.add_row("Total guests", str(total))
+    summary_table.add_row("  VMs", str(vms))
+    summary_table.add_row("  Containers", str(cts))
+    summary_table.add_row("Running", f"[green]{running}[/green]")
+    summary_table.add_row("Stopped", f"[red]{stopped}[/red]")
+    summary_table.add_row(
+        "RAM allocated",
+        f"{_fmt_bytes(used_mem)} / {_fmt_bytes(total_mem)}",
+    )
+    summary_table.add_row(
+        "Disk allocated",
+        f"{_fmt_bytes(used_disk)} / {_fmt_bytes(total_disk)}" if total_disk > 0 else "—  (no data)",
+    )
+
+    console.print(summary_table)

pxinv-0.3.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: pxinv
+Version: 0.3.0
+Summary: Proxmox VM & container inventory CLI
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/pxinv
+Project-URL: Issues, https://github.com/yourusername/pxinv/issues
+Keywords: proxmox,homelab,cli,inventory,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: proxmoxer>=2.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pip-audit>=2.0; extra == "dev"
+
+# pxinv
+
+[![CI](https://github.com/thetechiejourney/pxinv/actions/workflows/ci.yml/badge.svg)](https://github.com/thetechiejourney/pxinv/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A fast CLI for inventorying and managing VMs and containers on your Proxmox homelab.
+
+```
+$ pxinv list
+
+ VMID  NAME             NODE    TYPE  STATUS   CPU    RAM              DISK             UPTIME  TAGS
+──────────────────────────────────────────────────────────────────────────────────────────────────────
+ 100   homeassistant    pve-01  VM    running  5.2%   1.0GB/4.0GB      10.0GB/32.0GB    3d      homelab
+ 101   pihole           pve-01  CT    running  0.8%   128.0MB/512.0MB  1.0GB/8.0GB      14d     dns
+ 200   talos-cp-01      pve-02  VM    stopped  —      —/8.0GB          —/64.0GB         —       k8s
+
+3 resource(s) — 2 running, 1 stopped
+```
+
+## Installation
+
+```bash
+pip install pxinv
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/thetechiejourney/pxinv
+cd pxinv
+pip install -e .
+```
+
+## Authentication
+
+`pxinv` uses Proxmox API tokens (recommended over username/password).
+
+**Create a token in Proxmox:**
+1. Go to Datacenter → Permissions → API Tokens
+2. Add a token for your user (e.g. `root@pam`, token name: `pxinv`)
+3. Copy the token value — it's only shown once
+
+**Required permissions:** `VM.Audit` and `Sys.Audit` on `/` (or per-node).
+
+## Configuration
+
+Credentials can be provided in three ways (in order of precedence):
+
+### 1. CLI flags
+```bash
+pxinv --host 192.168.1.10 --token-name pxinv --token-value <secret> list
+```
+
+### 2. Environment variables
+```bash
+export PXINV_HOST=192.168.1.10
+export PXINV_TOKEN_NAME=pxinv
+export PXINV_TOKEN_VALUE=<secret>
+export PXINV_VERIFY_SSL=false   # optional, for self-signed certs
+
+pxinv list
+```
+
+### 3. Config file
+
+`~/.config/pxinv/config.yaml`:
+```yaml
+host: 192.168.1.10
+user: root@pam
+token_name: pxinv
+token_value: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+verify_ssl: false
+```
+
+## Commands
+
+### `pxinv list`
+
+List all VMs and containers.
+
+```bash
+# All guests
+pxinv list
+
+# Filter by node
+pxinv list --node pve-01
+
+# Only running containers
+pxinv list --type ct --status running
+
+# Filter by tag
+pxinv list --tags k8s
+pxinv list --tags homelab --status running
+
+# JSON output (pipe to jq, etc.)
+pxinv list --output json | jq '.[] | select(.cpu_usage > 50)'
+
+# YAML output
+pxinv list --output yaml
+```
+
+### `pxinv watch`
+
+Live-refresh the VM/container list directly in the terminal. No flickering — powered by `rich.Live`. Press `Ctrl+C` to exit.
+
+```bash
+# Refresh every 5 seconds (default)
+pxinv watch
+
+# Custom interval
+pxinv watch --interval 10
+
+# Combinable with all list filters
+pxinv watch --status running
+pxinv watch --tags k8s --interval 3
+pxinv watch --node pve-01
+```
+
+The panel header shows the refresh interval and the timestamp of the last update.
+
+### `pxinv summary`
+
+Show cluster-wide resource totals and node status.
+
+```bash
+pxinv summary
+pxinv summary --output json
+```
+
+### `pxinv start <vmid>`
+
+Start a VM or container by VMID.
+
+```bash
+pxinv start 100
+
+# Wait until the VM is fully running before returning
+pxinv start 100 --wait
+
+# Custom timeout (default: 60s)
+pxinv start 100 --wait --timeout 120
+```
+
+### `pxinv stop <vmid>`
+
+Gracefully shut down a VM or container by VMID.
+
+```bash
+pxinv stop 100
+
+# Wait until the VM is fully stopped before returning
+pxinv stop 100 --wait
+```
+
+### `pxinv ansible-inventory`
+
+Export the inventory in Ansible dynamic inventory JSON format. Hosts are automatically grouped by status (`running`, `stopped`) and by Proxmox tag (`tag_homelab`, `tag_k8s`, etc.).
+
+```bash
+# Basic inventory (no IPs)
+pxinv ansible-inventory
+
+# Fetch IPs via QEMU guest agent (requires qemu-guest-agent installed in VMs)
+pxinv ansible-inventory --with-ips
+
+# Only include running guests
+pxinv ansible-inventory --running-only
+
+# Use directly with ansible
+ansible -i <(pxinv ansible-inventory) all -m ping
+
+# Target a specific group
+ansible -i <(pxinv ansible-inventory) tag_homelab -m ping
+ansible -i <(pxinv ansible-inventory) running -m setup
+```
+
+Example output:
+
+```json
+{
+  "all": {
+    "hosts": ["homeassistant", "pihole"],
+    "children": ["running", "stopped", "tag_homelab", "tag_dns"]
+  },
+  "running": { "hosts": ["homeassistant", "pihole"] },
+  "stopped": { "hosts": [] },
+  "tag_homelab": { "hosts": ["homeassistant"] },
+  "tag_dns": { "hosts": ["pihole"] },
+  "_meta": {
+    "hostvars": {
+      "homeassistant": {
+        "ansible_host": "192.168.1.100",
+        "proxmox_vmid": 100,
+        "proxmox_node": "pve-01",
+        "proxmox_type": "vm",
+        "proxmox_status": "running",
+        "proxmox_tags": ["homelab"]
+      }
+    }
+  }
+}
+```
+
+> `ansible_host` is only populated when using `--with-ips` and the VM has `qemu-guest-agent` running.
+
+## Tags
+
+Proxmox supports tagging VMs and containers via the UI (VM → Options → Tags). `pxinv` shows tags as a column in `pxinv list` and lets you filter by them:
+
+```bash
+pxinv list --tags homelab
+pxinv list --tags k8s --status running
+```
+
+Tag matching is case-insensitive. Multiple tags per VM are supported — filtering matches any VM that contains the specified tag.
+
+## Self-signed certificates
+
+If your Proxmox uses the default self-signed cert, disable verification:
+
+```bash
+pxinv --no-verify-ssl list
+# or
+export PXINV_VERIFY_SSL=false
+```
+
+## Contributing
+
+PRs welcome. To set up a dev environment:
+
+```bash
+git clone https://github.com/thetechiejourney/pxinv
+cd pxinv
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pxinv-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pxinv/__init__.py,sha256=JN4aiyKGaHLfu0BbuNN3l1vqDZzFg3TicOSDlGn-2Qo,76
+pxinv/cli.py,sha256=6WlkoVQ9yAGG1ImKSzBpb3G6cVyBmKyvAJ6DH56wmZE,10705
+pxinv/client.py,sha256=HBsdJsibQCUkazSjJkcHv7w3Xvu7FGF1IbFGp4X5AuI,6413
+pxinv/config.py,sha256=g1uqCheY7mNmFl5ZJFVKiJNBxU42l4GVzT83wQ8b68Y,504
+pxinv/output.py,sha256=MT9V1fTug6U_-pZhgSErJ79319Cif4f15J8Y0ARlLX4,5557
+pxinv-0.3.0.dist-info/METADATA,sha256=Zft2q9JsZg0CEXDpK3Lj39zRsujjlcova1vfedjUAKk,6966
+pxinv-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pxinv-0.3.0.dist-info/entry_points.txt,sha256=MuLSkPDem9ke_lqiZ70kCfvxGXWjUkQ4xCtvGzhuGbI,41
+pxinv-0.3.0.dist-info/top_level.txt,sha256=c0Dn29u9r-aC7GvNAdrvm2tnYz9NIz48oBecPynmeb0,6
+pxinv-0.3.0.dist-info/RECORD,,

pxinv-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pxinv-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pxinv = pxinv.cli:main

pxinv-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pxinv