EthUI

One keyboard-driven network-interface TUI, with native Linux and macOS backends.

EthUI makes interface inspection, diagnostics, and configuration discoverable without hiding the command that does the work. The curses interface, navigation, search, caching, confirmation model, and output viewer are shared. At the last responsible moment, a backend resolves the requested capability to Linux ethtool/ip or the native BSD and Apple networking utilities on Darwin.

There are no third-party Python runtime dependencies.

Linux ethtool is powerful but broad. macOS distributes the same networking responsibilities across ifconfig, netstat, route, networksetup, scutil, ipconfig, and system_profiler. EthUI provides one coherent place to:

• Browse active, inactive, physical, and virtual interfaces.
• Inspect overview, counters, media, and hardware information on either OS.
• Reach deeper platform-native diagnostics from a searchable command palette.
• Keep ordinary sessions read-only and require deliberate confirmation for changes.
• See native command output and errors verbatim instead of translating them into false certainty.
• Preview the exact command before anything alters interface state.

The display adapts to terminal size, operating system, and the interfaces present on the machine.

 ethui · Darwin                                               READ-ONLY
 [Overview]  Statistics  Media  Hardware  MTU  Link  Routes  DNS
 INTERFACES 1/24         │ Overview — en0
  ● en0                  │ connected  00:11:22:33:44:55  ifindex 14
  ● en1                  │
  ○ en7                  │ en0: flags=8863<UP,BROADCAST,SMART,RUNNING,...>
  ● awdl0                │     mtu 1500
  ● llw0                 │     inet 192.0.2.10 netmask 0xffffff00
  ● utun0                │     media: autoselect
  ● utun1                │     status: active
                         │
─────────────────────────┴─────────────────────────────────────────────
 ↑↓ interface  ←→ page  PgUp/PgDn scroll  p commands  r refresh  ? help

The interface list scrolls independently, so systems with many Darwin utun devices remain navigable.

With Homebrew, install Python and pipx, then install EthUI from its checkout:

brew install python pipx
git clone https://github.com/CivicBrands/EthUI.git
cd EthUI
pipx install .
pipx ensurepath

Open a new terminal if pipx ensurepath changed your shell path, then verify and launch:

command -v ethui
ethui --version
ethui

Install the native backend tools, clone EthUI, and install it into an isolated pipx environment:

sudo apt update
sudo apt install ethtool iproute2 python3 pipx git
git clone https://github.com/CivicBrands/EthUI.git
cd EthUI
pipx install .
pipx ensurepath

Open a new terminal if needed, then verify and launch:

command -v ethui
ethui --version
ethtool --version
ethui

Already inside a checkout containing pyproject.toml? The installation command is literally pipx install .—the dot is the package specification for the current project.

Select a particular interface at startup when useful:

ethui en0

EthUI starts in read-only mode for ordinary users. To permit configuration and disruptive diagnostics to execute, deliberately start it as root:

sudo "$(command -v ethui)"

Changing network settings can interrupt connectivity. On a remote machine, make sure you have console access or another recovery path before using root mode.

Four logical dashboard screens are shared across Linux and Darwin. Only their final native command differs:

Linux then adds direct pages for Features, Channels, Rings, Coalesce, Pause, EEE, and FEC. Darwin adds MTU, Link, Routes, and DNS.

The command palette follows the same rule. Linux exposes supported ethtool 7.x inspection, configuration, PHY, transceiver, EEPROM, reset, and firmware commands. Darwin exposes native media, MTU, queue, protocol, routing, DNS, DHCP, service-order, Wi-Fi power, and interface-state operations. Linux-only firmware actions never appear in the Darwin palette.

net-tools is not used as a compatibility layer. macOS ships BSD utilities that sometimes share Linux command names but not their complete syntax or semantics. EthUI treats each operating system as an independent backend behind a common capability contract.

Read operations run immediately and display the native response. Configuration operations collect only the additional arguments; the backend supplies the selected interface and platform command.

Before a change runs, EthUI shows the complete command and requires confirmation based on its risk class:

Press Escape from an argument or confirmation dialog to cancel without running anything.

EthUI is deliberately conservative, but it cannot make unsafe network or hardware operations safe.

• State-changing operations are blocked unless EthUI was started as root.
• Commands execute as argument arrays, never through a shell. Shell operators, substitutions, and redirections in entered text are not evaluated.
• Interface names come from native discovery: /sys/class/net on Linux and one ifconfig -a snapshot on Darwin.
• The exact backend command is shown before execution.
• Higher-risk operations require increasingly specific confirmation.
• Driver and operating-system failures are shown verbatim.
• The palette contains only commands registered by the active backend.

The presence of an operation does not mean a particular NIC, PHY, transceiver, firmware, driver, or macOS network service supports it. The operating system remains authoritative.

The terminal must be at least 58 columns wide and 12 rows tall. Other Linux distributions and macOS versions may work when they provide compatible commands, but they have not yet been validated by this project.

ethui: command not found after installation

First run pipx list and confirm that an ethui environment exists. If it does not, return to the checkout and run pipx install .. If it does, run pipx ensurepath, open a new terminal, and check command -v ethui again.

pipx reports that package_spec is missing

From the directory containing EthUI's pyproject.toml, run exactly pipx install .. Commands that name unrelated Python libraries do not install EthUI.

Linux reports that ethtool is missing

Install the Ubuntu package with sudo apt install ethtool.

A page says the operation is not supported

That response comes from the selected backend command or operating system. Virtual interfaces commonly lack physical media and hardware controls. This does not necessarily mean the TUI failed.

A change says it requires root

Quit EthUI and restart it with sudo "$(command -v ethui)". EthUI does not attempt to elevate itself from inside the interface.

The selected interface disappears below the sidebar

Upgrade to EthUI 0.1.1 or newer. The interface sidebar scrolls with selection.

The layout is replaced by a terminal-size warning

Resize the terminal to at least 58×12. More width is useful for counters and verbose hardware output.

Platform divergence is intentionally late:

Shared App/TUI
  └── PlatformBackend contract
        ├── capability catalog
        ├── interface discovery
        ├── direct argv execution
        └── prerequisite check
              ├── LinuxBackend
              └── DarwinBackend

The shared application owns curses rendering, interface-list scrolling, key handling, page navigation, search, output caching, background execution, command previews, and confirmation. Backends own only native discovery, capabilities, prerequisites, and argv resolution.

Run EthUI directly from a checkout on either supported platform:

PYTHONPATH=src python3 -m ethui

Run the dependency-free test suite:

PYTHONPATH=src python3 -m unittest discover -s tests

Build an installable wheel:

python3 -m pip wheel .

The source is intentionally small:

• src/ethui/app.py contains the fully shared curses application.
• src/ethui/backends.py is the single runtime platform-divergence point.
• src/ethui/catalog.py declares shared logical screens and native capabilities.
• src/ethui/system.py contains the shared process model and native discovery parsers.
• tests/ covers catalogs, backend selection, command construction, discovery, privilege gating, and shell-safe previews.

Contributions should preserve four invariants: one shared TUI, the latest practical platform divergence, direct argv execution without a shell, and explicit confirmation before state changes.

EthUI 0.1.1 adds the Darwin backend. All Darwin dashboard commands have been exercised on macOS 27.0; Linux command construction and backend routing are automated-test covered. Broader hardware, driver, macOS-version, and live Ubuntu testing remain valuable.

EthUI is available under the MIT License.