Skip to content

Getting Started

Jump to bottom
Ken Tobias edited this page Sep 21, 2026 · 7 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 and config directory are still retch / ~/.config/retch/.

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

Note

New account registrations on the Arch User Repository are temporarily suspended by Arch Linux. While registrations are down, you can still build and install locally from a clone:

just aur-local            # needs just, python3 and makepkg

packaging/aur/PKGBUILD is a template whose pkgver/sha256sums are filled in from the tag at publish time, so it cannot be handed to makepkg directly. The recipe renders it for the last released tag and builds that, which is the same tarball the AUR builds.

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 (see How It Works for the full field breakdown):

retch --short   # hardware snapshot: OS, CPU, GPU, Memory, Disk — <100ms
retch           # standard: daily-use system overview — ~200ms
retch --long    # diagnostics: firmware, thermals, shell, network, battery — ~500ms
retch --full    # everything: theme, gamepad, weather, FUSE mounts, all sensors — ~5s+

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