Configuration Overview

Raffi runs without any config. When you want to change how it looks, what the main list shows or which addons are on, you write it in a YAML file.

Configuration Files

Raffi reads two files from $HOME/.config/raffi/, and both are optional:

$HOME/.config/raffi/raffi.yaml       # settings and addons
$HOME/.config/raffi/launchers.yaml   # your own entries

raffi.yaml holds almost everything: the theme, fonts, what the main list shows, which addons are on and their keywords, web searches, snippets and script filters. launchers.yaml only holds commands and scripts you add yourself, and many people never need it.

You can override the location of raffi.yaml with the -c or --configfile flag. Raffi then looks for launchers.yaml in the same directory:

raffi --configfile /path/to/custom/raffi.yaml

Raffi writes raffi-schema.json and launchers-schema.json next to your config so editors can validate both files as you type, and warns on stderr about unknown or invalid keys when it starts. Run raffi --check-config to validate them on demand. See Validation for details.

raffi.yaml

raffi.yaml has two main sections:

general: theme, fonts, window size, what the main list shows
addons: turn addons on or off, change their keywords, and add web searches, snippets and script filters

Minimal Example

general:
  theme: dark

A Fuller Example

version: 1

general:
  theme: dark
  font_size: 20
  main_view: [launchers, windows, browser_tabs, system, clipboard]

addons:
  apps:
    enabled: true
  system:
    trigger: power
  web_searches:
    - name: Google
      keyword: g
      url: "https://google.com/search?q={query}"
  script_filters:
    - name: Timezones
      keyword: tz
      command: batz
      args: ["-j"]

apps keeps installed applications in the list once you have entries of your own; without any entries they are listed anyway.

launchers.yaml

launchers.yaml is a mapping of names to custom entries:

firefox_private:
  binary: firefox
  args: [--private-window]
  icon: firefox
  description: Firefox private window

backup:
  script: |
    rsync -a ~/Documents /mnt/backup/
    notify-send "Raffi" "Backup done"
  icon: drive-harddisk
  description: Back up my documents

Raffi reads launchers.yaml when raffi.yaml is missing or has no launchers: section of its own. If raffi.yaml does define entries, those win and launchers.yaml is ignored with a warning.

Entries Inside raffi.yaml

A single file still works. Put the entries under a launchers: key in raffi.yaml, indented one level. The entry snippets in these docs are written for launchers.yaml; to use one in raffi.yaml, nest it under launchers::

version: 1

launchers:
  firefox_private:
    binary: firefox
    args: [--private-window]
    icon: firefox

Configuration Sections

General Settings

Theme, fonts, window size and what the main list shows

Addons

Turn addons on or off, change keywords, add web searches and snippets

Custom Entries

Your own commands, with arguments, icons and descriptions

Scripts

Inline scripts with bash, python, or custom interpreters

Conditions

Show an entry only when a program or variable is there

Icons

Icon caching, discovery, and path configuration

Path Expansion

Most configuration fields support path expansion:

~/ expands to your home directory
${VAR} expands to environment variable values
Unset variables expand to empty strings

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