Skip to content

Getting Started

Jump to bottom
Ken Tobias edited this page Jul 1, 2026 · 1 revision

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

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

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:

cd packaging/aur && makepkg -si

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

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

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-only        # 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
tldr retch            # common usage examples (requires a tldr client, e.g. tealdeer)

Next Steps

Clone this wiki locally