General Settings

Overview

The general section in your configuration file sets persistent defaults for Raffi’s appearance and behavior. Command-line flags override config values when a setting has a corresponding flag.

Configuration Options

All fields in the general section are optional.

ui_type string

By default Raffi opens its own window. Set it to fuzzel to show your entries in Fuzzel instead, a legacy option with fewer features.

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

theme string (default: dark)

Color theme. Valid options:

dark - Sleek Obsidian dark palette (default)
light - Rose Pine Dawn light palette
catppuccin / catppuccin-mocha - Catppuccin Mocha dark palette
catppuccin-latte - Catppuccin Latte light palette
tokyo-night / tokyonight - Tokyo Night dark palette
nord - Nord dark palette
gruvbox - Gruvbox dark palette
dracula - Dracula dark palette
rose-pine / rosepine - Rosé Pine dark palette
kanagawa - Kanagawa Wave dark palette

Equivalent to -t or --theme flag.

opacity number (default: 0.95)

Opacity of the window backgrounds, from 0.0 (see-through) to 1.0 (the theme as designed). Text and icons stay opaque. Set 1 for a solid window. Transparency needs the GPU renderer, which renderer: auto picks when opacity is below 1.

Equivalent to --opacity flag. See Transparency and Blur.

blur boolean (default: true)

Ask the compositor to blur what shows through the window. KDE Plasma honours it; Hyprland, niri and SwayFX use their own rules, see Transparency and Blur.

no_icons boolean (default: false)

Disables icon loading for faster startup.

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

renderer string (default: auto)

How Raffi draws its window. Valid options:

auto - gpu when opacity is below 1, otherwise cpu (default).
cpu - Software rendering. Skips GPU driver setup, so the window opens sooner. The window stays opaque on Wayland and opacity is ignored.
gpu - Vulkan/OpenGL rendering through wgpu. Needed for a translucent window.

An ICED_BACKEND environment variable (tiny-skia or wgpu) takes precedence. See Startup performance.

show_preview boolean (default: unset, automatic for addons)

Controls the Alfred-style right-hand preview and details pane.

When unset, addon results (text snippets, file browser, script filters, emoji, calculator, currency, web searches) show a preview, and apps and custom entries only show one when the entry itself sets show_preview: true. Set it to true to preview apps and entries too. Set it to false to start with the pane hidden everywhere, addons included; entries with their own show_preview: true still preview. Press Ctrl+P to toggle the pane at runtime; when nothing is shown, the first press turns previews on for everything.

close_on_action boolean (default: true)

Whether Raffi closes its window after executing an action.

Set close_on_action: false (or pass --keep-open / -o general.close_on_action=false) to keep Raffi open with your current search query and selection after launching an app, copying an inline result, or running an addon action. Individual entries and addons can override this with their own close_on_action: true | false setting (media, audio, bluetooth, and kill stay open unless you set close_on_action: true on the addon or write it out explicitly here). Actions that must type or paste into the previously focused window (insert, hypr_paste, password typing) or end the desktop session still close Raffi first.

launch string (default: auto)

How Raffi starts launchers and installed apps. Valid options:

auto - Inside Hyprland, niri or sway, ask the compositor to start the app (hyprctl, niri msg action spawn, swaymsg exec), so it runs as the compositor’s child, with the compositor’s environment and working directory. Outside them, or if the compositor refuses, Raffi starts it itself.
direct - Raffi always starts the app itself, and the app inherits Raffi’s environment and working directory.

Sway reads ; and , in exec as command separators and expands $ variables, so on sway Raffi starts command lines containing ;, ,, $, quotes, backslashes or line breaks itself.

With auto, the compositor reports success once it accepts the command, even when starting the program itself then fails, for example because the binary is not on the compositor’s PATH, so such failures stay silent. direct surfaces them instead.

-p / --print-only is not affected: it prints the command and starts nothing.

raise_running boolean (default: false)

When an app already has a window open, pressing Enter on its launcher focuses that window instead of starting a second copy. Ctrl+Enter still starts a new one. If the app has no open window, Raffi starts it as usual.

Raffi finds the window by its class (Hyprland, Xwayland) or app ID (niri, sway). Installed apps use the StartupWMClass and the name of their desktop file. A launcher with a plain binary and no args uses the binary’s file name. Launchers with args or a script need a window_class to raise. Launchers can opt in or out with raise; see Entries.

This needs Hyprland, niri or sway and Raffi’s own window. It does nothing with ui_type: fuzzel or -p.

show_tips boolean (default: true)

Shows a tip in the empty search box, such as Type to search... (tip: clip for Clipboard history), picked from your enabled addons and changed on each launch. Set it to false to keep the plain Type to search....

Preview Pane

preview object

Appearance of the right-hand preview pane. All fields are optional.

preview.font_size number (default: 0.8 × font_size, so 16 at the default 20)

Base text size in pixels. When unset it follows the UI font_size. The title (1.4×), headings (0.8×), hero values (2.2×) and emoji glyphs (5×) scale from it.

preview.font_family string

Font family for the pane: titles, metadata, and text such as Slack messages, snippets, clipboard entries and browser tab descriptions. Defaults to the UI font (font_family), or the system sans-serif font when that is unset.

preview.mono_font_family string

Font family for code-like blocks: file contents, entry commands and scripts, URLs, file lists, and Script Filter output. Defaults to the system monospace font.

preview.width_percent number (default: 50)

Share of the window width given to the pane, clamped to 10–80.

preview.colors object

Hex colour overrides (#RGB, #RRGGBB, or #RRGGBBAA). Unset colours come from the theme.

bg - pane background
bg_block - background of content blocks
text_main - title and body text
text_muted - subtitles, metadata keys
accent - headings, badges, hero values
border - pane and block borders

general:
  show_preview: true
  preview:
    font_size: 18
    font_family: "Inter"
    mono_font_family: "JetBrains Mono"
    width_percent: 55
    colors:
      accent: "#cba6f7"
      bg_block: "#1e1e2e"

Raffi showing a standard entry in the preview pane

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

Queries are saved when you run an action, in every mode, including clipboard, system commands, windows and developer tools. Debug logs still redact sensitive queries. The raw last query typed is also kept separately for --last-query.

sort_mode string (default: hybrid)

Controls how apps and entries, text snippets, password store entries and Bitwarden logins are ordered by past use. With no search query they are listed in this order; while typing, relevance comes first, then what you have used before ranks above what you have not, and past use breaks the remaining ties within a source. 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)

Apps and entries you have never used, or that tie, keep the order they have in your config file.

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. Snippet use is kept separately in ~/.cache/raffi/snippets.cache, and password entry use in ~/.cache/raffi/vault.cache.

clipboard_history string (default: auto)

Clipboard manager used by {clipboard:N} in text snippets. Valid options:

auto - Use the running one, preferring cliphist, then CopyQ, then clipman (default)
cliphist - Always use cliphist
copyq - Always use CopyQ
clipman - Always use clipman
none - Turn clipboard history off

{clipboard} reads the current clipboard with wl-paste, xclip or xsel and does not depend on this setting.

terminal_classes list of strings (default: [])

Extra window classes that the hypr_paste snippet action treats as terminals. Terminals get Ctrl+Shift+V instead of Ctrl+V. The list is added to the built-in one, which covers Alacritty, foot, kitty, Ghostty, WezTerm, GNOME Terminal, GNOME Console, Ptyxis, Konsole, Tilix, Terminator, Xfce Terminal, Rio and st. Classes are matched case-insensitively. Run hyprctl activewindow in your terminal to find its class.

general:
  terminal_classes:
    - my-terminal

Main list and fallbacks

What the main list shows as you type (main_view, main_view_chips) and the search rows added below it (fallbacks) have their own page: The Main List.

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)

Window width in pixels.

window_height number (default: 600)

Window height in pixels.

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.

Startup performance

To see where startup time goes, run raffi -d /tmp/raffi.log and look for the startup: lines (milliseconds since Raffi started).

Large or SVG icons are converted to small PNG copies in ~/.cache/raffi/icon-thumbnails on first use, so later launches skip decoding them. raffi --refresh-cache clears these copies along with the icon cache.

The translucent default (opacity: 0.95) uses the GPU renderer. For the fastest start, set opacity: 1 or renderer: cpu to use the software renderer with an opaque window.

If you use the GPU renderer, Vulkan layers installed by other programs (Steam, for example) are loaded on every launch. Setting VK_LOADER_LAYERS_DISABLE=all in Raffi’s environment skips them.

Example Configurations

Light Theme

general:
  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"

Command-Line Override

Dedicated flags exist for common settings, and any setting in raffi.yaml or launchers.yaml can be overridden from the command line with -o KEY=VALUE (--option KEY=VALUE).

# Override theme
raffi --theme light

# Override background opacity
raffi --opacity 0.7

# Keep the window open after actions
raffi --keep-open

# Override any config setting via -o / --option
raffi -o general.window_width=1000 -o addons.emoji.close_on_action=false