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).
-i or --initial-query <QUERY> pre-fills the search field on launch (native mode only).
-t or --theme <THEME> selects dark or light theme (default is dark, native mode only).
--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 theme support (dark by default, light available via -t light or config). It is suitable if you prefer a self‑contained graphical window.
Native Interface Extras
Calculator
Currency Converter
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 €)
Dynamic Script Filters
The native interface supports script filters, which allow external commands to provide dynamic results in the launcher. This feature uses a subset of the Alfred Script Filter JSON format.
When the configured keyword is typed, the script is executed with the remaining input
passed as the final argument. The script must print JSON to stdout. On selection, the
item's arg value (or title if arg is absent) is copied to the clipboard using
wl-copy. Alternatively, a custom action can be configured to run any command with
the selected value substituted via {value} placeholder. A secondary_action can
also be defined, which is triggered with Alt+Enter instead of Enter.
The title and subtitle fields support ANSI color codes in JSON output,
which the launcher renders as colored text. For example, the pr.py script
from alfred-pr-workflow uses
colors to display pull request states.
See below for how to configure this
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.
General Settings
Persistent defaults can be set under a general key. These are equivalent to command‑line flags and are overridden by them.
general:
ui_type: native
theme: light
no_icons: true
default_script_shell: /bin/zsh
theme_colors:
accent: "#cba6f7"
The ui_type field selects the interface (fuzzel or native).
The theme field selects the colour theme for the native interface. dark (default) uses a Dracula‑inspired palette; light uses Rose Pine Dawn.
The no_icons field disables icon loading when set to true.
The default_script_shell field sets the default interpreter for inline scripts.
Individual theme colours can be customised under theme_colors. Each field
accepts a hex colour string (#RGB, #RRGGBB, or #RRGGBBAA). Only the
colours you specify are overridden; the rest come from the base theme.
Available colour keys: bg_base, bg_input, accent, accent_hover,
text_main, text_muted, selection_bg, border.
Example (Catppuccin Mocha on top of the dark base theme):
general:
theme: dark
theme_colors:
bg_base: "#1e1e2e"
bg_input: "#313244"
accent: "#cba6f7"
accent_hover: "#89b4fa"
text_main: "#cdd6f4"
text_muted: "#6c7086"
selection_bg: "#45475a"
border: "#585b70"
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
Path Expansion
Config values for binary, icon, args, ifexist, and script filter fields command, icon, action, and secondary_action support path expansion:
~/is expanded to the user's home directory${VAR}is replaced with the environment variable value (unset variables expand to empty string)
The script field is not expanded as the shell handles it natively.
Example:
myapp:
binary: ${HOME}/bin/myapp
args:
icon: ~/icons/myapp.png
ifexist: ~/bin/myapp
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.
Script filters are configured under addons.script_filters. Here is an example using the batz time converter (shown in the screenshot above):
addons:
script_filters:
- name: "Timezones"
keyword: "tz"
command: "batz"
args:
icon: "clock"
This will parse the output of batz -j and display it in the launcher when the
user types tz followed by a query. The script must output JSON in the format
described below.
An example with both a primary and secondary action:
addons:
script_filters:
- name: "Bookmarks"
keyword: "bm"
command: "my-bookmark-script"
args:
action: "echo -n {value}|wl-copy"
secondary_action: "xdg-open {value}"
Here, pressing Enter copies the selected bookmark URL to the clipboard, while Alt+Enter opens it in the default browser.
Here is the meaning of each field in the script filter configuration:
| Field | Required | Description |
|---|---|---|
name |
yes | Display name shown during loading |
keyword |
yes | Text that activates the script filter |
command |
yes | Executable to run |
args |
no | Arguments passed before the query |
icon |
no | Fallback icon name for results without their own |
action |
no | Command template run on Enter; {value} is replaced with the selected value. Executed via sh -c. If omitted, the value is copied to the clipboard with wl-copy. |
secondary_action |
no | Command template run on Alt+Enter; same {value} substitution and sh -c execution as action. If omitted, Alt+Enter behaves the same as Enter. |
The script must output JSON matching this structure (a subset of Alfred's format):
| Field | Required | Description |
|---|---|---|
title |
yes | Main text displayed for the item |
subtitle |
no | Secondary text shown below the title |
arg |
no | Value copied to clipboard (falls back to title) |
icon.path |
no | Absolute path to a PNG or SVG icon |
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