ipmg 2.3.0__tar.gz → 3.0.0__tar.gz

{ipmg-2.3.0/src/ipmg.egg-info → ipmg-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 2.3.0
+Version: 3.0.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -29,15 +29,19 @@ Classifier: Environment :: Console
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas>=2.2.2
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: rich>=13.0
-Requires-Dist: fastapi>=0.110
-Requires-Dist: pydantic>=2.7
-Requires-Dist: uvicorn>=0.27
-Requires-Dist: websockets>=12
-Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: pydantic>=2.7; extra == "web"
+Requires-Dist: uvicorn>=0.27; extra == "web"
+Requires-Dist: websockets>=12; extra == "web"
+Requires-Dist: python-multipart>=0.0.9; extra == "web"
+Provides-Extra: all
+Requires-Dist: ipmg[web]; extra == "all"
 Provides-Extra: dev
+Requires-Dist: ipmg[web]; extra == "dev"
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
@@ -150,11 +154,24 @@ The formula lives in
 and is updated with every release. Upgrade with `brew upgrade ipmg`, remove
 with `brew uninstall ipmg`.
 
-**Windows — two commands in PowerShell:**
+**Windows — one command in PowerShell:**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-uv tool install ipmg
+irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
+```
+
+It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
+administrator rights: it installs uv if it is missing, installs IPMG, adds it
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+```
+
+**Docker (amd64 and arm64):**
+
+```bash
+docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24
 ```
 
 Then check it works, on any platform:
@@ -163,6 +180,38 @@ Then check it works, on any platform:
 ipmg --version
 ```
 
+### Running in Docker
+
+The image carries `ping`, runs as an unprivileged user (uid 10001), and keeps
+everything a scan writes (reports and the history database) in `/data`. Mount
+a volume there to keep it between runs:
+
+```bash
+docker run --rm -v ipmg-data:/data ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24 --compare
+```
+
+Ping needs no added capability: it uses the unprivileged ICMP sockets that
+Docker and containerd enable by default, so it also works with
+`--cap-drop ALL` and under Kubernetes' restricted pod security profile. To
+scan your LAN rather than the container's network, add `--network host`
+(Linux).
+
+For IPMG Web, use the [`compose.yaml`](https://github.com/sameeralam3127/ipmg/blob/main/compose.yaml)
+in this repository. Inside a container IPMG Web must listen on `0.0.0.0` or
+nothing outside the container could reach it, so the compose file starts it
+with `web --host 0.0.0.0` and publishes the port on the host's `127.0.0.1`
+only. Set a fixed `IPMG_WEB_TOKEN` in `.env`, then:
+
+```bash
+docker compose up -d                                      # http://127.0.0.1:8080/#token=<your token>
+docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in the same history
+```
+
+Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
+network over plain HTTP; put a reverse proxy with TLS in front first. Images
+are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+`latest`.
+
 ### Installing with pip
 
 `pip install ipmg` works inside a virtual environment, and inside one only.
@@ -192,6 +241,22 @@ python3 -m venv ~/.venvs/ipmg
 
 Please do not reach for `--break-system-packages`. It does what it says.
 
+### What gets installed
+
+`pip install ipmg` is the lean core: scanning, every report format
+(Excel included), history, change detection, notifications, and exit codes.
+It is about 9 MB and 7 packages. IPMG Web, the browser UI with its REST API
+and Prometheus `/metrics`, is the optional `web` extra, because its server
+stack is most of the weight:
+
+```bash
+pip install "ipmg[web]"             # or: uv tool install "ipmg[web]", pipx install "ipmg[web]"
+```
+
+The one-line installers, Homebrew, and the Docker image install it with the
+`web` extra already. Run `ipmg web` without it and IPMG tells you the command
+that adds it.
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -331,8 +396,10 @@ Or pick a ready-made command:
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
 | Scan hosts listed in a file | `ipmg --input targets.txt` |
+| Scan a file plus a few extra hosts | `ipmg --input targets.txt 10.0.0.0/30 10.0.0.5` |
 | Get names, not just IP addresses | `ipmg --input targets.txt --resolve` |
 | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
+| Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
 | See hosts appear as they answer | `ipmg --input 192.168.1.0/24 --stream` |
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
@@ -514,9 +581,11 @@ of it (see [Security](#security)).
 
 Anywhere IPMG takes `--input`, you can give it any of these:
 
-- **A single IP** — `8.8.8.8`
-- **A CIDR block** — `10.0.0.0/24`
-- **A range** — `10.0.0.1-10.0.0.200`
+- **A single IP** — `8.8.8.8`, or IPv6 such as `2001:db8::1` or a link-local
+  `fe80::1%eth0`
+- **A CIDR block** — `10.0.0.0/24`, or an IPv6 prefix up to 65,536 hosts
+  (`2001:db8::/112`)
+- **A range** — `10.0.0.1-10.0.0.200` or `2001:db8::10-2001:db8::20`
 - **A text file** — one IP or CIDR per line. Blank lines and `#` comments are
   ignored, so you can annotate it:
 
@@ -526,7 +595,7 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   192.168.1.0/30
   ```
 
-- **An Excel or CSV file** (`.xlsx`, `.xls`, `.csv`) — must contain a column
+- **An Excel or CSV file** (`.xlsx`, `.csv`) — must contain a column
   named `IP Address`. Cells can hold single addresses or CIDR blocks:
 
   | IP Address  |
@@ -534,9 +603,42 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   | 192.168.1.1 |
   | 10.0.1.0/30 |
 
-Duplicate targets are removed automatically, and one scan expands to at most
-65,536 hosts — larger CIDR blocks or ranges are rejected up front, before the
-scan starts.
+- **A JSON file** (`.json`) — a list of addresses, a list of objects keyed by
+  `IP Address`, `ip`, or `target`, or an object with a `targets` or `ips` array:
+
+  ```json
+  ["192.168.1.1", "10.0.1.0/30"]
+  ```
+
+  Because `IP Address` is one of the keys it accepts, a report IPMG wrote with
+  `--formats json` can be fed straight back in:
+
+  ```bash
+  ipmg --input results_20260628_120000.json
+  ```
+
+`--input` takes as many of these as you like, in any mix, and may also be
+repeated:
+
+```bash
+ipmg --input targets.txt 10.0.0.0/30 10.0.0.5
+ipmg --input targets.txt --input 10.0.0.5     # the same thing
+```
+
+IPv4 and IPv6 targets mix freely in one scan, and reports, history, and change
+detection handle both. An IPv6 `/64` holds 2^64 addresses, far too many to
+sweep one by one, so it is rejected with a pointer to `--discover ipv6`, which
+finds the hosts on your local links through neighbour discovery instead:
+
+```bash
+ipmg --discover ipv6      # IPv6 neighbours on the local links
+ipmg --discover all       # the IPv4 /24 and the IPv6 neighbours together
+```
+
+Duplicate targets are removed automatically — across sources too, so a host
+that is both in the file and on the command line is scanned once — and one scan
+expands to at most 65,536 hosts in total. Larger CIDR blocks, ranges, or
+combinations are rejected up front, before the scan starts.
 
 ---
 
@@ -586,6 +688,22 @@ preferring `jsonl` or `csv` (current to the last host) over `json` or `xlsx`
 (current to the last autosave). Hosts dropped from the target list since are
 left out of the finished report.
 
+**Piping results into a script.** `--json` prints the finished scan to stdout as
+a JSON array, and `--jsonl` prints one object per host the moment its probe
+finishes. The human output moves to stderr, so stdout is nothing but data and no
+temp file or glob is needed:
+
+```bash
+ipmg --input 10.0.0.0/24 --json | jq '.[] | select(.Status == "Active")'
+ipmg --input 10.0.0.0/24 --jsonl | while read -r host; do notify "$host"; done
+ipmg --input 10.0.0.0/24 --json 2>/dev/null > hosts.json   # data only
+```
+
+The field names are the report columns above, and both flags print a host
+identically — `--json` is what `--jsonl` prints, gathered into an array. Unless
+you ask for `--formats` explicitly, a piped scan writes no report file at all.
+Exit codes are unchanged.
+
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
 HTTPS, RDP, SMB, FTP, SMTP, DNS, MSSQL, MySQL, PostgreSQL by default)
@@ -602,6 +720,61 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## Default options in a file
+
+If every run repeats the same flags, put them in **`ipmg.toml`** next to your
+work instead:
+
+```toml
+threads = 200
+timeout = 1
+resolve = true
+formats = ["md", "csv"]
+
+[profile.datacenter]
+threads = 400
+scan-ports = true
+ports = "22,80,443"
+```
+
+```bash
+ipmg --input targets.txt                        # uses the file's defaults
+ipmg --input targets.txt --profile datacenter   # and the profile on top
+ipmg --input targets.txt --threads 20           # a flag always wins
+```
+
+Any long flag can be a key, written as the flag is (`scan-ports`) or with
+underscores (`scan_ports`). A switch takes `true` to mean "as if the flag were
+passed" — `no-history = true` is `--no-history`. Files are read from
+`~/.config/ipmg/config.toml` first (or `$XDG_CONFIG_HOME`), then `./ipmg.toml`
+on top, so a project can override your global defaults:
+
+| Flag | What it does |
+| --- | --- |
+| `--config PATH` | Read that file instead of searching |
+| `--no-config` | Ignore every file and use the built-in defaults |
+| `--profile NAME` | Apply the `[profile.NAME]` section as well |
+
+**The command line always wins.** A flag that appears on it ignores the file
+entirely for that flag — including `--input`, which merges several sources on
+one command line but replaces the file's list rather than adding to it.
+
+A key that is not a flag, a value of the wrong type, or a value outside a
+flag's choices is an error naming the key and the file it came from:
+
+```text
+✗ Unknown option 'thredas' in ipmg.toml. Did you mean 'threads'?
+✗ 'formats' in ipmg.toml: 'pdf' is not one of xlsx, csv, json, jsonl, md.
+```
+
+A project's `./ipmg.toml` comes with whatever directory you scan from,
+including a repository you just cloned, so it cannot say where results are
+sent: the `--notify-*` destinations and `--smtp-*` settings are only read from
+`~/.config/ipmg/config.toml` or a file you pass with `--config`. A file also
+cannot combine flags that exclude each other, such as `json` and `jsonl`.
+
+---
+
 ## All options
 
 `ipmg --help` always lists the current set. Grouped for reading:
@@ -610,10 +783,12 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 | Flag | Default | Description |
 | --- | --- | --- |
-| `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
-| `--discover` | off | Auto-detect and scan the local subnet instead |
+| `--input` | `ip_list.xlsx` | What to scan: one or more files (`.xlsx`, `.xls`, `.csv`, `.json`, `.txt`, `.list`), IPs, CIDR blocks, or ranges (`10.0.0.1-10.0.0.50`), merged and de-duplicated |
+| `--discover [FAMILY]` | off | Scan this machine's networks instead: `ipv4` (the default) sweeps the local /24, `ipv6` finds link neighbours, `all` does both |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` (no file at all with `--json`/`--jsonl`) |
+| `--json` | off | Print the finished scan to stdout as a JSON array, human output on stderr |
+| `--jsonl` | off | Stream one JSON object per host to stdout as each probe finishes |
 | `--no-incremental` | off | Only write the report once the scan has finished |
 | `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 | `--resume` | off | Finish an interrupted scan from its partial report (newest one, or the path given) |
@@ -645,6 +820,9 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-all` | off | Stream every result, including hosts that did not answer (implies `--stream`) |
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
+| `--config` | search | Read defaults from this file instead of searching for `ipmg.toml` |
+| `--no-config` | off | Ignore every configuration file |
+| `--profile` | none | Apply a `[profile.NAME]` section from the configuration file |
 
 **Exit status**
 

{ipmg-2.3.0 → ipmg-3.0.0}/README.md

@@ -102,11 +102,24 @@ The formula lives in
 and is updated with every release. Upgrade with `brew upgrade ipmg`, remove
 with `brew uninstall ipmg`.
 
-**Windows — two commands in PowerShell:**
+**Windows — one command in PowerShell:**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-uv tool install ipmg
+irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
+```
+
+It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
+administrator rights: it installs uv if it is missing, installs IPMG, adds it
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+```
+
+**Docker (amd64 and arm64):**
+
+```bash
+docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24
 ```
 
 Then check it works, on any platform:
@@ -115,6 +128,38 @@ Then check it works, on any platform:
 ipmg --version
 ```
 
+### Running in Docker
+
+The image carries `ping`, runs as an unprivileged user (uid 10001), and keeps
+everything a scan writes (reports and the history database) in `/data`. Mount
+a volume there to keep it between runs:
+
+```bash
+docker run --rm -v ipmg-data:/data ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24 --compare
+```
+
+Ping needs no added capability: it uses the unprivileged ICMP sockets that
+Docker and containerd enable by default, so it also works with
+`--cap-drop ALL` and under Kubernetes' restricted pod security profile. To
+scan your LAN rather than the container's network, add `--network host`
+(Linux).
+
+For IPMG Web, use the [`compose.yaml`](https://github.com/sameeralam3127/ipmg/blob/main/compose.yaml)
+in this repository. Inside a container IPMG Web must listen on `0.0.0.0` or
+nothing outside the container could reach it, so the compose file starts it
+with `web --host 0.0.0.0` and publishes the port on the host's `127.0.0.1`
+only. Set a fixed `IPMG_WEB_TOKEN` in `.env`, then:
+
+```bash
+docker compose up -d                                      # http://127.0.0.1:8080/#token=<your token>
+docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in the same history
+```
+
+Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
+network over plain HTTP; put a reverse proxy with TLS in front first. Images
+are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+`latest`.
+
 ### Installing with pip
 
 `pip install ipmg` works inside a virtual environment, and inside one only.
@@ -144,6 +189,22 @@ python3 -m venv ~/.venvs/ipmg
 
 Please do not reach for `--break-system-packages`. It does what it says.
 
+### What gets installed
+
+`pip install ipmg` is the lean core: scanning, every report format
+(Excel included), history, change detection, notifications, and exit codes.
+It is about 9 MB and 7 packages. IPMG Web, the browser UI with its REST API
+and Prometheus `/metrics`, is the optional `web` extra, because its server
+stack is most of the weight:
+
+```bash
+pip install "ipmg[web]"             # or: uv tool install "ipmg[web]", pipx install "ipmg[web]"
+```
+
+The one-line installers, Homebrew, and the Docker image install it with the
+`web` extra already. Run `ipmg web` without it and IPMG tells you the command
+that adds it.
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -283,8 +344,10 @@ Or pick a ready-made command:
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
 | Scan hosts listed in a file | `ipmg --input targets.txt` |
+| Scan a file plus a few extra hosts | `ipmg --input targets.txt 10.0.0.0/30 10.0.0.5` |
 | Get names, not just IP addresses | `ipmg --input targets.txt --resolve` |
 | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
+| Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
 | See hosts appear as they answer | `ipmg --input 192.168.1.0/24 --stream` |
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
@@ -466,9 +529,11 @@ of it (see [Security](#security)).
 
 Anywhere IPMG takes `--input`, you can give it any of these:
 
-- **A single IP** — `8.8.8.8`
-- **A CIDR block** — `10.0.0.0/24`
-- **A range** — `10.0.0.1-10.0.0.200`
+- **A single IP** — `8.8.8.8`, or IPv6 such as `2001:db8::1` or a link-local
+  `fe80::1%eth0`
+- **A CIDR block** — `10.0.0.0/24`, or an IPv6 prefix up to 65,536 hosts
+  (`2001:db8::/112`)
+- **A range** — `10.0.0.1-10.0.0.200` or `2001:db8::10-2001:db8::20`
 - **A text file** — one IP or CIDR per line. Blank lines and `#` comments are
   ignored, so you can annotate it:
 
@@ -478,7 +543,7 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   192.168.1.0/30
   ```
 
-- **An Excel or CSV file** (`.xlsx`, `.xls`, `.csv`) — must contain a column
+- **An Excel or CSV file** (`.xlsx`, `.csv`) — must contain a column
   named `IP Address`. Cells can hold single addresses or CIDR blocks:
 
   | IP Address  |
@@ -486,9 +551,42 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   | 192.168.1.1 |
   | 10.0.1.0/30 |
 
-Duplicate targets are removed automatically, and one scan expands to at most
-65,536 hosts — larger CIDR blocks or ranges are rejected up front, before the
-scan starts.
+- **A JSON file** (`.json`) — a list of addresses, a list of objects keyed by
+  `IP Address`, `ip`, or `target`, or an object with a `targets` or `ips` array:
+
+  ```json
+  ["192.168.1.1", "10.0.1.0/30"]
+  ```
+
+  Because `IP Address` is one of the keys it accepts, a report IPMG wrote with
+  `--formats json` can be fed straight back in:
+
+  ```bash
+  ipmg --input results_20260628_120000.json
+  ```
+
+`--input` takes as many of these as you like, in any mix, and may also be
+repeated:
+
+```bash
+ipmg --input targets.txt 10.0.0.0/30 10.0.0.5
+ipmg --input targets.txt --input 10.0.0.5     # the same thing
+```
+
+IPv4 and IPv6 targets mix freely in one scan, and reports, history, and change
+detection handle both. An IPv6 `/64` holds 2^64 addresses, far too many to
+sweep one by one, so it is rejected with a pointer to `--discover ipv6`, which
+finds the hosts on your local links through neighbour discovery instead:
+
+```bash
+ipmg --discover ipv6      # IPv6 neighbours on the local links
+ipmg --discover all       # the IPv4 /24 and the IPv6 neighbours together
+```
+
+Duplicate targets are removed automatically — across sources too, so a host
+that is both in the file and on the command line is scanned once — and one scan
+expands to at most 65,536 hosts in total. Larger CIDR blocks, ranges, or
+combinations are rejected up front, before the scan starts.
 
 ---
 
@@ -538,6 +636,22 @@ preferring `jsonl` or `csv` (current to the last host) over `json` or `xlsx`
 (current to the last autosave). Hosts dropped from the target list since are
 left out of the finished report.
 
+**Piping results into a script.** `--json` prints the finished scan to stdout as
+a JSON array, and `--jsonl` prints one object per host the moment its probe
+finishes. The human output moves to stderr, so stdout is nothing but data and no
+temp file or glob is needed:
+
+```bash
+ipmg --input 10.0.0.0/24 --json | jq '.[] | select(.Status == "Active")'
+ipmg --input 10.0.0.0/24 --jsonl | while read -r host; do notify "$host"; done
+ipmg --input 10.0.0.0/24 --json 2>/dev/null > hosts.json   # data only
+```
+
+The field names are the report columns above, and both flags print a host
+identically — `--json` is what `--jsonl` prints, gathered into an array. Unless
+you ask for `--formats` explicitly, a piped scan writes no report file at all.
+Exit codes are unchanged.
+
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
 HTTPS, RDP, SMB, FTP, SMTP, DNS, MSSQL, MySQL, PostgreSQL by default)
@@ -554,6 +668,61 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## Default options in a file
+
+If every run repeats the same flags, put them in **`ipmg.toml`** next to your
+work instead:
+
+```toml
+threads = 200
+timeout = 1
+resolve = true
+formats = ["md", "csv"]
+
+[profile.datacenter]
+threads = 400
+scan-ports = true
+ports = "22,80,443"
+```
+
+```bash
+ipmg --input targets.txt                        # uses the file's defaults
+ipmg --input targets.txt --profile datacenter   # and the profile on top
+ipmg --input targets.txt --threads 20           # a flag always wins
+```
+
+Any long flag can be a key, written as the flag is (`scan-ports`) or with
+underscores (`scan_ports`). A switch takes `true` to mean "as if the flag were
+passed" — `no-history = true` is `--no-history`. Files are read from
+`~/.config/ipmg/config.toml` first (or `$XDG_CONFIG_HOME`), then `./ipmg.toml`
+on top, so a project can override your global defaults:
+
+| Flag | What it does |
+| --- | --- |
+| `--config PATH` | Read that file instead of searching |
+| `--no-config` | Ignore every file and use the built-in defaults |
+| `--profile NAME` | Apply the `[profile.NAME]` section as well |
+
+**The command line always wins.** A flag that appears on it ignores the file
+entirely for that flag — including `--input`, which merges several sources on
+one command line but replaces the file's list rather than adding to it.
+
+A key that is not a flag, a value of the wrong type, or a value outside a
+flag's choices is an error naming the key and the file it came from:
+
+```text
+✗ Unknown option 'thredas' in ipmg.toml. Did you mean 'threads'?
+✗ 'formats' in ipmg.toml: 'pdf' is not one of xlsx, csv, json, jsonl, md.
+```
+
+A project's `./ipmg.toml` comes with whatever directory you scan from,
+including a repository you just cloned, so it cannot say where results are
+sent: the `--notify-*` destinations and `--smtp-*` settings are only read from
+`~/.config/ipmg/config.toml` or a file you pass with `--config`. A file also
+cannot combine flags that exclude each other, such as `json` and `jsonl`.
+
+---
+
 ## All options
 
 `ipmg --help` always lists the current set. Grouped for reading:
@@ -562,10 +731,12 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 | Flag | Default | Description |
 | --- | --- | --- |
-| `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
-| `--discover` | off | Auto-detect and scan the local subnet instead |
+| `--input` | `ip_list.xlsx` | What to scan: one or more files (`.xlsx`, `.xls`, `.csv`, `.json`, `.txt`, `.list`), IPs, CIDR blocks, or ranges (`10.0.0.1-10.0.0.50`), merged and de-duplicated |
+| `--discover [FAMILY]` | off | Scan this machine's networks instead: `ipv4` (the default) sweeps the local /24, `ipv6` finds link neighbours, `all` does both |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` (no file at all with `--json`/`--jsonl`) |
+| `--json` | off | Print the finished scan to stdout as a JSON array, human output on stderr |
+| `--jsonl` | off | Stream one JSON object per host to stdout as each probe finishes |
 | `--no-incremental` | off | Only write the report once the scan has finished |
 | `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 | `--resume` | off | Finish an interrupted scan from its partial report (newest one, or the path given) |
@@ -597,6 +768,9 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-all` | off | Stream every result, including hosts that did not answer (implies `--stream`) |
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
+| `--config` | search | Read defaults from this file instead of searching for `ipmg.toml` |
+| `--no-config` | off | Ignore every configuration file |
+| `--profile` | none | Apply a `[profile.NAME]` section from the configuration file |
 
 **Exit status**
 

{ipmg-2.3.0 → ipmg-3.0.0}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "2.3.0"  # Managed automatically by semantic-release
+version = "3.0.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -48,15 +48,14 @@ classifiers = [
     "Environment :: Console",
 ]
 
+# The core is what a scan needs: the terminal UI, Excel reports and input,
+# and the config file parser. IPMG Web's server stack is the `web` extra.
 dependencies = [
-    "pandas>=2.2.2",
     "openpyxl>=3.1",
     "rich>=13.0",
-    "fastapi>=0.110",
-    "pydantic>=2.7",
-    "uvicorn>=0.27",
-    "websockets>=12",
-    "python-multipart>=0.0.9",
+    # tomllib is in the standard library from 3.11; tomli 2.x is the same
+    # parser with the same API, so the floor must not drop below it.
+    "tomli>=2.0.1; python_version < '3.11'",
 ]
 
 [project.urls]
@@ -67,7 +66,18 @@ Issues = "https://github.com/sameeralam3127/ipmg/issues"
 Changelog = "https://github.com/sameeralam3127/ipmg/releases"
 
 [project.optional-dependencies]
+# IPMG Web (`ipmg web`): the browser UI, its REST API, and /metrics.
+web = [
+    "fastapi>=0.110",
+    "pydantic>=2.7",
+    "uvicorn>=0.27",
+    "websockets>=12",
+    "python-multipart>=0.0.9",
+]
+# Everything; what the one-line installers and the Docker image install.
+all = ["ipmg[web]"]
 dev = [
+    "ipmg[web]",
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.4",
@@ -86,6 +96,7 @@ ipmg = "ipmg.cli.commands:run"
 
 [dependency-groups]
 dev = [
+    "ipmg[web]",
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.4",

{ipmg-2.3.0 → ipmg-3.0.0}/src/ipmg/__init__.py

@@ -2,4 +2,4 @@
 ipmg - IP Management & Ping Monitoring Tool
 """
 
-__version__ = "2.3.0"
+__version__ = "3.0.0"