General Settings

Overview

The general section in your configuration file sets persistent defaults for Raffi’s appearance and behavior. These settings are equivalent to command-line flags but are applied automatically on every launch.

Note

Command-line flags always override settings from the configuration file.

Configuration Options

All fields in the general section are optional.

ui_type string (default: fuzzel)

UI backend selection. Valid options:

• fuzzel - Uses external Fuzzel launcher (default)
• native - Uses built-in iced-based GUI

Equivalent to -u or --ui-type flag.

theme string (default: dark)

Color theme for the native interface. Valid options:

• dark - Dracula-inspired palette (default)
• light - Rose Pine Dawn palette

Equivalent to -t or --theme flag. Only applies to native UI.

no_icons boolean (default: false)

Disables icon loading for faster startup.

Equivalent to -I or --no-icons flag.

default_script_shell string (default: bash)

Default interpreter for inline scripts. Common values:

• bash (default)
• /bin/zsh
• python3

Equivalent to --default-script-shell flag.

max_history number (default: 10)

Maximum number of search query history entries.

Set to 0 to disable history. Navigate history with Alt+P (previous) and Alt+N (next) in native mode.

sort_mode string (default: hybrid)

Controls how launcher entries are sorted when no search query is active. Valid options:

• frequency - Sort by launch count (most frequently used first)
• recency - Sort by last-used time (most recently used first)
• hybrid - Combined score: 40% frequency + 60% recency (default)

The MRU cache at ~/.cache/raffi/mru.cache stores both launch counts and timestamps. Existing caches using the old format are migrated automatically on next use.

Fallbacks

fallbacks list of strings (default: [])

Addon entries that appear at the bottom of the launcher list when you type a non-empty query. This is useful for search-type addons (web searches, script filters) so they are always accessible without remembering their keywords.

Each entry is a dot-separated path: addons.<type>."<name>" where <type> is web_searches or script_filters, and <name> matches the addon’s name field.

Behavior:

• Only shown when the search query is non-empty
• Not shown when already in an addon mode (script filter, web search, file browser, etc.)
• Web search fallbacks open the URL with the current query and exit
• Script filter fallbacks switch the input to that filter’s keyword mode

general:
  fallbacks:
    - addons.web_searches."Google"
    - addons.web_searches."DuckDuckGo"
    - addons.script_filters."Search Google"

Tip

Fallbacks work best with search-type addons. The referenced addon must be defined in your addons section.

Font and Typography

font_size number (default: 20)

Base font size in pixels. Other UI elements scale proportionally:

• Input text: 1.2× base size (24px by default)
• Item descriptions: 1.0× base size (20px by default)
• Subtitles: 0.7× base size (14px by default)
• Hints: 0.6× base size (12px by default)

font_family string

Font family name (e.g., "Inter", "Fira Sans", "Roboto").

When omitted, the system default sans-serif font is used.

Window Dimensions

window_width number (default: 800)

Launcher window width in pixels (native mode only).

window_height number (default: 600)

Launcher window height in pixels (native mode only).

padding number (default: 20)

Outer window padding in pixels.

When not set, padding scales automatically with font_size.

Theme Colors

Customize individual theme colors under the theme_colors section. Each field accepts hex color strings in the format #RGB, #RRGGBB, or #RRGGBBAA.

Only specified colors are overridden; the rest come from the base theme selected via theme.

theme_colors.bg_base string

Base background color.

theme_colors.bg_input string

Input field background color.

theme_colors.accent string

Primary accent color (used for highlights and selected items).

theme_colors.accent_hover string

Accent color for hover states.

theme_colors.text_main string

Primary text color.

theme_colors.text_muted string

Muted/secondary text color.

theme_colors.selection_bg string

Background color for selected items.

theme_colors.border string

Border color.

Example Configurations

Native UI with Light Theme

general:
  ui_type: native
  theme: light
  font_size: 18
  font_family: "Inter"
  window_width: 900
  window_height: 500

Custom Theme Colors (Catppuccin Mocha)

general:
  theme: dark
  theme_colors:
    bg_base: "#1e1e2e"
    bg_input: "#313244"
    accent: "#cba6f7"
    accent_hover: "#89b4fa"
    text_main: "#cdd6f4"
    text_muted: "#6c7086"
    selection_bg: "#45475a"
    border: "#585b70"

Minimal Fuzzel Configuration

general:
  ui_type: fuzzel
  no_icons: true
  default_script_shell: /bin/zsh

Command-Line Override

All general settings can be overridden with command-line flags:

# Override UI type
raffi --ui-type native

# Override theme
raffi --theme light

# Disable icons
raffi --no-icons

# Set custom script shell
raffi --default-script-shell /bin/zsh