Skip to content

Configuration

Jump to bottom
Sam edited this page Feb 24, 2025 · 16 revisions

Generating the Config File

CrabFetch will generate a default config file if you run crabfetch -g
This will place a config file in one of three places;

  • $XDG_CONFIG_HOME/CrabFetch/config.toml
  • Or, if $XDG_CONFIG_HOME isn't set $HOME/.config/CrabFetch/config.toml
  • Or, if you specify the --config argument it will place it in the specified path.

CrabFetch will also use these paths to search for your configs. If it can't find any configuration, it will simply use it's defaults.

Note

If you want to swap between multiple configuration files, check out Config Presets.

Configuration Basics

The config file is written in TOML. It's recommended you use some form of code editor just to make life easier, but any regular ol' text editor will do the trick as well.

Some key information;

  • Each piece of Information CrabFetch can find and display is referred to as a "module". Each module can also be customized independently.
  • If you need a separate copy of the config file but don't want to re-generate over your old one, you can find it here (and use button with the download icon on the top right if your new to GitHub).

Base Configuration

The top "modules" array defines what modules to display in what order. You can either refer to the comment above that array to see what you can add, or refer to a module's specific wiki page in order to see how to use it.

Underneath that you'll find several "global" configuration options, that let you control how CrabFetch displays and formats certain things e.g separator characters and inline modules. For the most part the config file will keep you right with comments (those lines that start with #).

Inline Modules

Inline modules are "modules" that don't have a specified configuration area and instead are configured when you add it into the modules array in your config.toml.
They are done by adding a : followed by the option. For example, to add an underline of 10 spaces; underline:10

Using Colors

Colors in regular texts like separators or module formats (talked about later) can be used by using a placeholders like {color-green}, replacing it with your color of choice. You can select from the following colors;

  • Black {color-black}
  • Red {color-red}
  • Green {color-green}
  • Yellow {color-yellow}
  • Blue {color-blue}
  • Magenta {color-magenta}
  • Cyan {color-cyan}
  • White {color-white}
  • BrightBlack {color-brightblack}
  • BrightRed {color-brightred}
  • BrightGreen {color-brightgreen}
  • BrightYellow {color-brightyellow}
  • BrightBlue {color-brightblue}
  • BrightMagenta {color-brightmagenta}
  • BrightCyan {color-brightcyan}
  • BrightWhite {color-brightwhite}
  • Clear {color-clear}

Percentage Color Configuration

You can modify the "percentage_color_thresholds" array to set colors for percent values in output. Each entry should be a string with the format "{percentage}:{color}". For example, the default config;

percentage_color_thresholds = [
    "75:brightgreen",
    "85:brightyellow",
    "90:brightred"
]

ASCII Configuration

By default the ASCII will be an art of your distribution's logo, as well as your distributions color. If your distro's ASCII doesn't work, make a issue and I'll add it in.
If you want to use your own custom ASCII, you can make a file at {CrabFetch Config Folder}/ascii and place your own ASCII art in there. This will override the ASCII and drop in whatever you place in.

Configuring the ASCII let's you select the side, margin, as well as how CrabFetch colors it. When coloring it, you have four options / "modes";

  • raw which leaves the ASCII alone. This is useful for people who have their own custom ASCII, and have ANSI codes to color it instead.
  • os which colors the ASCII in your distributions color.
  • solid which colors the ASCII in a solid color, specified in the solid_color option.
  • band which gives a flag-like coloring, specified in band_colors which go from top to bottom.

Unlike other color placeholders, if you wish to use a "bright" color, you must separate the "bright" and color with a underscore; e.g bright_blue

Configuring Modules

Each module has it's own configuration area underneath these previous options. You'll see them marked in square brackets (a TOML table), e.g;

[cpu]
title = "CPU"
format = "{name} {arch} ({core_count}c {thread_count}t) @ {max_clock_ghz} GHz"

As for actually configuring them; each module has a "title", "separator" and a "format" used to display it.

image

"title" and "format" are unique to the module, meanwhile "separator" will use the default separator you specify at the global options at the top unless you choose to override it for that module (more on this in a sec).
The title/format can also have their own "placeholders", texts that get replaced with values.

If your looking at a module's default config and see that "format" is missing, it means it's a really simple module that just has a single placeholder being displayed. You can still override it if you wish.
You can also place color placeholders in format, e.g the default hostname format;

format = "{color-brightmagenta}{username}{color-white}@{color-brightmagenta}{hostname}"

Some modules may have their own required variables too. If this is the case they will be present and explained in the config comments.

I also pointed out you can override the separator, but you can also override most other global options granted they're relevant to that module. If you want a full list of settings for each module, check that module's wiki page.

Modules

Clone this wiki locally