ifpretty 0.9.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 --map                 # open an interactive browser map of your network
ifpretty --map 8.8.8.8         # …tracing the route to a specific target

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

--map (browser visualization): opens an interactive graph of your network — this host and its interfaces, the LAN devices/peripherals each interface talks to (from the ARP table, labelled by OUI vendor), the default gateway, and the traceroute path out to the internet (default target 1.1.1.1, or pass one). Rendered with vis-network (loaded from a CDN) into a self-contained HTML file that opens automatically in your browser.

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
topology	--map: traceroute + ARP → vis-network HTML graph in the browser
cli	acquire input → parse → enrich → render

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

Development

python3 -m unittest discover -s tests   # 67 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