Skip to content

Configuration and Theming

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

Configuration & Theming

retch is highly configurable, allowing you to select which system fields are queried and how they are colored.

Configuration File

The default configuration file is loaded from:

  • Linux/macOS: ~/.config/retch/config.toml (or respects $XDG_CONFIG_HOME/retch/config.toml)
  • Windows: %USERPROFILE%\.config\retch\config.toml

Configuration Commands

  • Generate config template (prints to stdout): 
    retch --generate-config
  • Write config directly to the default path: 
    retch --write-config
  • Merge defaults into an existing configuration file (adds comments for any missing keys): 
    retch --merge-config

Configuration Options

Below are the primary top-level settings in config.toml:

theme

Sets the active color scheme.

  • Value: String (e.g. "auto", "neutral", "dark", "light", "custom", "catppuccin-mocha")
  • Default: "auto" (follows system dark/light preference)

show_logo

Toggles the distribution logo display.

  • Value: Boolean (true or false)
  • Default: true

ascii_only

Forces text-only ASCII logo display.

  • Value: Boolean (true or false)
  • Default: false

logo

Overrides the auto-detected distribution logo.

  • Value: String (e.g., "pop", "fedora", "ubuntu", "macos", "windows")
  • Default: Detected distro name

fields

An ordered list of details to retrieve and display. Leaving this empty or omitting it shows all.

  • Value: Array of strings. Available fields:
    • os, kernel, host, arch
    • cpu, cpu-freq, gpu, motherboard, bios, display
    • audio, memory, swap, uptime, procs, load, disk, temp
    • net, wifi, bluetooth, battery
    • shell, terminal, desktop
    • theme, icons, cursor, font
    • users, packages

Theming

Built-in Themes

  • auto: Checks light/dark preference on Windows registry, macOS Aqua, or Linux dbus/GSettings.
  • neutral: Balanced clean output (cyan labels).
  • dark / light: Standard high-contrast modes.
  • catppuccin-latte / frappe / macchiato / mocha: Soft pastel color palettes.
  • solarized-dark / solarized-light: Popular low-contrast solarized color schemes.

Custom Themes

You can customize colors by setting theme = "custom" and defining the [custom_theme] block:

[custom_theme]
label_color = "bright_cyan"
value_color = "#cdd6f4"
accent_color = "bright_green"
title_color = "bright_yellow"
separator_color = "bright_black"

Color values can be standard terminal color names (e.g., red, bright_cyan) or hex triplet codes (#RRGGBB).

Clone this wiki locally