Metadata-Version: 2.4
Name: invctl
Version: 0.2.0a1
Summary: Infrastructure Inventory Control for Proxmox VE
Author-email: Alexis Frère <frere.alexis974@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: devops,infrastructure,inventory,ops,proxmox
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: proxmoxer>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Description-Content-Type: text/markdown

# invctl — Infrastructure Inventory Control

[![CI](https://github.com/alfrere/invctl/actions/workflows/ci.yml/badge.svg)](https://github.com/alfrere/invctl/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/invctl)](https://pypi.org/project/invctl/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

> Get the full inventory of a Proxmox VE cluster in one command.

`invctl` connects to the Proxmox API and produces a structured, exportable snapshot of every
layer of your infrastructure: nodes, VMs, containers, storage, networking, backups, users, and
firewall rules. Run it once to get a quick picture of an unfamiliar cluster, or save dated
snapshots and diff them over time to track what changed.

## Installing / Getting started

**Linux / MacOS :**

```shell
pipx install invctl
pipx ensurepath   # adds ~/.local/bin to PATH — reload your shell after
```

Then run your first scan:

```shell
invctl scan --host pve.example.com \
  --token-id root@pam!invctl \
  --token-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

This prints a pretty-printed JSON inventory to stdout. You can also write it directly to a file:

```shell
invctl scan --output html --file report.html
```

Other install options:

```shell
uv tool install invctl   # with uv
pip install invctl        # plain pip, inside a virtualenv
```

**Windows:** `pip install invctl` works. If `invctl` is not found after install, Python's Scripts
folder is not on your PATH — find it and add it:

```powershell
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
```

### Initial Configuration

`invctl` needs credentials to reach the Proxmox API. The recommended approach is an API token:

1. Go to **Datacenter → Permissions → API Tokens** in the Proxmox web UI
2. Click **Add**, select the user, set a token ID, uncheck **Privilege Separation** for full
   read access (or scope it to `VM.Audit`, `Datastore.Audit`, etc. for least privilege)
3. Copy the token secret — it is shown only once

The minimum privileges required for a full read-only scan:

| Privilege | Used by |
|---|---|
| `VM.Audit` | VMs, containers |
| `Datastore.Audit` | Storage |
| `Sys.Audit` | Nodes, network, firewall |
| `Permissions.Read` | Users, ACLs, roles |

Store credentials in a `.env` file so you don't have to type them on every run:

```bash
# .env
PROXMOX_HOST=pve.example.com
PROXMOX_TOKEN_ID=root@pam!invctl
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

```bash
source .env && invctl scan
```

Most home-lab Proxmox installs use a self-signed certificate. Pass `--no-verify-ssl` to skip
TLS validation:

```shell
invctl scan --host 192.168.1.10 --no-verify-ssl
```

## Features

* Collects **nodes** (CPU, memory, kernel, PVE version, subscription status), **VMs** and **LXC
  containers** (config, runtime stats, snapshots, tags), **storage**, **network**, **backups**,
  **users & ACLs**, and **firewall** rules — all in one pass
* Export as **JSON**, **HTML**, or **Markdown** — pipe to `jq`, open in a browser, or commit
  to a repo
* **Selective sections** — scan only what you need with `--sections vms,containers`
* **Diff two snapshots** — see exactly what changed between any two inventory files: added or
  removed VMs, config changes, storage drift, user changes
* Works with both **API token** and **username/password** authentication

## Configuration

| Flag | Env var | Default | Description |
|---|---|---|---|
| `--host` | `PROXMOX_HOST` | | Proxmox hostname or IP address |
| `--token-id` | `PROXMOX_TOKEN_ID` | | API token ID (`user@realm!tokenname`) |
| `--token-secret` | `PROXMOX_TOKEN_SECRET` | | API token secret |
| `--user` | `PROXMOX_USER` | | Username for password-based auth (`user@realm`) |
| `--password` | `PROXMOX_PASSWORD` | | Password for password-based auth |
| `--port` | | `8006` | Proxmox API port |
| `--no-verify-ssl` | | off | Disable TLS certificate verification |
| `--output` | | `json` | Output format: `json`, `html`, `markdown` (scan); `text` also available for diff |
| `--file` | | | Write output to a file instead of stdout |
| `--sections` | | all | Comma-separated sections: `cluster,nodes,vms,containers,storage,network,backups,users,firewall` |
| `--pretty` / `--no-pretty` | | `--pretty` | Pretty-print JSON output |

## Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests
are warmly welcome.

Start by cloning and installing the dev dependencies:

```shell
git clone https://github.com/alfrere/invctl.git
cd invctl/
uv sync
```

`uv sync` installs the package and all dev dependencies into a local virtualenv. Before
submitting a PR, make sure the test suite and linters pass:

```shell
uv run pytest
uv run ruff check .
uv run mypy invctl/
```

To build a distribution wheel locally:

```shell
uv build
```

If you find a bug, vulnerability or have a feature request, please open an issue on GitHub.

## Roadmap

* **Proxmox Datacenter Manager support :** Connect to a PDM instance to scan all managed
  clusters in one pass, without running the tool cluster by cluster.
* **Full diff coverage :** Extend `invctl diff` to cover nodes, network, firewall, and backups,
  which are collected but currently not compared.
* **Filtering :** `--filter` flag to scope a scan by node, status, or tag (e.g.
  `--filter node=pve1`, `--filter status=running`, `--filter tag=prod`).
* **CSV export :** flat spreadsheet-friendly export of VMs and containers
* **Config file :** `~/.invctl.toml` for storing host, credentials, and defaults so you don't
  need env vars or flags on every run

## Links

- Repository: https://github.com/alfrere/invctl
- Issue tracker: https://github.com/alfrere/invctl/issues
- PyPI: https://pypi.org/project/invctl/

## Licensing

The code in this project is licensed under the Apache 2.0 license. See [LICENSE](LICENSE) for
the full text.
