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):

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:

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 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:

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 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 repository:

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).

From crates.io

cargo install retch-cli

With Nix

nix run github:l1a/retch

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

# 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).

From source

git clone https://github.com/l1a/retch.git
cd retch
cargo install --path .

Usage

Basic usage:

retch

Output modes:

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):

retch --ascii-logo

Override distribution logo:

retch --logo pop

List available logos:

retch --print-logos

List known distros:

retch --list-distros

Show help:

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:

# 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:

  man retch

• TL;DR Page: 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):

  retch --generate-config

• Write config directly to the default location:

  retch --write-config

• Merge defaults into an existing configuration file (adds comments for new keys):

  retch --merge-config

Configuration Structure

Here is an example of the settings you can configure in config.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 (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:

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.

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.