Raffi Application Launcher

Raffi is an application launcher designed to sit on top of Fuzzel, or, if preferred, operate using its own built‑in interface. It allows commands and scripts to be defined in a YAML configuration file, with support for icons, arguments, conditional visibility, and script execution through configurable interpreters.

Documentation

Primary documentation lives on the docs site:

• https://chmouel.github.io/raffi/

Useful entry points:

• Introduction: https://chmouel.github.io/raffi/
• Installation: https://chmouel.github.io/raffi/installation/
• Quick start: https://chmouel.github.io/raffi/quickstart/
• Configuration overview: https://chmouel.github.io/raffi/configuration/overview/
• Configuration reference: https://chmouel.github.io/raffi/reference/yaml-schema/
• CLI options: https://chmouel.github.io/raffi/reference/cli-options/
• UI modes: https://chmouel.github.io/raffi/features/ui-modes/
• Themes: https://chmouel.github.io/raffi/features/themes/
• Script filters: https://chmouel.github.io/raffi/features/script-filters/
• Text snippets: https://chmouel.github.io/raffi/features/text-snippets/
• Web search: https://chmouel.github.io/raffi/features/web-search/
• Calculator: https://chmouel.github.io/raffi/features/calculator/
• Currency converter: https://chmouel.github.io/raffi/features/currency-converter/
• File browser: https://chmouel.github.io/raffi/features/file-browser/
• Addon configuration: https://chmouel.github.io/raffi/reference/addon-configuration/
• Window manager integration (Sway): https://chmouel.github.io/raffi/integration/sway/
• Window manager integration (Hyprland): https://chmouel.github.io/raffi/integration/hyprland/

Screenshot

See more screenshots below

Installation

Prebuilt binaries are available from the GitHub releases page. Download the archive or package suitable for your platform. If you intend to use the default interface, Fuzzel must also be installed.

On Arch Linux, Raffi can be installed from the AUR using a helper such as:

yay -S raffi-bin

On NixOS or using Nix (unstable channel):

nix-shell -p raffi

With LinuxBrew or Homebrew:

brew tap chmouel/raffi https://github.com/chmouel/raffi
brew install raffi

From crates.io:

cargo install raffi

To build from source:

git clone https://github.com/chmouel/raffi.git
cd raffi
cargo build --release

If you only require Fuzzel integration and want a significantly smaller binary, build without the native UI:

cargo build --release --no-default-features

This reduces the binary from roughly 15 MB to around 1.1 MB by removing the iced GUI dependency.

Usage

Running raffi launches configured entries through the selected interface. If your config does not define any valid launchers yet, Raffi falls back to auto-detected desktop applications from your system's .desktop files.

See the full CLI reference: https://chmouel.github.io/raffi/reference/cli-options/

Window Manager Integration

Sway

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

Hyprland

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

See also: Sway integration · Hyprland integration · Fuzzel integration

User Interfaces

Raffi supports two interface modes:

• Fuzzel — uses the external Fuzzel launcher, integrates naturally with Wayland environments.
• Native — built-in iced-based GUI with fuzzy search, keyboard navigation, and theme support.

The native interface includes built-in addons: calculator, currency converter, file browser, emoji/Nerd Fonts picker, script filters, web searches, and text snippets.

See: UI modes · Themes · Calculator · Currency converter · File browser · Script filters · Web search · Text snippets

Configuration

Configuration is stored in $HOME/.config/raffi/raffi.yaml. Basic example:

version: 1

launchers:
  firefox:
    binary: firefox
    args: [--marionette]
    icon: firefox
    description: Firefox browser with marionette enabled

If you do not create a config yet, Raffi can still show installed desktop applications by scanning XDG application entries.

For full configuration reference see the docs:

• Configuration overview
• Entries
• General settings
• Scripts
• Conditions
• Icons
• Addon configuration
• YAML schema reference

Development

Contributions are welcome. Issues, feature requests, and pull requests can be submitted via GitHub.

To enable pre‑commit hooks that run cargo clippy before pushing:

pip install pre-commit
pre-commit install

Screenshots

File Browser (/)

Currency Converter ($)

Calculator

Script Filter with github PR browser

Script Filter with timezone converter

Light Theme

Licence

This project is released under the MIT Licence.

Author

Chmouel Boudjnah

• GitHub: https://github.com/chmouel
• Fediverse: https://fosstodon.org/@chmouel
• Twitter: https://twitter.com/chmouel
• Blog: https://blog.chmouel.com