Raffi Application Launcher

Raffi is an application launcher for Wayland. You define commands and scripts in a YAML file, with icons, arguments, conditions for when an entry shows up, and the interpreter each script runs with. Raffi is based on Rust and is fast, lightweight and secure and works without a server or a DB. It has a native interface with fuzzy search, keyboard navigation, themes and a preview pane. It also has a legacy Fuzzel interface for simplier workflow.

Documentation

The full documentation is at https://chmouel.github.io/raffi/. Good places to start:

• Installation
• Quick start
• Configuration overview
• CLI options

Screenshot

See more screenshots below

Installation

Prebuilt binaries and packages are on the GitHub releases page. The standard release assets use the native interface. Linux x86_64 releases also include a smaller Fuzzel-only archive; it requires Fuzzel, and config validation is disabled (--check-config reports that it is unavailable, and startup warnings about unknown keys are not shown). The deprecated Fuzzel interface remains selectable in the standard build: install Fuzzel and pass -u fuzzel or set ui_type: fuzzel.

On Arch Linux, install it from the AUR with 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 use Fuzzel, you can build without the native UI:

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

The binary drops from about 15 MB to about 2.1 MB. This build also disables config validation: --check-config reports that the feature is unavailable, and startup warnings about unknown keys are not shown. Add --features config-validation to keep validation, which adds a few MB.

Usage

Run raffi to pick one of your configured entries. Without a config, or with no valid launchers in it, Raffi lists the desktop applications installed on your system.

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 cmd=$($menu) && [ -n "$cmd" ] && swaymsg exec -- "$cmd"

Hyprland

$super = SUPER
bind = $super, R, exec, (val=$(raffi -pI); [ -n "$val" ] && hyprctl dispatch exec "$val")

See also: Sway integration · Hyprland integration · Legacy Fuzzel integration

User Interfaces

Raffi's built-in native interface is the default and recommended UI, with fuzzy search, keyboard navigation and themes. The external Fuzzel interface is deprecated but remains available as a legacy option for existing setups.

The native interface also comes with addons. Some answer as you type: a calculator, currency and unit conversion, a color converter, a world clock and developer tools (encoders, hashes, UUID and password generators). Others let you search and pick: a file browser, an emoji and Nerd Fonts picker, text snippets, clipboard history (through CopyQ), web searches and script filters. The rest control your desktop: system commands (lock, suspend, hibernate, log out, reboot, shut down), a window switcher for Hyprland, niri and sway, a browser tab switcher (using the Vicinae browser extension), media controls, volume and audio devices, Bluetooth, a way to stop your own processes, and > command to run a command in a terminal. Your installed applications can be listed next to your launchers. Two more copy or type passwords from pass and Bitwarden (through rbw), unlocking the vault when needed. An optional Slack addon opens conversations, searches messages, lists unread ones and sets your status.

A preview pane on the right shows details for the selected item, and Ctrl+P toggles it. In the file browser it shows PDF pages, video frames, ebook covers, archive contents and highlighted source code when python3 is installed. Ctrl+/ lists every keyword and shortcut your config defines.

See: UI modes · Themes · Calculator · Currency converter · Unit conversion · Color converter · World clock · Developer tools · File browser · Script filters · Web search · Text snippets · Clipboard history · System commands · Window switcher · Browser tabs · Media controls · Audio switcher · Installed apps · Run in terminal · Kill process · Bluetooth · Password store · Bitwarden · Slack

Configuration

Raffi reads launcher entries from $HOME/.config/raffi/launchers.yaml and settings from $HOME/.config/raffi/raffi.yaml. Both are optional. A basic launchers.yaml:

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

Entries can also live under a launchers: key in raffi.yaml; when they do, launchers.yaml is ignored. See examples/raffi.yaml and examples/launchers.yaml for fuller examples.

The docs cover the rest of the configuration:

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

Development

Issues and pull requests are welcome on GitHub.

To run cargo clippy through pre-commit hooks before pushing:

pip install pre-commit
pre-commit install

Screenshots

Search and Recent Picks

Desktop and Utilities

Clipboard and Passwords

Interface Modes

Search, Help, and Scripts

Themes

Licence

This project is released under the MIT Licence.

Author

Chmouel Boudjnah

• Fediverse - @chmouel@chmouel.com
• Twitter - @chmouel
• Blog - https://blog.chmouel.com