retch-cli 0.11.2

.TH "RETCH" "1" "September 2026" "retch 0.11.2" "System Information Fetcher"

.SH "NAME"
.PP
retch \- a fast, feature\-rich system information fetcher

.SH "SYNOPSIS"
.PP
\fBretch\fP [\fIOPTIONS\fP]

.SH "DESCRIPTION"
.PP
\fBretch\fP is a fast system information tool written in Rust\. It displays detailed information about your system including OS, CPU, memory, audio, disks, network, Wi\-Fi, Bluetooth, and more, with support for high\-quality ASCII and graphical logos\.

.SH "OPTIONS"
\fB\-h, \-\-help\fP
.RS
Show help information\.
.RE
\fB\-V, \-\-version\fP
.RS
Print version information\.
.RE
\fB\-m, \-\-mode\fP \fIMODE\fP
.RS
Select output mode (`\f[CR]short\fP`, `\f[CR]long\fP`, or `\f[CR]custom\fP`)\.
.RE
\fB\-c, \-\-config\fP \fIFILE\fP
.RS
Path to a custom configuration file instead of the default\.
.RE
\fB\-\-ascii\-logo\fP
.RS
Force ASCII logo output, disabling graphical and Chafa rendering\.
.RE
\fB\-\-chafa\-logo\fP
.RS
Force Chafa symbols output, disabling high\-res graphical protocols (Kitty, Sixel, iTerm2)\.
.RE
\fB\-\-no\-logo\fP
.RS
Disable the logo entirely\.
.RE
\fB\-\-logo\fP \fILOGO\fP
.RS
Force a specific distribution logo by name/ID (e\.g\. `\f[CR]pop\fP`, `\f[CR]manjaro\fP`, `\f[CR]endeavouros\fP`, `\f[CR]opensuse\fP`, `\f[CR]ubuntu\fP`, `\f[CR]fedora\fP`, `\f[CR]macos\fP`, `\f[CR]windows\fP`)\.
.RE
\fB\-\-theme\fP \fITHEME\fP
.RS
Use a specific theme (e\.g\. `\f[CR]default\fP`, `\f[CR]dark\fP`, `\f[CR]light\fP`, or community themes)\.
.RE
\fB\-\-list\-themes\fP
.RS
List all available built\-in themes\.
.RE
\fB\-\-print\-theme\-template\fP
.RS
Print an example custom theme template to stdout\.
.RE
\fB\-\-print\-logos\fP
.RS
Print all available logos\.
.RE
\fB\-\-list\-distros\fP
.RS
List known supported distributions\.
.RE
\fB\-\-completions\fP \fISHELL\fP
.RS
Generate shell completion scripts for the specified shell\. Supported shells are: `\f[CR]bash\fP`, `\f[CR]elvish\fP`, `\f[CR]fish\fP`, `\f[CR]power\-shell\fP`, `\f[CR]zsh\fP`, `\f[CR]nushell\fP`\.
.RE
\fB\-\-generate\-config\fP
.RS
Print a default configuration file to stdout\.
.RE
\fB\-\-write\-config\fP [\fIPATH\fP]\fP
.RS
Write the default configuration to a file (uses `\f[CR]~/\.config/retch/config\.toml\fP` if no path is given)\.
.RE
\fB\-\-merge\-config\fP
.RS
Merge default configuration settings (as comments) into an existing config file at the default path (or custom path if `\f[CR]\-\-config\fP` is supplied)\.
.RE
\fB\-\-fields\fP \fIFIELDS\fP
.RS
Comma\-separated list of fields to display, overriding the config file's default list\.
.RE
\fB\-s, \-\-short\fP
.RS
Short output mode\. Equivalent to `\f[CR]\-\-mode short\fP`\. Shows: OS, Kernel, Host, CPU, GPU, Memory, Disk\.
.RE
\fB\-l, \-\-long\fP
.RS
Long output mode\. Shows diagnostics fields \-\- firmware, thermals (consolidated: one reading per physical unit), shell, desktop, network, Bluetooth, battery, packages, and more\. Does not include cosmetic or slow\-running fields (use `\f[CR]\-\-full\fP` for those)\.
.RE
\fB\-f, \-\-full\fP
.RS
Full output mode\. Shows everything in `\f[CR]\-\-long\fP` plus slow and cosmetic fields: UI theme, icons, cursor, weather (requires network), and FUSE mounts\. Expect multi\-second runtimes\.
.RE

.SH "CONFIGURATION"
.PP
retch reads its configuration from:
.RS
.PP
.nf
$XDG_CONFIG_HOME/retch/config\.toml
.fi
.RE
.PP
or
.RS
.PP
.nf
~/\.config/retch/config\.toml
.fi
.RE
.PP
You can generate a starting configuration with:
.RS
.PP
.nf
retch \-\-generate\-config > ~/\.config/retch/config\.toml
.fi
.RE

.SS "Available Configuration Keys"
.RS
.IP \(bu 4
\fBtheme\fP: Theme name to use\. (default: `\f[CR]"auto"\fP`)\.
.IP \(bu 4
\fBshow_logo\fP: Boolean indicating whether to show the logo (default: `\f[CR]true\fP`)\.
.IP \(bu 4
\fBascii_only\fP: Boolean indicating whether to restrict logo to ASCII representation\.
.IP \(bu 4
\fBchafa\fP: Boolean indicating whether to force Chafa symbols output\.
.IP \(bu 4
\fBlogo\fP: Distro name/ID to force override logo detection\.
.IP \(bu 4
\fBweather_location\fP: Location for weather lookup\. Accepts a city name (`\f[CR]"London"\fP`), US ZIP code (`\f[CR]"10001"\fP`), or lat/lon coordinates (`\f[CR]"48\.8566,2\.3522"\fP`)\. If unset, your location is auto\-detected from your outbound IP via ipinfo\.io\.
.IP \(bu 4
\fBweather_unit\fP: Temperature unit for the `\f[CR]weather\fP` field\. Accepts `\f[CR]"fahrenheit"\fP` (default) or `\f[CR]"celsius"\fP`\. Can also be set via `\f[CR]\-\-weather\-unit\fP` on the CLI\.
.IP \(bu 4
\fBfields\fP: Array of strings representing active fields and their display order\. Available fields are:
.RS
.IP \(bu 4
`\f[CR]os\fP`: Operating system name\.
.IP \(bu 4
`\f[CR]kernel\fP`: Kernel version\.
.IP \(bu 4
`\f[CR]host\fP`: System host/product name\.
.IP \(bu 4
`\f[CR]arch\fP`: System architecture\.
.IP \(bu 4
`\f[CR]chassis\fP`: Chassis type (Laptop, Desktop, Mini PC, etc\.)\.
.IP \(bu 4
`\f[CR]init\fP`: PID 1 / init system (systemd, runit, launchd, etc\.)\.
.IP \(bu 4
`\f[CR]locale\fP`: System locale from `\f[CR]$LC_ALL\fP` / `\f[CR]$LANG\fP`\.
.IP \(bu 4
`\f[CR]cpu\fP`: CPU model name\.
.IP \(bu 4
`\f[CR]cpu\-freq\fP`: CPU current/max/min frequencies\.
.IP \(bu 4
`\f[CR]cpu\-cache\fP`: CPU L1/L2/L3 cache sizes\.
.IP \(bu 4
`\f[CR]cpu\-usage\fP`: Current CPU utilization percentage\.
.IP \(bu 4
`\f[CR]gpu\fP`: GPU model(s) and VRAM\.
.IP \(bu 4
`\f[CR]motherboard\fP`: Motherboard manufacturer and model\.
.IP \(bu 4
`\f[CR]bios\fP`: BIOS vendor and version\.
.IP \(bu 4
`\f[CR]bootmgr\fP`: Second\-stage bootloader (GRUB, systemd\-boot, etc\.)\.
.IP \(bu 4
`\f[CR]tpm\fP`: Trusted Platform Module specification version (`\f[CR]2\.0\fP`, `\f[CR]1\.2\fP`), read from `\f[CR]/sys/class/tpm\fP`\. Omitted when no TPM is present or its version cannot be read\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]display\fP`: Connected monitor displays with refresh rates and resolution\.
.IP \(bu 4
`\f[CR]brightness\fP`: Current backlight brightness as a percentage (from `\f[CR]/sys/class/backlight\fP`)\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]audio\fP`: Audio card controller and active sound servers (PipeWire, PulseAudio, ALSA, CoreAudio, Windows Audio)\.
.IP \(bu 4
`\f[CR]camera\fP`: Connected camera/webcam names\.
.IP \(bu 4
`\f[CR]gamepad\fP`: Connected gamepad/controller names\.
.IP \(bu 4
`\f[CR]keyboard\fP`: Connected keyboard names, from `\f[CR]/proc/bus/input/devices\fP`\. A device is listed only when its class is unambiguous: peripherals paired through a Logitech Unifying/Bolt receiver are presented by the kernel with a merged capability set that is byte\-identical for a keyboard and a mouse, so those are resolved via the HID++ driver's battery model name and, failing that, listed in neither `\f[CR]keyboard\fP` nor `\f[CR]mouse\fP` rather than guessed into the wrong one\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]mouse\fP`: Connected pointing devices \-\- mice, touchpads, and tablets \-\- from `\f[CR]/proc/bus/input/devices\fP`, de\-duplicated by name\. Subject to the same ambiguity rule as `\f[CR]keyboard\fP`\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]memory\fP`: System RAM usage and capacity\.
.IP \(bu 4
`\f[CR]phys\-mem\fP`: Physical RAM slot details \-\- type (DDR5, LPDDR5, etc\.), speed, and per\-slot capacity\. On Linux, shows the module's actual running speed alongside its rated speed when they differ (e\.g\. `\f[CR]4800 MT/s (rated 6000 MT/s)\fP`, as when XMP/EXPO isn't enabled), parsed from dmidecode's "Configured Memory Speed"\. Requires root (`\f[CR]sudo\fP`) to read DMI memory tables via `\f[CR]dmidecode\fP`\. On Windows, reads the SMBIOS table natively via `\f[CR]GetSystemFirmwareTable\fP`; no PowerShell and no elevation\.
.IP \(bu 4
`\f[CR]swap\fP`: System SWAP usage and capacity\.
.IP \(bu 4
`\f[CR]uptime\fP`: System uptime\.
.IP \(bu 4
`\f[CR]procs\fP`: Active process count\.
.IP \(bu 4
`\f[CR]load\fP`: Average system load\.
.IP \(bu 4
`\f[CR]disk\fP`: Mounted disk capacity, usage, and mountpoint\.
.IP \(bu 4
`\f[CR]phys\-disk\fP`: Physical disk model, size, and type (NVMe SSD, SSD, HDD)\. On Windows, uses native storage IOCTLs; no PowerShell and no administrator rights\.
.IP \(bu 4
`\f[CR]disk\-io\fP`: Per\-disk read/write throughput in bytes per second, for physical whole disks only (partitions are excluded \-\- their traffic is already counted against the parent device)\. On Linux, read from `\f[CR]/proc/diskstats\fP` and named after the kernel device (`\f[CR]nvme0n1\fP`)\. On Windows, read via the `\f[CR]IOCTL_DISK_PERFORMANCE\fP` storage IOCTL and named after the drive index (`\f[CR]PhysicalDrive0\fP`); no PowerShell and no administrator rights\. Long mode and above\. See \fBI/O RATES\fP below for how the rate is measured\.
.IP \(bu 4
`\f[CR]btrfs\fP`: Mounted btrfs filesystem label, subvolume, and space allocation (`\f[CR]btrfs filesystem show\fP`/`\f[CR]usage\fP`); one entry per mount point, so a filesystem mounted at both `\f[CR]/\fP` and `\f[CR]/home\fP` via separate subvolumes shows two entries\. Snapshot count is shown when it can be read (`\f[CR]btrfs subvolume list \-s\fP`, requires root) and omitted otherwise\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]zpool\fP`: Imported ZFS pool name, allocation, and health (`\f[CR]zpool list\fP`)\. Linux and macOS with ZFS installed; empty if `\f[CR]zpool\fP` is not present\. Long mode and above\.
.IP \(bu 4
`\f[CR]temp\fP`: System temperature sensors\.
.IP \(bu 4
`\f[CR]net\fP`: Active network interfaces and local/public IP addresses\.
.IP \(bu 4
`\f[CR]net\-io\fP`: Per\-interface RX/TX throughput in bytes per second, read from `\f[CR]/sys/class/net/<iface>/statistics\fP` on Linux and from `\f[CR]GetIfTable2\fP` on Windows (the same counters `\f[CR]Get\-NetAdapterStatistics\fP` reports, without the subprocess)\. Reports the default\-route interface when it is known, otherwise every non\-loopback interface that moved data during the window\. On Windows, the NDIS lightweight\-filter instances bound to an adapter \-\- which report that adapter's counters a second time under names like `\f[CR]Wi\-Fi\-QoS Packet Scheduler\-0000\fP` \-\- are excluded, so each adapter is counted once\. Long mode and above\. See \fBI/O RATES\fP below\.
.IP \(bu 4
`\f[CR]public\-ip\fP`: Public IP address (queried over the network)\. Long mode and above\.
.IP \(bu 4
`\f[CR]wifi\fP`: Active Wi\-Fi SSID, band frequency, channel, and link rates\.
.IP \(bu 4
`\f[CR]dns\fP`: Configured DNS nameservers\. Read from `\f[CR]/etc/resolv\.conf\fP` on Linux and macOS, and from `\f[CR]GetAdaptersAddresses\fP` on Windows \-\- natively, with no PowerShell and no elevation\. IPv4 nameservers only on Windows\.
.IP \(bu 4
`\f[CR]domain\fP`: Configured DNS domain name\. On Linux, the domain of the interface carrying the default route (via `\f[CR]resolvectl\fP`), so a split\-tunnel VPN's domain is not reported unless the VPN is the default route; falls back to the `\f[CR]domain\fP` or first `\f[CR]search\fP` entry in `\f[CR]/etc/resolv\.conf\fP`\. Long mode and above\.
.IP \(bu 4
`\f[CR]domain\-search\fP`: DNS search domain lists, one entry per scope, formatted as `\f[CR]scope: a, b\fP`\. The scope is the interface name when per\-interface data is available (from `\f[CR]resolvectl status\fP`), or `\f[CR]global\fP` when falling back to `\f[CR]/etc/resolv\.conf\fP`'s `\f[CR]search\fP` list, which carries no interface attribution\. Full mode only\.
.IP \(bu 4
`\f[CR]bluetooth\fP`: Bluetooth adapter details and connected device count/names\.
.IP \(bu 4
`\f[CR]battery\fP`: Battery capacity, vendor/model, time remaining, and health\.
.IP \(bu 4
`\f[CR]power\-adapter\fP`: AC power adapter name and connection state (from `\f[CR]/sys/class/power_supply\fP` `\f[CR]Mains\fP` supply)\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]shell\fP`: Currently running shell name and version (e\.g\. bash, zsh, fish, nu)\. Detected from the process tree; falls back to `\f[CR]$SHELL\fP` (login shell)\.
.IP \(bu 4
`\f[CR]editor\fP`: Default editor from `\f[CR]$VISUAL\fP` / `\f[CR]$EDITOR\fP`\.
.IP \(bu 4
`\f[CR]terminal\fP`: Terminal emulator name and version\.
.IP \(bu 4
`\f[CR]terminal\-font\fP`: Terminal emulator active font\.
.IP \(bu 4
`\f[CR]terminal\-size\fP`: Terminal dimensions (columns x rows)\.
.IP \(bu 4
`\f[CR]desktop\fP`: Desktop environment name (e\.g\. GNOME, KDE Plasma, XFCE)\.
.IP \(bu 4
`\f[CR]wm\fP`: Window manager name (e\.g\. Mutter, KWin, Sway)\. Hidden when identical to Desktop\.
.IP \(bu 4
`\f[CR]login\-manager\fP`: Active display/login manager (GDM, SDDM, LightDM, greetd, \.\.\.), resolved from the `\f[CR]display\-manager\.service\fP` systemd unit\. Linux only\. Long mode and above\.
.IP \(bu 4
`\f[CR]player\fP`: Active media player name and playback status (e\.g\. Spotify (Playing), VLC media player)\. Long mode and above\.
.IP \(bu 4
`\f[CR]media\fP`: Currently playing song/track title and artist\. Long mode and above\.
.IP \(bu 4
`\f[CR]wm\-theme\fP`: Window manager frame / decoration theme (e\.g\. Breeze, Adwaita, Yaru, Greybird, Aqua, Aero)\. Full mode only by default\.
.IP \(bu 4
`\f[CR]wallpaper\fP`: Current desktop background wallpaper file path or URI\. Full mode only by default\.
.IP \(bu 4
`\f[CR]terminal\-theme\fP`: Terminal emulator color scheme or palette name (Kitty, Alacritty, WezTerm, Foot, Windows Terminal, Konsole, Ptyxis, iTerm2, Apple Terminal)\. Full mode only by default\.
.IP \(bu 4
`\f[CR]theme\fP`: UI Theme settings\.
.IP \(bu 4
`\f[CR]icons\fP`: UI icon pack\.
.IP \(bu 4
`\f[CR]cursor\fP`: UI mouse cursor settings\.
.IP \(bu 4
`\f[CR]font\fP`: UI system font\.
.IP \(bu 4
`\f[CR]users\fP`: Current logged in users\.
.IP \(bu 4
`\f[CR]packages\fP`: Installed package counts (supporting dpkg, rpm, pacman, flatpak, snap, homebrew, scoop, chocolatey, etc\.)\.
.IP \(bu 4
`\f[CR]weather\fP`: Current weather via Open\-Meteo (city, condition, temperature)\. Requires network access\. Full mode only by default (~4s network timeout)\.
.RE
.RE

.SH "THEMES"
.PP
retch supports multiple built\-in themes as well as custom color overrides\.
.PP
The following themes are available:
.RS
.IP \(bu 4
\fBauto\fP (default): Automatically follows your system dark/light preference\.
.IP \(bu 4
\fBneutral\fP: A balanced neutral theme (cyan labels, white values)\.
.IP \(bu 4
\fBdark\fP and \fBlight\fP: Basic dark and light themes\.
.IP \(bu 4
Popular community themes: \fBcatppuccin\-latte\fP, \fBcatppuccin\-frappe\fP, \fBcatppuccin\-macchiato\fP, \fBcatppuccin\-mocha\fP, \fBsolarized\-light\fP, \fBsolarized\-dark\fP\.
.RE
.PP
You can also define custom colors using the `\f[CR][custom_theme]\fP` section in your configuration file\.
.PP
Colors can be specified using names (e\.g\. `\f[CR]"bright_cyan"\fP`) or hex values (e\.g\. `\f[CR]"#89b4fa"\fP`)\.
.PP
Example:
.RS
.PP
.nf
[custom_theme]
label_color = "bright_cyan"
value_color = "#cdd6f4"
accent_color = "bright_green"
.fi
.RE

.SH "LOGOS"
.PP
retch supports both ASCII and graphical logos\.
.RS
.IP \(bu 4
ASCII logos are adapted from Fastfetch\.
.IP \(bu 4
Graphical logos are rendered using Chafa when available, or via the Kitty, iTerm2, or Sixel inline image protocols\.
.IP \(bu 4
Logos are automatically suppressed when stdout is not a terminal (e\.g\. when piped to a pager or redirected to a file)\.
.RE
.PP
Use `\f[CR]\-\-ascii\-only\fP` to force text\-only output\. Use `\f[CR]\-\-no\-logo\fP` to suppress the logo unconditionally\.

.SH "I/O RATES"
.PP
The `\f[CR]disk\-io\fP` and `\f[CR]net\-io\fP` fields report throughput, and the kernel exposes only
cumulative counters \-\- so a rate requires two samples and an interval\. \fBretch\fP takes the
first sample before its concurrent probes run and the second after they finish, which
makes the run's own collection window the sampling window and costs no additional time\.
.PP
Two consequences follow, and both are deliberate:
.RS
.IP \(bu 4
The window varies with the output mode \-\- roughly 0\.4 seconds in `\f[CR]\-\-long\fP`, several
seconds in `\f[CR]\-\-full\fP`\. The figure is therefore an \fBaverage over the run\fP, not an
instantaneous rate\. A fixed window would be more comparable between runs, but only by
sleeping on every invocation\.
.IP \(bu 4
Requesting one of these fields on its own (`\f[CR]retch \-\-fields disk\-io\fP`) leaves almost no
window at all, so it is topped up to approximately 100 milliseconds\. This is the only
situation in which either field adds measurable wall\-clock time\.
.RE
.PP
A device that appears part\-way through the run \-\- a VPN interface coming up \-\- is omitted
rather than reported, since its lifetime counter is not a delta\. Counter resets are
clamped to zero for the same reason\.
.PP
Both fields are available on Linux and Windows\. They are absent on other platforms rather
than reported as zero, so a missing line never reads as an idle device\.

.SH "PRIVILEGES"
.PP
Running \fBretch\fP under \fBsudo\fP(8) exchanges one set of fields for another rather than
simply adding to them, because sudo's default `\f[CR]env_reset\fP` clears most of the environment\.
.PP
Available only as root:
.RS
.IP \(bu 4
`\f[CR]phys\-mem\fP` \-\- the per\-DIMM breakdown reads the DMI tables (`\f[CR]/sys/firmware/dmi/tables/DMI\fP`, mode 0400)\.
.IP \(bu 4
`\f[CR]btrfs\fP` \-\- the snapshot count requires `\f[CR]btrfs subvolume list \-s\fP`\. It is omitted, never shown as zero, when it cannot be read\.
.RE
.PP
Available only as the logged\-in user:
.RS
.IP \(bu 4
`\f[CR]editor\fP` \-\- read from `\f[CR]$VISUAL\fP` / `\f[CR]$EDITOR\fP`\.
.IP \(bu 4
`\f[CR]desktop\fP`, `\f[CR]wm\fP` \-\- read from `\f[CR]XDG_CURRENT_DESKTOP\fP`, `\f[CR]XDG_SESSION_DESKTOP\fP` and `\f[CR]GDMSESSION\fP`\.
.RE
.PP
All other fields are identical either way\.

.SH "EXIT STATUS"
.PP
\fBretch\fP exits with status 0 on success, and non\-zero on error\.

.SH "SEE ALSO"
.PP
\fBfastfetch\fP(1), \fBneofetch\fP(1)

.SH "AUTHORS"
.PP
Maintained by the retch developers\.
See the project repository for more information:
.RS
.PP
.nf
https://github\.com/l1a/retch
.fi
.RE