retch-cli 0.18.0

# retch

A fast, feature-rich system information fetcher written in Rust.

> **Note**: The crate is published as `retch-cli` on crates.io because the name `retch` was already taken.  
> Users interact with the tool as `retch` (binary name and config directory `~/.config/retch/`).

## Status

**Active and usable.**  
retch is under active development with a working core, rich system information output, theming, config support, and high-quality distro logos (ASCII, plus graphical logos via the Kitty, iTerm2 and Sixel protocols with a Chafa fallback).

> **Note**: This project was 100% vibe coded using Grok, Gemini and Claude. Real programmers are welcome.

## Features

- **Concurrent Execution**: Scoped multi-threading (`std::thread::scope`) fetches slow system properties (GPUs, packages, network, displays, audio, Bluetooth, etc.) concurrently to keep execution blazing fast.
- **Cross-Platform**: First-class support for Linux (Fedora, Ubuntu, Arch, etc.), macOS (Darwin), and Windows (Win32).
- **Rich Hardware Detection**:
  - **Multi-GPU & VRAM**: Detects multiple graphics cards (supports AMD/NVIDIA/Apple Silicon; translates AMD codenames like Phoenix1 to marketing names).
  - **Displays**: Raw EDID parser reads monitor vendor/model names, preferred resolutions, refresh rates (via Detailed Timing Descriptors), and generates unique serial ID suffixes for identical models.
  - **Motherboard & BIOS**: Parses motherboard manufacturer/model and BIOS version/vendor details.
  - **Camera/Webcam**: Queries connected webcam and camera device names.
  - **Gamepad/Controller**: Enumerates wired and wireless game controllers (Xbox, PlayStation, DualShock, DualSense, Nintendo Joy-Con, etc.).
  - **Keyboard & Mouse** (Linux, macOS): Lists connected keyboards and pointing devices, de-duplicated by name. Linux reads `/proc/bus/input/devices`; macOS enumerates IOKit `IOHIDDevice` interfaces on HID usage page 1. Classification is exclusive and conservative: a peripheral paired through a Logitech Unifying/Bolt receiver is presented by the kernel with a *merged* capability set that is identical for a keyboard and a mouse (same handlers, same `rel`/`key` bitmaps, same udev tags, same HID report descriptor), so retch resolves those via the HID++ driver's battery model name and otherwise lists the device in **neither** field rather than asserting the wrong one. macOS does not present that ambiguity: it publishes one HID interface per role, so the kernel states the class directly and a composite device such as an internal keyboard-and-trackpad is correctly listed under both fields.
  - **TPM**: Reports the Trusted Platform Module specification version (`2.0`, `1.2`) from `/sys/class/tpm` (Linux).
  - **Audio Devices**: Detects active audio servers (PipeWire, PulseAudio, ALSA on Linux; CoreAudio on macOS; Windows Audio on Windows).
  - **Disks & Temp**: Measures active disk mounts (hiding loopback/temporary volumes) and temperature sensors.
  - **Disk & Network Throughput**: `disk-io` and `net-io` rates, measured over the run's own collection window rather than a dedicated sleep (Linux, Windows, macOS).
  - **Graphics APIs**: Vulkan, OpenGL and OpenCL versions from the installed loaders (Linux, Windows, macOS; full mode). Each is simply absent when its loader is not installed.
  - **Physical Memory (`phys-mem`)**: Per-DIMM type, capacity, and speed via `dmidecode` (Linux, requires root), `system_profiler` (macOS), or the SMBIOS table read natively (Windows, no PowerShell and no admin). On Linux, shows the module's actual running speed alongside its rated speed when they differ (e.g. `4800 MT/s (rated 6000 MT/s)`, as when XMP/EXPO isn't enabled).
- **Advanced Networking & Wireless**:
  - **Network Interfaces**: Outputs IPv4 & IPv6 addresses for active interfaces.
  - **Wi-Fi**: Details SSID, band frequency, channel, link rates (RX/TX on Linux, TX-only on macOS), adapter hardware, and Wi-Fi 7 Multi-Link Operation (MLO) bands.
  - **Bluetooth**: Reports adapter controller state, manufacturer/model, and connected device names/counts.
- **Battery Info**: Uses a custom, native implementation (no heavy dependencies) to extract capacity, vendor/model, time remaining, and battery health.
- **Software & Desktop Environment**:
  - **Shell Version**: Identifies the *running* shell (process tree, not `$SHELL`) and parses versions (`bash`, `zsh`, `fish`, `nu`, `pwsh`, `elvish`, `tcsh`).
  - **Desktop Environment & WM**: Detects GNOME, KDE, macOS Aqua, Windows, etc. WM is shown separately (e.g. Mutter under GNOME) and suppressed when identical to the DE.
  - **DNS**: Reports configured nameservers: from `/etc/resolv.conf` on Linux, from the default route's network service on macOS (so a split-tunnel VPN's resolver is not reported in its place), and from the network adapters on Windows.
  - **Terminal**: Identifies the terminal emulator from its own environment variables, then the process tree. Windows Terminal is also recognised through `WT_SESSION` (including inside WSL) and reported with its Store package version, e.g. `Windows Terminal 1.24.11911.0`.
  - **Terminal Size**: Reports terminal dimensions (columns × rows).
  - **UI Themes & Styling**: Concurrently resolves GTK2/3/4 or Qt global settings, icon packs, cursors, and system fonts (macOS/Windows/Linux-compatible).
  - **Package Counts**: Counts packages across many managers (`dpkg`, `rpm`, `pacman`, `flatpak`, `snap`, `homebrew`, `scoop`, `chocolatey`, `macports`).
  - **Media & Player**: The active media player, its playback state and the current track, through native APIs (WinRT on Windows, a direct D-Bus connection on Linux, the Objective-C runtime on macOS) rather than `playerctl` or `osascript`.
- **Logo Rendering Modes**:
  - **ASCII art**: High-quality color ASCII art matching your distro (adapted from Fastfetch).
  - **Graphical images**: Inline image rendering support via Kitty protocol, iTerm2, and Sixel.
  - **Unicode symbols fallback**: Graphical rendering using Chafa when full image protocols are unavailable.
  - **Auto-suppressed when piped**: Logo is never printed when stdout is not a terminal (e.g. `retch | bat` or `retch > file`).
  - **Interactive CLI tools**: Command flags like `--ascii-logo`, `--chafa-logo`, `--no-logo`, `--logo <NAME>` to force overrides, `--print-logos`, and `--list-distros`.
- **Flexible Theming**:
  - Built-in community color schemes (Catppuccin Latte/Frappé/Macchiato/Mocha, Solarized Light/Dark) or automatic dark/light preference detection.
  - Full hex code (`#RRGGBB`) color support for custom theme creation.
- **Configuration Engine**: Merge logic integrates CLI parameters and TOML configuration files seamlessly.

## Installation

### On Arch Linux (AUR)

You can install `retch` from the AUR using an AUR helper (e.g., `yay` or `paru`):

```sh
yay -S retch
```

> [!NOTE]
> **AUR Registration Outage**: New account registrations on the Arch User Repository are temporarily suspended by Arch Linux. While registrations are down, you can still build and install the package locally from a clone:
> ```sh
> just aur-local            # needs just, python3 and makepkg
> ```
> This renders the PKGBUILD for the last released tag and runs `makepkg -si` on it, which
> builds exactly the tarball the AUR package builds.

*(The AUR PKGBUILD lives in [packaging/aur](packaging/aur/PKGBUILD) as a **template**: its
`pkgver` and `sha256sums` are filled in from the tag at publish time, so it cannot be run
directly — hence the recipe above. See `scripts/render_packaging.py`.)*

### On macOS (Homebrew)

`retch` is available from a Homebrew tap:

```sh
brew trust l1a/retch    # Homebrew 6.0+ only; see the note below
brew tap l1a/retch
brew install retch
```

> [!IMPORTANT]
> **Homebrew 6.0 and later require third-party taps to be trusted before their formulae
> will load**, so `brew trust l1a/retch` must come first. Without it `brew tap` fails with
> a misleading message:
>
> ```
> Refusing to load formula l1a/retch/retch from untrusted tap l1a/retch.
> Error: Cannot tap l1a/retch: invalid syntax in tap!
> ```
>
> The syntax is not the problem — that is just how the refusal surfaces. On Homebrew 5.x
> and earlier there is no `brew trust` command; skip that line and tap directly.

> [!NOTE]
> The formula builds from source, so the first install compiles `retch` and needs Rust —
> Homebrew installs it as a build-time dependency automatically. There is deliberately no
> prebuilt bottle: a bottle has to be built, signed and uploaded per macOS version and
> architecture, which is a meaningful amount of release machinery for a small tool. It also
> installs the man page and shell completions for bash, zsh and fish.

*(The formula is maintained in [packaging/homebrew](packaging/homebrew/retch.rb) and pushed
to the tap by `just brew-publish` — the tap is never hand-edited.)*

### On Fedora (COPR)

`retch` is built for Fedora in a [COPR](https://copr.fedorainfracloud.org/coprs/kentobias/retch/)
repository:

```sh
sudo dnf copr enable kentobias/retch
sudo dnf install retch
```

> [!NOTE]
> COPR is Fedora's community build service, not an official Fedora repository — packages
> there are not reviewed by Fedora. Builds are provided for Fedora 43 and 44 on `x86_64`
> and `aarch64`.

*(The RPM spec file is available in [packaging/copr](packaging/copr/retch.spec)).*

### From crates.io

```sh
cargo install retch-cli
```

This installs the **binary only** — no man page and no shell completions. Generate
completions from the installed binary with `retch --completions <shell>` (see
[From source](#from-source) for where each shell looks), or use one of the `just` recipes
below, which install all three.

### With Nix

```sh
nix run github:l1a/retch
```

Or add it to your NixOS / Home Manager configuration using the provided Flake:

```nix
# flake.nix inputs
inputs.retch.url = "github:l1a/retch";

# Home Manager module
programs.retch.enable = true;
# Optionally configure retch (writes ~/.config/retch/config.toml):
programs.retch.settings = {
  theme = "catppuccin";
};
```

*(Nixpkgs package derivation expression is available in [packaging/nixpkgs](packaging/nixpkgs/package.nix)).*

### From source

Prefer the [`just`](https://github.com/casey/just) recipes: they install the **man page and
shell completions** as well as the binary, and keep all three at the same version. Besides
Rust they need `just` and Python 3.

```sh
git clone https://github.com/l1a/retch.git
cd retch
just install-tag "$(git describe --tags --abbrev=0)"   # the newest release
```

`just install-tag <version>` builds that release (`cargo install --git --tag`), then installs
completions generated by the binary it just installed and the man page read from the same
tag, so the three cannot disagree. It is a bash recipe, so on Windows run it from Git Bash.

To install **the current checkout** instead — unreleased changes included:

```sh
just install
```

Either recipe puts the binary in `~/.cargo/bin`, the man page in
`~/.local/share/man/man1`, and completions for bash, zsh, fish, elvish, nushell and
PowerShell in their per-user locations (honouring `XDG_DATA_HOME` / `XDG_CONFIG_HOME`).
zsh only reads completions from directories on its `fpath`; if
`~/.local/share/zsh/site-functions` is not on it, the recipe says so and prints the line to
add.

Without `just`, `cargo install --path .` works too, but installs the binary only — use
`retch --completions <shell>` for completions, and `docs/retch.1` is the man page.

## Usage

Basic usage:

```sh
retch
```

Output modes:

```sh
retch --short   # hardware snapshot: host, OS, kernel, CPU, GPU, memory, disk, network
retch           # standard: daily-use system overview
retch --long    # diagnostics: firmware, thermals, shell, network, battery, …
retch --full    # everything: theme, gamepad, weather, FUSE mounts, all sensors
```

Force the ASCII logo (even where graphical logos are supported):

```sh
retch --ascii-logo
```

Colour is used only when stdout is a terminal and `NO_COLOR` is unset, so piped output is plain.
Force it either way:

```sh
retch --color always | less -R
retch --color never
```

Override distribution logo:

```sh
retch --logo pop
```

List available logos:

```sh
retch --print-logos
```

List known distros:

```sh
retch --list-distros
```

Show help:

```sh
retch --help
```

### Running under `sudo`

`sudo retch` is not simply "retch with more fields" — it trades one set for another, because
`sudo`'s default `env_reset` clears most of the environment:

| | Field |
|---|---|
| **Root only** | `phys-mem` (reads the DMI tables, mode `0400 root`); the snapshot count in `btrfs` (`btrfs subvolume list -s`) |
| **User only** | `editor` (`$VISUAL`/`$EDITOR`), `desktop` and `wm` (`XDG_CURRENT_DESKTOP` and friends) |

Everything else is identical either way, so run retch normally unless you specifically want
the DIMM breakdown or btrfs snapshot counts.

## Shell Completions

Generate completion scripts for your shell:

```sh
# Bash
retch --completions bash > ~/.local/share/bash-completion/completions/retch

# Zsh
retch --completions zsh > ~/.local/share/zsh/site-functions/_retch

# Fish
retch --completions fish > ~/.config/fish/completions/retch.fish
```

Supported shells: `bash`, `elvish`, `fish`, `power-shell`, `zsh`, `nushell`.

## Documentation

Retch provides standard documentation and quick-reference guides:
- **Man Page**: Display the full user manual:
  ```sh
  man retch
  ```
- **TL;DR Page**: [`docs/retch.md`](docs/retch.md) holds a page in tldr-pages format. It is not yet in the upstream tldr-pages collection, so `tldr retch` will not find it until it is.

## Configuration

retch looks for a configuration file at `~/.config/retch/config.toml` (or `$XDG_CONFIG_HOME/retch/config.toml`).

### Setup Commands

- **Generate config template** (prints to stdout):
  ```sh
  retch --generate-config
  ```
- **Write config directly** to the default location:
  ```sh
  retch --write-config
  ```
- **Merge defaults** into an existing configuration file (adds comments for new keys):
  ```sh
  retch --merge-config
  ```

### Configuration Structure

Here is an example of the settings you can configure in `config.toml`:

```toml
# Theme to use. Defaults to "auto" (follows system dark/light preference).
# Other options: "neutral", "dark", "light", "custom", or community schemes:
# "catppuccin-latte", "catppuccin-frappe", "catppuccin-macchiato", "catppuccin-mocha",
# "solarized-dark", "solarized-light".
theme = "auto"

# Whether to show the distribution ASCII/graphical logo
show_logo = true

# Force ASCII-only logo output (even if graphical protocols are supported)
ascii_only = false

# Override the detected distribution logo (e.g. "ubuntu", "fedora", "pop", "macos", "windows")
logo = "pop"

# Custom theme colors (applied if theme = "custom" or as partial overrides)
# Colors can be specified using terminal names or standard hex values (#RRGGBB)
[custom_theme]
label_color = "bright_cyan"
value_color = "#cdd6f4"
accent_color = "bright_green"
title_color = "bright_yellow"
separator_color = "bright_black"

# Location for weather lookup (city name, ZIP code, or lat/lon coordinates).
# If unset, your location is auto-detected from your IP address.
# weather_location = "London"

# Temperature unit for weather: "fahrenheit" (default) or "celsius"
# weather_unit = "fahrenheit"

# Which system information fields to display (selection only — this list does not reorder output)
# Note: "phys-mem" requires root (sudo) on Linux to read DMI memory tables. On Windows, reads the SMBIOS table natively (no PowerShell).
# Note: "btrfs" snapshot counts require root on Linux; the count is omitted (not shown as 0) when it can't be read.
# Note: "editor", "desktop" and "wm" read environment variables, so they are absent under `sudo` (env_reset).
# Note: "phys-disk" on Windows uses native storage IOCTLs (no PowerShell, no admin).
# Note: "gamepad" on Windows enumerates PnP devices natively via SetupAPI (no PowerShell).
# Note: "weather" requires network access; shown in full mode only by default.
# Note: "domain-search" queries resolvectl; shown in full mode only by default.
# Note: "disk-io" and "net-io" are rates averaged over the run's own collection window
#       (Linux, Windows and macOS). They add no wall-clock in --long/--full; requesting one on its
#       own tops the window up to ~100 ms so the reading is a measurement, not sampling
#       noise. On Windows both read native counters - no PowerShell, no admin.
# Note: "vulkan", "opengl" and "opencl" work on Linux, Windows and macOS. All three are
#       full mode only, and each is simply absent when its loader is not installed - which
#       on macOS is the normal state for Vulkan, since it exists there only via MoltenVK.
#       OpenGL needs a context: Linux uses headless EGL, Windows uses WGL on a window
#       created hidden and never shown, macOS uses CGL and needs no window at all.
fields = [
    "os", "kernel", "host", "domain", "domain-search", "chassis", "init", "locale",
    "arch", "cpu", "cpu-freq", "cpu-cache", "cpu-usage", "gpu",
    "motherboard", "bios", "bootmgr", "tpm", "display", "brightness", "audio", "camera", "gamepad",
    "keyboard", "mouse",
    "memory", "phys-mem", "swap", "uptime", "procs", "load",
    "disk", "phys-disk", "disk-io", "btrfs", "zpool", "temp",
    "net", "net-io", "public-ip", "wifi", "dns", "bluetooth", "battery", "power-adapter",
    "shell", "editor", "terminal", "terminal-font", "terminal-size", "desktop", "wm", "login-manager",
    "player", "media",
    "vulkan", "opengl", "opencl",
    "wm-theme", "wallpaper", "terminal-theme", "theme", "icons", "cursor", "font", "users", "packages", "weather"
]
```

## Logos

### ASCII Logos

Some ASCII logos are adapted from [Fastfetch](https://github.com/fastfetch-cli/fastfetch) (MIT licensed).

### Graphic Logos

Graphic logos are converted from official or community SVG logos. These are **not** covered by the project's GPLv3 license and remain subject to the original trademarks and licenses of their respective projects.

See the full list of supported distros with:

```sh
retch --print-logos
```

## Workspace Architecture

retch is structured as a Cargo workspace with the following crates:

| Crate | Path | Description |
|---|---|---|
| `retch-cli` | `.` | CLI binary — display logic, configuration, logo rendering |
| `retch-sysinfo` | `crates/sysinfo` | System info library — all `detect_*` logic, `SystemInfo`, `CollectOptions`, GPU, and battery |

The `retch-sysinfo` crate can be used independently as a library for cross-platform system information gathering without any dependency on `clap` or the CLI.

## License

Copyright (C) 2025 Ken Tobias. Licensed under the GNU General Public License,
version 3 or later (`GPL-3.0-or-later`). The full text is in [LICENSE](LICENSE).

[NOTICE](NOTICE) carries the licence grant for this project together with the MIT
attribution for the ASCII logos adapted from Fastfetch.

## Contributing

Contributions are welcome! Feel free to open issues or pull requests.

If you are the copyright holder of any logo and would like different attribution or removal, please open an issue.