YAML Configuration Schema

Raffi reads settings and addons from ~/.config/raffi/raffi.yaml, and your own entries from ~/.config/raffi/launchers.yaml.

Top-Level Structure

raffi.yaml holds the settings:

version: 1

general:
  # General settings and UI configuration

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

launchers.yaml holds the entries, one top-level key per entry:

entry_name:
  binary: command
  description: "Display name"
  # ... other entry fields

raffi.yaml may also contain the entries under a launchers: key. In that case launchers.yaml is ignored, so pick one place for them. launchers.yaml is used when raffi.yaml is missing or has no launchers: section.

General Section

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

general.ui_type string

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

general:
  ui_type: fuzzel

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.show_preview boolean (default: unset)

Unset previews addon results only; true also previews apps and custom entries; false hides the pane everywhere except entries that set their own show_preview: true. Toggle at runtime with Ctrl+P.

general:
  show_preview: true

general.close_on_action boolean (default: true)

Whether Raffi closes after running an entry or addon action. Individual entries and addons can override this with their own close_on_action field.

general:
  close_on_action: false

general.show_tips boolean (default: true)

Show a keyword tip, picked from your enabled addons, in the empty search box.

general:
  show_tips: false

general.vim_mode boolean (default: false)

Start with modal vim keybindings in normal mode. Press i, a or / to focus the search field, j/k to move, g g/G for the first or last result and q to quit. Ctrl+Alt+V toggles it at runtime, and --vim-mode enables it from the command line.

general:
  vim_mode: true

general.preview object

Appearance of the preview pane: font_size (default 16), font_family, mono_font_family, width_percent (default 50, 10–80) and colors (bg, bg_block, text_main, text_muted, accent, border).

general:
  preview:
    font_size: 18
    width_percent: 55
    colors:
      accent: "#cba6f7"

general.theme string (default: dark)

Color theme.

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

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.

general:
  max_history: 20

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

  ```yaml
  general:
    font_family: "Inter"

general.window_width number (default: 800)

Window width in pixels.

general:
  window_width: 900

general.window_height number (default: 600)

Window height in pixels.

general:
  window_height: 500

general.padding number (default: 20)

Outer window padding in pixels.

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

general:
  padding: 30

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

Addon rows shown at the bottom of the main 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.main_view object (default: unset)

Sources mixed into the main list when typing without an addon trigger. An object with entries (the sources to show, in order) and exclude (sources to remove after resolving). When set, apps and entries only appear if launchers or all is listed. Use entries: [all] to include every enabled supported source, including all named snippet sources and script filters. Sources before all keep priority; duplicates are skipped. See The Main List.

Entries: all, launchers, browser_tabs, bookmarks, browser_history, windows, system, media, audio, bluetooth, pass, text_snippets.<name>, script_filters.<name>.

general:
  main_view:
    entries:
      - launchers
      - browser_tabs
      - text_snippets."Emails"
    exclude:
      - bluetooth

general.theme_colors object

Custom color overrides for the 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 top-level key in `launchers.yaml` (or each key under `launchers` in `raffi.yaml`) defines a custom entry.

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

The executable command to run.

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

  ```yaml title="launchers.yaml"
  firefox:
    binary: firefox
    description: "Firefox Browser"

description string

Display name shown in the list.

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

firefox:
  binary: firefox
  description: "Firefox Browser"

args array[string]

Command-line arguments to pass to the binary.

Supports tilde and environment variable expansion.

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

env map of strings

Environment variables to set for the binary or script, on top of Raffi’s own environment.

Values support tilde and environment variable expansion. Not allowed with alias.

firefox:
  binary: firefox
  description: "Firefox"
  env:
    MOZ_ENABLE_WAYLAND: "1"

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.

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.

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

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

show_preview boolean (default: false)

Show the right-hand preview pane for this entry, regardless of general.show_preview.

deploy:
  script: |
    kubectl apply -f deploy.yaml
  description: "Deploy"
  show_preview: true

close_on_action boolean (default: general.close_on_action, else true)

Whether Raffi closes after launching this entry, overriding general.close_on_action.

 volume_up:
  binary: pactl
  args: ["set-sink-volume", "@DEFAULT_SINK@", "+5%"]
  description: "Volume Up"
  close_on_action: false

alias string

Text typed into the search box when the entry is picked, such as an addon keyword followed by its query. Nothing runs until you choose a result. Cannot be combined with binary, script or args. See Entries for details.

keyword string (requires alias)

Word that stands for the alias while typing: linoux torvalds searches like mp linus/linux torvalds while the box keeps showing what you typed. Case-sensitive, needs a trailing space, no spaces inside.

linoux:
  description: "Linus Pull Requests"
  alias: "mp linus/linux"
  keyword: linoux

Conditional Display

Entries can be conditionally shown based on environment variables or file existence. An entry can have several conditions, and all of them 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]

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

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.

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

ifexist string

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

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

Addons Section

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

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

Validation

Raffi generates JSON Schemas for both files and keeps copies named raffi-schema.json and launchers-schema.json next to your config file. The copies are rewritten whenever they no longer match the running version of Raffi.

To explicitly write or refresh both schemas beside a config file, run:

raffi --generate-schemas --configfile /path/to/raffi.yaml

Point your editor at them by adding this line at the top of each file (supported by any editor using yaml-language-server):

# yaml-language-server: $schema=raffi-schema.json

# yaml-language-server: $schema=launchers-schema.json

Unknown keys (a typo such as binnary:) and wrong value types are then flagged while you edit.

Raffi also validates the config every time it loads it. Problems are printed to stderr as warnings and Raffi keeps running, ignoring unknown keys as before:

raffi: config warning: /home/user/.config/raffi/launchers.yaml:12: /firefox: Additional properties are not allowed ('binnary' was unexpected)

To check a config explicitly, for example in a script or after editing, run raffi --check-config. It checks raffi.yaml and launchers.yaml, prints all problems and exits with a non-zero status if any were found.

The startup warnings and --check-config need the config-validation Cargo feature, which is enabled by default. Minimal --no-default-features builds skip them, though the schema file is still written for your editor.

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)

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

Complete Example

version: 1

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

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