ifpretty 0.8.0

Prettify and enrich ifconfig output: aligned tables, IP/MAC/scope annotations, OUI vendor lookup, live DNS/DHCP/route, and a 1h bandwidth graph.

ifpretty

Prettify and enrich ifconfig output — aligned tables, color, decoded flags, IP/MAC/scope annotations, OUI vendor lookup, live DNS/DHCP/route, a 1‑hour bandwidth graph, and run‑to‑run diffing. Built on rich.

ifpretty

The default is an essentials view: identity, routable IPs (with scope), gateway and throughput, with down / address‑less interfaces collapsed to one line. Pass -v for every field.

Install

pip install ifpretty

Requires Python ≥ 3.9. The only dependency is rich.

Usage

ifpretty                       # essentials view; runs `ifconfig` for you
ifpretty -v                    # verbose: every field + expand collapsed interfaces
ifpretty en0 en6               # limit to one or more interfaces
ifconfig | ifpretty            # or pipe ifconfig in yourself

ifpretty -r                    # --records : compact label/value record layout
ifpretty -t                    # --table   : single wide table, all fields (<=240 cols)

ifpretty -l                    # --live    : route, traffic, friendly names, DNS, DHCP (macOS)
ifpretty -c                    # --check   : ping the default gateway for latency (macOS)
ifpretty -w                    # --wan     : public IP / ASN / geo (opt-in; sends IP to ipapi.co)
ifpretty -d                    # --diff    : show what changed since the previous run
ifpretty -x                    # --explain : append a legend for the flags/options seen

ifpretty --record              # sample byte counters (run via cron to feed the 1h graph)
ifpretty --update-oui          # refresh the IEEE vendor database into the cache

Run it bare and it runs ifconfig for you; or pipe ifconfig in to control which interfaces to show. Flags compose (e.g. ifpretty -l -d -w).

What it adds

Always on (offline, deterministic):

• Per‑interface role (loopback / Ethernet·Wi‑Fi / VPN·tunnel / bridge / …).
• IP scope for every address — loopback / link‑local / ULA / private / global — plus IPv4 network + usable‑host count.
• MAC kind (universal vs locally‑administered), OUI vendor (bundled IEEE registry, no network), shared‑MAC notes (e.g. bridge members), and EUI‑64 detection.
• Media speed/duplex with a half‑duplex ⚠ warning; jumbo / sub‑1280 MTU notes.
• Decoded flag/option/nd6 bitfields; IPv6 attributes aligned into columns.
• A one‑line overview above the layout (interface count, default route, totals).

--live (macOS, cross‑references the system):

• Default route + gateway, friendly hardware‑port names, per‑interface DNS and search domains, DHCP server + lease, traffic counters (bytes + packets) and error/collision counts.

--check: pings the default gateway and reports latency / unreachable.

--wan (external, opt‑in): looks up your public IP plus ASN/ISP/geo via ipapi.co and shows it in the overview. It sends your public IP to a third party, so it is strictly opt‑in; the result is cached ~1 h, times out fast, and degrades silently offline. --update-oui refreshes the vendor database from the IEEE registry into the cache (overrides the bundled copy).

--diff: every run records a snapshot of the stable interface state (up/down, addresses, MAC, mtu, media, gateway — not volatile counters) to snapshot.json. With --diff, ifpretty prints what changed since the previous run — interfaces added/removed, status flips, added/removed IPv4/IPv6 addresses — before the normal view.

1‑hour bandwidth graph: schedule the recorder, then per‑interface Unicode sparklines (and a link‑utilization gauge) appear automatically:

# once, e.g. in `crontab -e` — use the absolute path:
* * * * * $(command -v ifpretty) --record

1h in    ▁▁▁▂▄█▅▂▁▁▁▁   peak 10.0 Mbps
1h out   ▁▂▂▄▆█▄▂▂▁▁▁   peak 533.3 Kbps
link use ████░░░░░░     40% of 1000 Mbps

Environment

• NO_COLOR=1 disables color; CLICOLOR_FORCE=1 forces it when piped.
• IFPRETTY_HISTORY — bandwidth‑samples file (default ~/.cache/ifpretty/samples.csv).
• IFPRETTY_CACHE — cache directory for the WAN lookup, refreshed OUI DB, and the diff snapshot (default ~/.cache/ifpretty/).

--live / --check / --record use macOS tools (route, netstat, networksetup, scutil, ipconfig, ping) and no‑op (or degrade) elsewhere; the parsing, formatting and offline enrichment work wherever you can pipe ifconfig output in.

Architecture

The package is split into focused modules (one responsibility each):

Module	Responsibility
model	dataclasses Inet / Inet6 / Interface
parse	raw ifconfig text → interface model
enrich	derivations, OUI, system (--live/--check), history, --wan, snapshot/diff
formatting	model values → styled (rich‑markup) strings; layout field rows
render	render strategies (boxed / records / table) + overview / legend / diff
cli	acquire input → parse → enrich → render

Dependency direction: model ← parse, enrich ← formatting ← render ← cli (no cycles).

Development

python3 -m unittest discover -s tests   # 63 tests (snapshot + unit)
ruff check src tests && mypy src

Layout snapshots are pinned to golden files; regenerate intentionally with REGEN=1 python3 tests/test_ifpretty.py.

License

MIT