Skip to content

Getting Started

Jump to bottom
Ken Tobias edited this page Sep 30, 2026 · 10 revisions

Getting Started

Prerequisites

  • None on the user side — retch ships as a single static-ish binary per platform.
  • To build from source: Rust toolchain (rustup.rs), plus just and Python 3 for the recipes that also install the man page and completions (see From source).

Install

From crates.io

cargo install retch-cli

The crate is published as retch-cli because the name retch was already taken on crates.io; the installed binary is still retch, and so is its config folder (see Configuration & Theming for the path on each platform).

This installs the binary only — no man page and no shell completions. Generate completions with retch --completions <shell>, or use the just recipes under From source, which install all three.

On Arch Linux (AUR)

yay -S retch

Installing from the AUR needs no AUR account. To build the same package from a clone instead, run just aur-local (needs just, python3 and makepkg). packaging/aur/PKGBUILD is a template whose version and checksum are filled in at publish time, so it cannot be handed to makepkg directly; the recipe renders it for the last released tag and builds that.

On macOS (Homebrew)

brew trust l1a/retch    # Homebrew 6.0+ only
brew tap l1a/retch
brew install retch

Homebrew 6.0 and later require third-party taps to be trusted before their formulae will load. Without brew trust first, brew tap fails with a message that blames the wrong thing:

Refusing to load formula l1a/retch/retch from untrusted tap l1a/retch.
Error: Cannot tap l1a/retch: invalid syntax in tap!

The syntax is fine — that is just how the refusal surfaces. On Homebrew 5.x and earlier there is no brew trust command, so skip that line and tap directly.

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

The formula lives in packaging/homebrew/retch.rb and is pushed to the tap by just brew-publish — the tap is never hand-edited. See Development Setup for the guard that keeps it from drifting.

On Fedora (COPR)

sudo dnf copr enable kentobias/retch
sudo dnf install retch

COPR is Fedora's community build service, not an official Fedora repository. Builds are provided for Fedora 43 and 44 on x86_64 and aarch64. The spec lives in packaging/copr/retch.spec; see Development Setup for how it is built and what compromises it makes.

With Nix

nix run github:l1a/retch

Or add it to a NixOS / Home Manager configuration via the provided flake:

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

# Home Manager module
programs.retch.enable = true;
programs.retch.settings = {
  theme = "catppuccin";
};

From source

Prefer the 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.

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:

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. Development Setup has the details.

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.

Quick Start

retch

Runs in standard mode — a daily-use system overview with the distro logo. Four output modes trade runtime for detail. On a Linux laptop --short and standard take a few milliseconds, --long ~0.2 s and --full ~0.4 s, the last two mostly waiting on CPU sampling and the network. See How It Works for the fields in each mode:

retch --short   # hardware snapshot: OS, CPU, GPU, Memory, Disk
retch           # standard: daily-use system overview
retch --long    # diagnostics: CPU usage, firmware, thermals, shell, network, battery
retch --full    # everything: theme, gamepad, weather, FUSE mounts, all sensors

Common Flags

retch --ascii-logo        # force text-only ASCII logo
retch --logo pop          # override the detected distro logo
retch --print-logos       # list all bundled logos
retch --list-distros      # list known distro identifiers
retch --help               # full flag reference

Shell Completions

# 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

Also supported: elvish, nushell, power-shell.

Documentation

man retch            # full user manual

Next Steps

Clone this wiki locally