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.
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:
On NixOS or using Nix (unstable channel):
With LinuxBrew or Homebrew:
From crates.io:
To build from source:
If you only require Fuzzel integration and want a significantly smaller binary, build without the native UI:
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. The chosen item is executed according to the configuration.
Common options include:
-p or --print-only prints the command rather than executing it.
-c or --configfile <FILE> selects a custom configuration file.
-r or --refresh-cache refreshes cached icon paths.
-I or --disable-icons disables icons for slightly faster startup.
-u or --ui-type <TYPE> selects fuzzel or native (default is fuzzel).
--default-script-shell <SHELL> sets the default interpreter for scripts.
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")
User Interfaces
Raffi supports two interface modes.
Fuzzel mode uses the external Fuzzel launcher and integrates naturally with Wayland environments.
Native mode uses an internal iced‑based graphical interface with fuzzy search, keyboard navigation, and a dark theme. It is suitable if you prefer a self‑contained graphical window.
Native Interface Extras
The native interface includes a built‑in calculator which evaluates expressions as you type. Standard mathematical operators are supported, along with functions such as sqrt, sin, cos, tan, log, ln, exp, abs, floor, and ceil. Results can be copied to the clipboard using Enter, provided wl-copy is available.
The native interface also includes a currency converter. Enter an amount prefixed with the configured trigger (default $) followed by a target currency. Exchange rates are fetched from the Frankfurter API and cached for one hour.
Example inputs:
$10 to eur
$50 gbp to usd
$100eur to jpy
€10 to usd (with trigger set to €)
Configuration
Fuzzel Configuration
Fuzzel appearance can be configured through ~/.config/fuzzel/fuzzel.ini. Refer to the Fuzzel manual for full details.
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=bd93f9ff
Raffi Configuration
Configuration is stored in:
$HOME/.config/raffi/raffi.yaml
Basic example:
firefox:
binary: firefox
args:
icon: firefox
description: Firefox browser with marionette enabled
The binary field defines the executable. If the binary is not present in PATH, the entry is ignored.
The description field defines the label shown in the launcher.
The args field defines optional command‑line arguments.
The icon field defines an icon name or absolute path. Icons are cached and can be refreshed with -r.
The script field defines inline script content.
The disabled field hides the entry when set to true.
Scripts
Entries can run inline scripts instead of binaries. Scripts use bash by default, or another interpreter if configured via --default-script-shell or by explicitly setting binary.
Example:
hello_script:
script: |
echo "hello world and show me your env"
env
description: "Hello Script"
icon: "script"
Python example:
hello_script:
binary: python3
script: |
import os
print("hello world and show me your env")
print(os.environ)
description: "Hello Python script"
icon: "script"
Conditional Display
Entries can be shown or hidden based on simple conditions. Only one condition is supported per entry.
Conditions include checking whether a binary exists, whether an environment variable is set, not set, or equal to a specific value.
Example:
ifenveq:
ifenvset: WAYLAND_DISPLAY
ifexist: firefox
Addon Configuration
The native interface includes optional addons for calculations and currency conversion. These are enabled by default and can be configured or disabled.
addons:
currency:
enabled: true
trigger: "€"
default_currency: EUR
currencies:
calculator:
enabled: true
The enabled field controls whether the addon is active.
The trigger field sets the character that activates currency conversion. Defaults to $ if omitted. Can be set to €, £, or any other symbol.
The default_currency field sets the source currency used when none is specified (e.g., €10 to GBP converts from EUR). Defaults to USD if omitted.
The currencies field for the currency addon defines which currencies are available for conversion.
Both addons are enabled by default. Omitting the addons section preserves this behaviour.
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:
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