YAML Configuration Schema

Raffi uses a YAML configuration file to define launcher entries and settings. The default location is ~/.config/raffi/raffi.yaml.

Top-Level Structure

The configuration file consists of three main sections:

version: 1

general:
  # General settings and UI configuration

addons:
  # Addon configurations (currency, calculator, etc.)

# Entry definitions (each key becomes an entry)
launchers:
  entry_name:
    binary: command
    description: "Display name"
    # ... other entry fields

General Section

Persistent defaults for UI and behavior. All fields are optional and can be overridden by command-line flags.

general.ui_type string (default: fuzzel)

Default UI backend to use.

Valid values: fuzzel, native

general:
  ui_type: native

general.default_script_shell string (default: bash)

Default interpreter for script entries.

Used when an entry has a script field but no explicit binary field.

general:
  default_script_shell: /bin/zsh

general.no_icons boolean (default: false)

Disable icon loading globally.

general:
  no_icons: true

general.theme string (default: dark)

Color theme for native UI.

Valid values: dark, light

general:
  theme: light

general.max_history number (default: 10)

Maximum number of search query history entries to keep.

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

general:
  max_history: 20

general.font_size number (default: 20)

Base font size in pixels for native UI.

Other UI elements scale proportionally:

Input text: 1.2× base size (24px by default)
Item text: 1.0× base size (20px by default)
Subtitle text: 0.7× base size (14px by default)
Hint text: 0.6× base size (12px by default)
```
general:
  font_size: 16
```

**`general.font_family`** `string` (default: `system sans-serif`)

Font family name for native UI.

  ```yaml
  general:
    font_family: "Inter"

general.window_width number (default: 800)

Window width in pixels for native UI.

general:
  window_width: 900

general.window_height number (default: 600)

Window height in pixels for native UI.

general:
  window_height: 500

general.padding number (default: 20)

Outer window padding in pixels for native UI.

By default, scales automatically with font_size. Set explicitly to override.

general:
  padding: 30

general.fallbacks list of strings (default: [])

Addon entries shown at the bottom of the launcher list when typing a non-empty query. Useful for search-type addons (web searches, script filters).

Format: addons.<type>."<name>" where <type> is web_searches or script_filters.

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

general.theme_colors object

Custom color overrides for the native UI theme.

Each field accepts a hex color string: #RGB, #RRGGBB, or #RRGGBBAA. Only specified colors are overridden; others use the base theme defaults.

Available color keys:

bg_base - Main background color
bg_input - Input field background
accent - Accent color (selected items, borders)
accent_hover - Hover state for accented elements
text_main - Primary text color
text_muted - Secondary/muted text color
selection_bg - Selected item background

border - Border color

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"

## Entry Fields

Each key under `launchers` defines a launcher entry.

**`binary`** `string` (optional)

The executable command to run.

  If the binary is not found in `$PATH`, the entry is automatically hidden.

  ```yaml
  launchers:
    firefox:
      binary: firefox
      description: "Firefox Browser"

description string

Display name shown in the launcher.

If omitted, the entry key or binary name is used.

launchers:
  firefox:
    binary: firefox
    description: "Firefox Browser"

args array[string]

Command-line arguments to pass to the binary.

Supports tilde and environment variable expansion.

launchers:
  firefox:
    binary: firefox
    args: ["--marionette", "--private-window"]
    description: "Firefox Private"

icon string

Icon name resolved from system icon directories ($XDG_DATA_DIRS/icons, $XDG_DATA_DIRS/pixmaps). Prefers larger icons (48×48+) as Raffi renders at 48×48. Supports PNG and SVG formats.

launchers:
  firefox:
    binary: firefox
    icon: firefox
    description: "Firefox"

script string

Inline script content to execute.

When present, the binary field specifies the interpreter (defaults to bash or the value of --default-script-shell). The args field can provide arguments to the interpreter.

Script expansion (~/ and ${VAR}) is not performed on the script content itself.

launchers:
  hello_script:
    script: |
      echo "Hello, world!"
      date
    description: "Hello Script"

  python_script:
    binary: python3
    script: |
      import datetime
      print(f"Current time: {datetime.datetime.now()}")
    description: "Python Time"

disabled boolean (default: false)

Hide this entry from the launcher.

launchers:
  experimental_feature:
    binary: experimental
    description: "Experimental Feature"
    disabled: true

Conditional Display

Entries can be conditionally shown based on environment variables or file existence. Multiple conditions can be specified per entry — when present, they are AND-ed together (all must pass).

ifenveq array[string]

Show entry only if an environment variable equals a specific value.

Must be an array with exactly two elements: [VARIABLE_NAME, expected_value]

launchers:
  gnome_settings:
    binary: gnome-control-center
    description: "Settings"
    ifenveq: [DESKTOP_SESSION, GNOME]

ifenvset string

Show entry only if the specified environment variable is set (to any value).

launchers:
  wayland_tool:
    binary: some-wayland-tool
    description: "Wayland Tool"
    ifenvset: WAYLAND_DISPLAY

ifenvnotset string

Show entry only if the specified environment variable is not set.

launchers:
  x11_only:
    binary: some-x11-tool
    description: "X11 Tool"
    ifenvnotset: WAYLAND_DISPLAY

ifexist string

Show entry only if the specified binary exists in $PATH.

launchers:
  spotify:
    binary: spotify
    description: "Spotify"
    ifexist: spotify

Addons Section

The addons section configures built-in addons for the native UI. See Addon Configuration for detailed documentation.

addons:
  currency:
    enabled: true
  calculator:
    enabled: true
  file_browser:
    enabled: true
  script_filters: []
  web_searches: []
  text_snippets: []

Path Expansion

Most configuration fields (except script) support path and variable expansion:

~/ expands to $HOME
${VAR} expands to the value of environment variable VAR (empty string if unset)

launchers:
  myapp:
    binary: ${HOME}/bin/myapp
    args: ["${XDG_DATA_HOME}/files", "~/Documents"]
    icon: ~/icons/myapp.png
    ifexist: ~/bin/myapp

Complete Example

version: 1

general:
  ui_type: native
  theme: dark
  font_size: 20
  font_family: "Inter"
  window_width: 800
  window_height: 600
  max_history: 10
  default_script_shell: bash
  theme_colors:
    accent: "#cba6f7"

addons:
  currency:
    enabled: true
    trigger: "$"
    default_currency: USD
  calculator:
    enabled: true
  file_browser:
    enabled: true
    show_hidden: false
  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"

launchers:
  firefox:
    binary: firefox
    args: ["--marionette"]
    icon: firefox
    description: "Firefox Browser"

  thunder:
    binary: thunar
    args: ["~/Downloads/"]
    description: "File Manager"

  hello_script:
    script: |
      echo "Hello, world!"
      date
    description: "Hello Script"
    icon: "script"

  gnome_settings:
    binary: gnome-control-center
    description: "System Settings"
    icon: preferences-system
    ifenveq: [DESKTOP_SESSION, GNOME]

  suspend:
    binary: systemctl
    args: [suspend]
    description: "Suspend/Sleep"
    icon: system-suspend