Quick Start

You can run raffi before writing any config. With no config, typing searches your installed applications, open windows and system commands in one list. This page walks you through binding Raffi to a key, finding your way around, trying a few addons, and then setting it up the way you like.

Your first launch

New users see a welcome panel above the results. Search stays ready: start typing to find an app, choose Do quick math (2 + 2) or Browse your files (~/) to try a working example, or choose See everything Raffi can do to browse keywords. Examples fill the search box and show results; Enter then copies the answer or opens the selected file. Disabled addons do not appear as examples. Tab and Shift+Tab move through the welcome controls; Enter chooses one. Hide this hides the panel on future launches. You can reopen it through Getting started in Ctrl+/ help. Existing configurations and usage history keep the panel from appearing automatically.

Bind it to a key

Choose Open Raffi with a shortcut in Getting started for a snippet matching your compositor, with steps for where to paste it. Ctrl+Tab cycles the available variants, including both Hyprland configuration formats. Copy keeps Raffi open and reports whether copying succeeded. Add the snippet to the file shown; Raffi does not edit or reload your compositor configuration. Escape returns to Getting started.

Sway

Add to ~/.config/sway/config, then run swaymsg reload:

set $super Mod4
bindsym $super+Space exec raffi

Super+Space now opens Raffi.

Hyprland

Add to ~/.config/hypr/hyprland.conf:

$super = SUPER
bind = $super, R, exec, raffi

After Hyprland reloads its config, Super+R opens Raffi.

Other compositors

Bind a key to raffi and it runs what you pick itself. If your compositor should start the program instead, have Raffi print the command with -p and pass it on.

Find your way around

Press Ctrl+/, or type ? on its own, to see the keywords and keyboard shortcuts your config turns on. Typing narrows the list, and Escape closes it and gives you back what you had typed. Press Enter or Tab on a keyword to start using it.

You don’t need to learn the keywords first. The empty search box shows a different tip each time, such as clip for Clipboard history. Type a word like volume, password or lock and Raffi suggests the addon that handles it.

When a list is empty or unavailable

An empty search result offers Clear filter, which keeps you in the current addon or folder. Loading messages wait for the source; failed loads offer Retry with Ctrl+R. A missing program or unsupported integration offers Open setup help for that addon. Select the recovery control with Enter or click it.

While a list refreshes, the previous results remain usable. If the refresh fails, the footer reports the failure and Ctrl+R retries without losing your search. Password managers keep their existing unlock prompts; Escape cancels an unlock.

Switch views with Ctrl+Tab

Some lists have more than one view. Ctrl+Tab moves to the next one and Ctrl+Shift+Tab goes back, and the footer shows where you are. It works the same in every list that has views: clipboard history (all, images, URLs), the file browser (all, files, directories), Slack (home, unread, people), audio devices (all, outputs, inputs), the window switcher (windows, workspaces) and the main list when you set up main_view.

The keyboard shortcuts page lists every key.

Try a few addons

Type a sum and Raffi shows the answer. Enter copies it:

2 + 2 * 5
sqrt(144) + log(100)

Start with $ to convert money:

$100 to eur
$50 gbp to usd

Type / or ~/ to browse files. Tab completes a path, Backspace after a / goes up a folder, Ctrl+H shows dotfiles, and Ctrl+Y copies the path. The preview pane shows the folder contents, images, PDFs and source code.

The Features section of the sidebar covers the other addons, from the window switcher to password managers.

Make it yours

Choose Save your settings in Getting started to preview a small config and its destination. Create the file creates it only when no file exists; existing configs are preserved. Copy copies the example without writing a file. The starter enables installed apps and keeps the default search sources. Changes take effect the next time you launch Raffi.

If you started Raffi with -c, the preview uses that config path. Command-line overrides are not saved into the starter file.

Settings normally live in ~/.config/raffi/raffi.yaml. To create one manually, start with the folder:

mkdir -p ~/.config/raffi

This config picks a theme, chooses what the main list shows as you type, keeps installed apps listed, and adds two web searches:

raffi.yaml

general:
  theme: dark
  main_view: [launchers, windows, browser_tabs, system, clipboard]
addons:
  apps:
    enabled: true
  web_searches:
    - name: Google
      keyword: g
      url: "https://google.com/search?q={query}"
      icon: google
    - name: Wikipedia
      keyword: wiki
      url: "https://en.wikipedia.org/wiki/{query}"
      icon: wikipedia

Then g wayland protocol or wiki rust opens the search in your browser.

Note

Adding a config file keeps Raffi’s default main-list sources unless you set main_view. An explicit list replaces those defaults; use null or [] to show only apps and your custom entries.

Every addon can be turned off, or given another keyword, under its own name in addons. For example, to free up sys for something else:

raffi.yaml

addons:
  system:
    enabled: false

The general settings page covers fonts, window size and history, and themes covers colors.

Add your own entries

For commands Raffi doesn’t know about, such as an app opened with particular arguments or a script you run often, add entries of your own.

1. Create ~/.config/raffi/launchers.yaml. Each top-level key is one entry:

   launchers.yaml

   firefox_private:
     binary: firefox
     args: [--private-window]
     icon: firefox
     description: Firefox private window
   
   notes:
     binary: kitty
     args: [nvim, ~/notes/todo.md]
     icon: kitty
     description: Open my todo list

   Swap in programs you have. Raffi hides an entry whose program it can’t find in your PATH. Installed apps stay in the list next to your entries only while addons.apps.enabled is true, as in the config above.

2. Run raffi, pick an entry and press Enter. Add -p to print the command instead of running it, which is handy for checking your config.

Run scripts

An entry can carry a script and the program that runs it:

Bash

launchers.yaml

hello_script:
  script: |
    echo "Hello from Bash!"
    notify-send "Raffi" "Script finished"
  description: Hello Script
  icon: script

Python

launchers.yaml

check_disk:
  binary: python3
  script: |
    import shutil
    usage = shutil.disk_usage("/")
    print(f"Disk usage: {usage.used / usage.total * 100:.1f}%")
  description: Check Disk Usage
  icon: drive-harddisk

Node.js

launchers.yaml

node_example:
  binary: node
  script: |
    const os = require('os');
    console.log(`Hostname: ${os.hostname()}`);
  description: System Info (Node)
  icon: nodejs

Scripts without a binary run with Bash unless you change default_script_shell. See Scripts for more.

More ideas

Arguments

launchers.yaml

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

code_workspace:
  binary: code
  args: [~/projects/myapp]
  icon: vscode
  description: Open MyApp in VS Code

Entries that only show up when they make sense

launchers.yaml

gnome_tweaks:
  binary: gnome-tweaks
  description: GNOME Tweaks
  icon: gnome-tweak-tool
  ifenveq: [DESKTOP_SESSION, GNOME]

wayland_only_app:
  binary: my-wayland-app
  description: Wayland App
  icon: wayland
  ifenvset: WAYLAND_DISPLAY

docker_compose:
  binary: docker-compose
  description: Docker Compose
  icon: docker
  ifexist: docker-compose

Paths and environment variables

launchers.yaml

custom_script:
  binary: ${HOME}/bin/my-script
  args: ["${XDG_DATA_HOME}/files", "~/Documents"]
  icon: ~/icons/custom.png
  description: My Custom Script
  ifexist: ~/bin/my-script

Lock, suspend and power off

launchers.yaml

lock_screen:
  binary: swaylock
  args: [-f, -c, "000000"]
  icon: system-lock-screen
  description: Lock Screen

suspend:
  binary: systemctl
  args: [suspend]
  icon: system-suspend
  description: Suspend to RAM

The system commands addon gives you these under sys without writing them yourself.

Handy flags

Command	Effect
raffi -p	Print the picked command instead of running it
raffi -c ~/.config/raffi/work.yaml	Use another config file
raffi -i "clip "	Open with a search already typed
raffi -t light	Use the light theme
raffi -r	Refresh the icon cache
raffi -I	Hide icons

Tip

From here, recipes has setups to copy, the configuration overview covers every setting, themes changes the look, and the CLI reference lists every flag.