Quick Start

This guide will help you configure and launch your first application with Raffi.

Step 1: Create Your Configuration

1. Create the config directory

   Raffi looks for its configuration at ~/.config/raffi/raffi.yaml. Create the directory:

   mkdir -p ~/.config/raffi

2. Create a basic configuration file

   Create ~/.config/raffi/raffi.yaml with a simple entry:

   version: 1
   launchers:
     firefox:
       binary: firefox
       icon: firefox
       description: Firefox Web Browser
   
     terminal:
       binary: kitty
       icon: kitty
       description: Kitty Terminal
   
     file_manager:
       binary: nautilus
       icon: folder
       description: File Manager

3. Test your configuration

   Run Raffi in print-only mode to verify the configuration:

   raffi -p

   This will display your configured entries without executing them.

Note

Entries are only shown if the binary exists in your PATH. Replace the binary names with applications you have installed.

Step 2: Choose Your Interface

Raffi supports two interface modes:

Fuzzel Mode (Default)

Fuzzel mode uses the external Fuzzel launcher for a minimal, Wayland-native experience.

Install Fuzzel

First, ensure Fuzzel is installed:

Arch Linux

    sudo pacman -S fuzzel

Ubuntu/Debian

    sudo apt install fuzzel

Build from source

    git clone https://codeberg.org/dnkl/fuzzel.git
    cd fuzzel
    meson build
    ninja -C build
    sudo ninja -C build install

Launch with Fuzzel

raffi

Or explicitly specify Fuzzel mode:

raffi -u fuzzel

Configure Fuzzel Appearance

Customize Fuzzel’s look in ~/.config/fuzzel/fuzzel.ini:

dpi-aware=yes
font=RobotoMonoNerdFont-Thin:size=16
terminal=kitty
width=50
layer=overlay
exit-on-keyboard-focus-loss=no
inner-pad=15

[colors]
background=282a36ff
text=f8f8f2ff
match=8be9fdff
selection=44475add
border=bd93f9ff

Native Mode

Native mode uses Raffi’s built-in iced-based GUI with additional features like calculator, file browser, and more.

Launch Native Interface

raffi -u native

Choose a Theme

# Dark theme (default, Dracula-inspired)
raffi -u native -t dark

# Light theme (Rose Pine Dawn)
raffi -u native -t light

Set as Default

To always use native mode, add this to your config:

general:
  ui_type: native
  theme: dark
  font_size: 20
  window_width: 800
  window_height: 600

Step 3: Add Script Support

Raffi can execute inline scripts with any interpreter:

Bash Script

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

Python Script

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

Node.js Script

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

Step 4: Window Manager Integration

Integrate Raffi with your Wayland compositor:

Sway

Add to ~/.config/sway/config:

set $menu raffi -p
set $super Mod4
bindsym $super+Space exec $menu | xargs swaymsg exec --

Reload Sway config:

swaymsg reload

Now press Super+Space to launch Raffi!

Hyprland

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

$super = SUPER
bind = $super, R, exec, (val=$(raffi -pI); echo $val | grep -q . && hyprctl dispatch exec "$val")

Reload Hyprland config or restart Hyprland, then press Super+R to launch Raffi.

Other Compositors

For other Wayland compositors, bind a key to execute:

raffi -p | xargs swaymsg exec --

Or for direct execution:

raffi

Step 5: Explore Native Mode Features

Note

These features are only available when using the native interface (-u native).

Calculator

Just start typing a mathematical expression:

2 + 2 * 5
sqrt(144) + log(100)
sin(90) * 50

Press Enter to copy the result to clipboard.

Currency Converter

Type $ followed by an amount and currency:

$100 to eur
$50 gbp to usd
$10eur to jpy

Configure currency converter

addons:
  currency:
    enabled: true
    trigger: "$"
    default_currency: USD
    currencies: ["USD", "EUR", "GBP", "JPY", "CAD"]

File Browser

Navigate your filesystem by typing:

• / - Browse root directory
• ~ - Browse home directory
• /home/user/Documents - Browse specific path

Keyboard shortcuts:

• Enter: Open file/directory
• Alt+Enter: Copy path to clipboard
• Tab: Autocomplete
• Ctrl+H: Toggle hidden files

Web Searches

Add web searches to your config:

addons:
  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"

    - name: "GitHub"
      keyword: "gh"
      url: "https://github.com/search?q={query}"
      icon: "github"

    - name: "Wikipedia"
      keyword: "wiki"
      url: "https://en.wikipedia.org/wiki/{query}"
      icon: "wikipedia"

Then type:

g wayland protocol
gh user/repo
wiki rust programming

Common Use Cases

Launch applications with custom arguments

launchers:
  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

Conditional entries (show only when available)

launchers:
  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

Path expansion and environment variables

launchers:
  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

System actions

launchers:
  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

  poweroff:
    binary: systemctl
    args: [poweroff]
    icon: system-shutdown
    description: Power Off

Useful Commands

Print command without executing

raffi -p

Use custom config file

raffi -c ~/.config/raffi/work.yaml

Refresh icon cache

raffi -r

Disable icons (faster startup)

raffi -I

Native mode with initial query

raffi -u native -i "firefox"

Set default script interpreter

raffi --default-script-shell /bin/zsh

Next Steps

Configuration Overview

Explore all configuration options and advanced features

Script Filters

Extend Raffi with dynamic external commands

Theme Customization

Customize the native interface colors and appearance

CLI Options

Browse all command-line flags and options