Metadata-Version: 2.4
Name: pxinv
Version: 1.0.0
Summary: Proxmox VM & container inventory CLI
License: MIT
Project-URL: Homepage, https://github.com/thetechiejourney/pxinv
Project-URL: Issues, https://github.com/thetechiejourney/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
A fast CLI for inventorying and managing VMs and containers on your Proxmox homelab.

![pxinv demo](assets/demo.gif)

```
$ 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

Single host — `~/.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
```

Multiple clusters — `~/.config/pxinv/config.yaml`:
```yaml
clusters:
  home:
    host: 192.168.1.10
    user: root@pam
    token_name: pxinv
    token_value: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    verify_ssl: false

  vps:
    host: 95.216.x.x
    token_name: pxinv
    token_value: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
    verify_ssl: true
```

## Commands

### `pxinv clusters`

List all configured clusters.

```bash
pxinv clusters
```

### `pxinv list`

List all VMs and containers.

```bash
# All guests across all clusters
pxinv list

# Only a specific cluster
pxinv --cluster home list

# Filter by node, type, status or tag
pxinv list --node pve-01
pxinv list --type ct --status running
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
```

When multiple clusters are configured, a `CLUSTER` column appears automatically.

### `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 and --cluster
pxinv --cluster home watch --status running
pxinv watch --tags k8s --interval 3
```

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 --cluster vps 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`), by Proxmox tag (`tag_homelab`, `tag_k8s`, etc.) and by cluster (`cluster_home`, `cluster_vps`, 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) cluster_home -m ping
ansible -i <(pxinv ansible-inventory) running -m setup
```

Example output:

```json
{
  "all": {
    "hosts": ["homeassistant", "pihole"],
    "children": ["running", "stopped", "cluster_home", "tag_homelab", "tag_dns"]
  },
  "running": { "hosts": ["homeassistant", "pihole"] },
  "cluster_home": { "hosts": ["homeassistant", "pihole"] },
  "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_cluster": "home",
        "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
```
