.TH "RETCH" "1" "July 2026" "retch 0.4.1" "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\fB\-h, \-\-help\fP\fP
.RS
Show help information\.
.RE
\fB\fB\-V, \-\-version\fP\fP
.RS
Print version information\.
.RE
\fB\fB\-m, \-\-mode\fP \fIMODE\fP\fP
.RS
Select output mode (`\f[CR]short\fP`, `\f[CR]long\fP`, or `\f[CR]custom\fP`)\.
.RE
\fB\fB\-c, \-\-config\fP \fIFILE\fP\fP
.RS
Path to a custom configuration file instead of the default\.
.RE
\fB\fB\-\-ascii\-logo\fP\fP
.RS
Force ASCII logo output, disabling graphical and Chafa rendering\.
.RE
\fB\fB\-\-chafa\-logo\fP\fP
.RS
Force Chafa symbols output, disabling high\-res graphical protocols (Kitty, Sixel, iTerm2)\.
.RE
\fB\fB\-\-no\-logo\fP\fP
.RS
Disable the logo entirely\.
.RE
\fB\fB\-\-logo\fP \fILOGO\fP\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\fB\-\-theme\fP \fITHEME\fP\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\fB\-\-list\-themes\fP\fP
.RS
List all available built\-in themes\.
.RE
\fB\fB\-\-print\-theme\-template\fP\fP
.RS
Print an example custom theme template to stdout\.
.RE
\fB\fB\-\-print\-logos\fP\fP
.RS
Print all available logos\.
.RE
\fB\fB\-\-list\-distros\fP\fP
.RS
List known supported distributions\.
.RE
\fB\fB\-\-completions\fP \fISHELL\fP\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\fB\-\-generate\-config\fP\fP
.RS
Print a default configuration file to stdout\.
.RE
\fB\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\fB\-\-merge\-config\fP\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\fB\-\-fields\fP \fIFIELDS\fP\fP
.RS
Comma\-separated list of fields to display, overriding the config file's default list\.
.RE
\fB\fB\-s, \-\-short\fP\fP
.RS
Short output mode\. Equivalent to `\f[CR]\-\-mode short\fP`\. Shows: OS, Kernel, Host, CPU, GPU, Memory, Disk\.
.RE
\fB\fB\-l, \-\-long\fP\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\fB\-f, \-\-full\fP\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
.Bl
.IP \(bu 4
\fBtheme\fP: Theme name to use\. (default: `\f[CR]"auto"\fP`)\.
.El
.Bl
.IP \(bu 4
\fBshow_logo\fP: Boolean indicating whether to show the logo (default: `\f[CR]true\fP`)\.
.El
.Bl
.IP \(bu 4
\fBascii_only\fP: Boolean indicating whether to restrict logo to ASCII representation\.
.El
.Bl
.IP \(bu 4
\fBchafa\fP: Boolean indicating whether to force Chafa symbols output\.
.El
.Bl
.IP \(bu 4
\fBlogo\fP: Distro name/ID to force override logo detection\.
.El
.Bl
.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\.
.El
.Bl
.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\.
.El
.Bl
.IP \(bu 4
\fBfields\fP: Array of strings representing active fields and their display order\. Available fields are:
.RS
.Bl
.IP \(bu 4
`\f[CR]os\fP`: Operating system name\.
.El
.Bl
.IP \(bu 4
`\f[CR]kernel\fP`: Kernel version\.
.El
.Bl
.IP \(bu 4
`\f[CR]host\fP`: System host/product name\.
.El
.Bl
.IP \(bu 4
`\f[CR]arch\fP`: System architecture\.
.El
.Bl
.IP \(bu 4
`\f[CR]chassis\fP`: Chassis type (Laptop, Desktop, Mini PC, etc\.)\.
.El
.Bl
.IP \(bu 4
`\f[CR]init\fP`: PID 1 / init system (systemd, runit, launchd, etc\.)\.
.El
.Bl
.IP \(bu 4
`\f[CR]locale\fP`: System locale from `\f[CR]$LC_ALL\fP` / `\f[CR]$LANG\fP`\.
.El
.Bl
.IP \(bu 4
`\f[CR]cpu\fP`: CPU model name\.
.El
.Bl
.IP \(bu 4
`\f[CR]cpu\-freq\fP`: CPU current/max/min frequencies\.
.El
.Bl
.IP \(bu 4
`\f[CR]cpu\-cache\fP`: CPU L1/L2/L3 cache sizes\.
.El
.Bl
.IP \(bu 4
`\f[CR]cpu\-usage\fP`: Current CPU utilization percentage\.
.El
.Bl
.IP \(bu 4
`\f[CR]gpu\fP`: GPU model(s) and VRAM\.
.El
.Bl
.IP \(bu 4
`\f[CR]motherboard\fP`: Motherboard manufacturer and model\.
.El
.Bl
.IP \(bu 4
`\f[CR]bios\fP`: BIOS vendor and version\.
.El
.Bl
.IP \(bu 4
`\f[CR]bootmgr\fP`: Second\-stage bootloader (GRUB, systemd\-boot, etc\.)\.
.El
.Bl
.IP \(bu 4
`\f[CR]display\fP`: Connected monitor displays with refresh rates and resolution\.
.El
.Bl
.IP \(bu 4
`\f[CR]audio\fP`: Audio card controller and active sound servers (PipeWire, PulseAudio, ALSA, CoreAudio, Windows Audio)\.
.El
.Bl
.IP \(bu 4
`\f[CR]camera\fP`: Connected camera/webcam names\.
.El
.Bl
.IP \(bu 4
`\f[CR]gamepad\fP`: Connected gamepad/controller names\.
.El
.Bl
.IP \(bu 4
`\f[CR]memory\fP`: System RAM usage and capacity\.
.El
.Bl
.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, uses `\f[CR]Win32_PhysicalMemory\fP` via PowerShell\.
.El
.Bl
.IP \(bu 4
`\f[CR]swap\fP`: System SWAP usage and capacity\.
.El
.Bl
.IP \(bu 4
`\f[CR]uptime\fP`: System uptime\.
.El
.Bl
.IP \(bu 4
`\f[CR]procs\fP`: Active process count\.
.El
.Bl
.IP \(bu 4
`\f[CR]load\fP`: Average system load\.
.El
.Bl
.IP \(bu 4
`\f[CR]disk\fP`: Mounted disk capacity, usage, and mountpoint\.
.El
.Bl
.IP \(bu 4
`\f[CR]phys\-disk\fP`: Physical disk model, size, and type (NVMe SSD, SSD, HDD)\. On Windows, uses `\f[CR]Get\-PhysicalDisk\fP` via PowerShell\.
.El
.Bl
.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\.
.El
.Bl
.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\.
.El
.Bl
.IP \(bu 4
`\f[CR]temp\fP`: System temperature sensors\.
.El
.Bl
.IP \(bu 4
`\f[CR]net\fP`: Active network interfaces and local/public IP addresses\.
.El
.Bl
.IP \(bu 4
`\f[CR]public\-ip\fP`: Public IP address (queried over the network)\. Long mode and above\.
.El
.Bl
.IP \(bu 4
`\f[CR]wifi\fP`: Active Wi\-Fi SSID, band frequency, channel, and link rates\.
.El
.Bl
.IP \(bu 4
`\f[CR]dns\fP`: Configured DNS nameservers (from `\f[CR]/etc/resolv\.conf\fP` on Linux/macOS)\.
.El
.Bl
.IP \(bu 4
`\f[CR]domain\fP`: Configured DNS domain name (from `\f[CR]domain\fP` or first `\f[CR]search\fP` entry in `\f[CR]/etc/resolv\.conf\fP`)\. Long mode and above\.
.El
.Bl
.IP \(bu 4
`\f[CR]domain\-search\fP`: Per\-interface DNS search domain lists (from `\f[CR]resolvectl status\fP` or `\f[CR]/etc/resolv\.conf\fP` `\f[CR]search\fP`)\. Full mode only\.
.El
.Bl
.IP \(bu 4
`\f[CR]bluetooth\fP`: Bluetooth adapter details and connected device count/names\.
.El
.Bl
.IP \(bu 4
`\f[CR]battery\fP`: Battery capacity, vendor/model, time remaining, and health\.
.El
.Bl
.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)\.
.El
.Bl
.IP \(bu 4
`\f[CR]editor\fP`: Default editor from `\f[CR]$VISUAL\fP` / `\f[CR]$EDITOR\fP`\.
.El
.Bl
.IP \(bu 4
`\f[CR]terminal\fP`: Terminal emulator name and version\.
.El
.Bl
.IP \(bu 4
`\f[CR]terminal\-font\fP`: Terminal emulator active font\.
.El
.Bl
.IP \(bu 4
`\f[CR]terminal\-size\fP`: Terminal dimensions (columns x rows)\.
.El
.Bl
.IP \(bu 4
`\f[CR]desktop\fP`: Desktop environment name (e\.g\. GNOME, KDE Plasma, XFCE)\.
.El
.Bl
.IP \(bu 4
`\f[CR]wm\fP`: Window manager name (e\.g\. Mutter, KWin, Sway)\. Hidden when identical to Desktop\.
.El
.Bl
.IP \(bu 4
`\f[CR]theme\fP`: UI Theme settings\.
.El
.Bl
.IP \(bu 4
`\f[CR]icons\fP`: UI icon pack\.
.El
.Bl
.IP \(bu 4
`\f[CR]cursor\fP`: UI mouse cursor settings\.
.El
.Bl
.IP \(bu 4
`\f[CR]font\fP`: UI system font\.
.El
.Bl
.IP \(bu 4
`\f[CR]users\fP`: Current logged in users\.
.El
.Bl
.IP \(bu 4
`\f[CR]packages\fP`: Installed package counts (supporting dpkg, rpm, pacman, flatpak, snap, homebrew, scoop, chocolatey, etc\.)\.
.El
.Bl
.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)\.
.El
.RE
.El
.RE
.SH "THEMES"
.PP
retch supports multiple built\-in themes as well as custom color overrides\.
.PP
The following themes are available:
.RS
.Bl
.IP \(bu 4
\fBauto\fP (default): Automatically follows your system dark/light preference\.
.El
.Bl
.IP \(bu 4
\fBneutral\fP: A balanced neutral theme (cyan labels, white values)\.
.El
.Bl
.IP \(bu 4
\fBdark\fP and \fBlight\fP: Basic dark and light themes\.
.El
.Bl
.IP \(bu 4
Popular community themes: \fBcatppuccin\-latte\fP, \fBcatppuccin\-frappe\fP, \fBcatppuccin\-macchiato\fP, \fBcatppuccin\-mocha\fP, \fBsolarized\-light\fP, \fBsolarized\-dark\fP\.
.El
.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
.Bl
.IP \(bu 4
ASCII logos are adapted from Fastfetch\.
.El
.Bl
.IP \(bu 4
Graphical logos are rendered using Chafa when available, or via the Kitty, iTerm2, or Sixel inline image protocols\.
.El
.Bl
.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)\.
.El
.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 "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