Raffi is a launcher that wraps the Fuzzel utility, allowing you to define commands and scripts in a YAML configuration file. It supports icons, custom arguments, conditional display, and script execution with configurable interpreters.
Visit the release page and download the archive or package for your platform.
Ensure you have Fuzzel installed.
brew tap chmouel/raffi https://github.com/chmouel/raffi
brew install rafficargo install raffiUsing your preferred AUR helper, for example, yay:
yay -S raffi-binNixOS / Nix (unstable)
nix-shell -p raffiTo install Raffi from source, clone the repository and build it using Cargo:
git clone https://github.com/chmouel/raffi.git
cd raffi
cargo build --releaseIf you only need the Fuzzel UI and want to reduce binary size significantly, build with the Wayland feature disabled:
cargo build --release --no-default-featuresThis reduces the binary size from 15 MB (with Wayland) to 1.1 MB (93% smaller), as the Wayland UI depends on the heavy iced GUI framework. Use this option if you only plan to use Fuzzel or need a minimal installation.
Run raffi to launch the configured items through Fuzzel. The application will execute the selected entry according to your configuration.
Common options:
-p/--print-only: Print the command instead of executing it-c/--configfile <FILE>: Specify a custom configuration file-r/--refresh-cache: Refresh the cached icon paths-I/--disable-icons: Run without icons (marginally faster)-u/--ui-type <TYPE>: Select UI type (fuzzelorwayland, default:fuzzel)--default-script-shell <SHELL>: Shell for scripts (default:bash)--version: Show version--help: Show all options
Here is an example of how to use Raffi with Sway:
// Set a variable that can be easily used later in the config file
// These variables are optional
set $menu raffi -p
// Mod4 is the Super key for me, but use whatever you want.
set $super Mod4
// Bind the Super+Space key to launch the launcher
bindsym $super+Space exec $menu | xargs swaymsg exec --
$super = SUPER
bind = $super, R, exec, (val=$(raffi -pI); echo $val | grep -q . && hyprctl dispatch exec "$val")
Raffi supports two UI options via the --ui-type flag:
Fuzzel (default): External launcher using Fuzzel. Good integration with Wayland.
Wayland: Built-in GUI using the iced framework. Displays a dark-themed window with fuzzy search. Navigation via arrow keys, Enter to select, Esc to cancel. Useful if you prefer a native window over an external launcher.
Example with Wayland UI in Sway:
set $super Mod4
bindsym $super+Space exec raffi -u wayland
for_window [app_id="com.chmouel.raffi"] floating enable, resize set 800 600, move position center
Configure Fuzzel's appearance via ~/.config/fuzzel/fuzzel.ini. See the manpage for options. Example:
dpi-aware=yes
font=RobotoMonoNerdFont-Thin:size=16
terminal=kitty
width=50
layer=overlay
exit-on-keyboard-focus-loss=no
inner-pad=15
fields=filename,name
[colors]
background=282a36ff
text=f8f8f2ff
match=8be9fdff
selection-match=8be9fdff
selection=44475add
selection-text=f8f8f2ff
border=bd93f9ffConfiguration goes in $HOME/.config/raffi/raffi.yaml. Basic example:
firefox:
binary: firefox
args: [--marionette]
icon: firefox
description: Firefox browser with marionette enabledFields:
binary: The executable to run. Skipped if not in PATH.description: Label shown in the launcher.args: Command-line arguments as an array (optional).icon: Icon name or full path (optional). Searched in standard directories. Icon paths are cached; refresh with-r.script: Inline script to execute (see below).disabled: Set totrueto hide the entry.
Define inline scripts instead of binaries. Scripts run via bash by default, or specify a different interpreter with --default-script-shell. Use the binary field to set the interpreter explicitly. Example:
hello_script:
script: |
echo "hello world and show me your env"
env
description: "Hello Script"
icon: "script"With a different interpreter:
hello_script:
binary: python3
script: |
import os
print("hello world and show me your env")
print(os.environ)
description: "Hello Python script"
icon: "script"With interpreter arguments:
hello_script:
binary: sh
args: ["-xv"]
script: |
echo "hello world and show me your env"
env
description: "Hello debug"
icon: "script"Entries can be shown or hidden based on conditions. Conditions are optional and cannot be combined.
ifexist: Show if binary exists in PATH or at full path.ifenvset: Show if environment variable is set.ifenvnotset: Show if environment variable is not set.ifenveq: Show if environment variable equals a specified value.
Example:
ifenveq: [DESKTOP_SESSION, GNOME]
ifenvset: WAYLAND_DISPLAY
ifexist: firefoxSee the file located in examples/raffi.yaml for a more comprehensive example.
Contributions welcome. For issues, feature requests, or pull requests, see the GitHub repository.
To set up pre-commit hooks that run cargo clippy before pushing:
pip install pre-commit
pre-commit installThis project is licensed under the MIT License.
- Chmouel Boudjnah https://github.com/chmouel
- Fediverse - <@chmouel@fosstodon.org>
- Twitter - <@chmouel>
- Blog - <https://blog.chmouel.com>