CLI Options

Raffi supports several command-line flags to control its behavior. All flags are optional and override settings from the configuration file.

Global Flags

--help boolean (default: false)

Print help message and exit.

--version boolean (default: false)

Print version information and exit.

Configuration

-c, --configfile string (default: ~/.config/raffi/raffi.yaml)

Path to the YAML configuration file. Custom entries are read from launchers.yaml in the same directory when this file has no launchers: section.

Supports tilde expansion (~/) and environment variable expansion (${VAR}).

raffi -c ~/custom/config.yaml
raffi --configfile ~/custom/config.yaml

-o, --option KEY=VALUE (repeatable)

Override any YAML configuration setting from the command line.

Keys use dot-separated paths matching raffi.yaml (such as general.theme=nord, addons.emoji.close_on_action=false, or launchers.firefox.close_on_action=false). Sequence entries under addons.script_filters, addons.web_searches, and addons.text_snippets can be addressed by numeric index, name, or keyword. Values are parsed as YAML booleans, numbers, lists, or strings, and validated against the configuration schema.

raffi -o general.close_on_action=false
raffi -o addons.emoji.close_on_action=false -o general.theme=nord
raffi -o 'addons.script_filters.Timezones.close_on_action=false'

--vim-mode boolean (default: false)

Start with modal vim keybindings in normal mode. Equivalent to general.vim_mode: true; the flag wins when both are set. Ctrl+Alt+V toggles vim mode at runtime.

raffi --vim-mode

--keep-open boolean (default: false)

Keep the Raffi window open after executing an action (shorthand for -o general.close_on_action=false). Individual addons or entries can still override this via -o addons.<name>.close_on_action=true.

raffi --keep-open

--check-config boolean (default: false)

Validate the configuration file and launchers.yaml next to it against the JSON Schema and exit without launching anything.

Every problem is printed with the file name, line number and path of the offending key, for example launchers.yaml:12: /firefox: Additional properties are not allowed ('binnary' was unexpected). The exit code is non-zero when problems are found. Old v0 (flat) configs are checked as if migrated, but the file is left untouched and line numbers refer to the original file.

Requires the config-validation Cargo feature, which is enabled by default. Builds made with --no-default-features report that validation is unavailable.

raffi --check-config
raffi --check-config -c ~/custom/config.yaml

--generate-schemas boolean (default: false)

Write or refresh both JSON Schema files next to the selected config file and exit. Use --configfile to choose the config directory.

raffi --generate-schemas --configfile /path/to/raffi.yaml

--install-browser-host boolean (default: false)

Writes a com.vicinae.vicinae.json manifest pointing to the running raffi binary for every Chromium or Firefox based browser with a configuration directory, and prints each file. A manifest Raffi did not install, such as one that starts Vicinae, is left alone unless --force is given.

raffi --install-browser-host
raffi --install-browser-host --force

--uninstall-browser-host boolean (default: false)

Remove the browser host manifests that start Raffi and exit. Manifests of other programs are kept.

raffi --uninstall-browser-host

--force boolean (default: false)

With --install-browser-host, replace manifests Raffi did not install, such as the ones that start Vicinae.

UI Options

-u, --ui-type string

By default Raffi opens its own window. Pass fuzzel to show your entries in Fuzzel instead, a legacy option with fewer features.

raffi -u fuzzel

--app-name string (default: com.chmouel.raffi)

Set the application ID reported for Raffi’s window on Linux. This is useful for targeting the window with compositor or window-manager rules.

raffi --app-name org.example.raffi

-I, --no-icons boolean (default: false)

Disable icon loading for faster startup.

When enabled, no icons are shown. This can significantly speed up startup time, especially on first launch.

raffi -I

-i, --initial-query string

Pre-fill the search field with an initial query.

Useful for launching Raffi with a specific search term already entered.

Addon keywords need their trailing space here too, so use -i "sn " to open a snippet source directly.

Opening help temporarily clears the initial query so all help entries are visible. Closing help restores it.

raffi -i firefox

--last-query boolean (default: false)

Print the last query typed in Raffi’s search box and exit. Raffi’s own window records the raw text each time the query changes, so addon modes such as clip and script filters are included, and a script gets the exact keyword and trailing space back. Nothing is printed when no query has been recorded yet. Fuzzel does its own search and cannot record the typed query.

raffi --last-query
raffi -i "$(raffi --last-query)"

-1, --select-1 boolean (default: false)

With a non-empty --initial-query, automatically activate the only selectable result after its results finish loading. The option applies only to the initial query; typing or refining the query later does not trigger automatic activation.

raffi -1 -i firefox
raffi --select-1 --initial-query firefox

-t, --theme string (default: dark)

Select the color theme.

Valid values:

dark - Sleek Obsidian dark theme (default)
light - Rose Pine Dawn light theme
catppuccin / catppuccin-mocha - Catppuccin Mocha dark theme
catppuccin-latte - Catppuccin Latte light theme
tokyo-night / tokyonight - Tokyo Night dark theme
nord - Nord dark theme
gruvbox - Gruvbox dark theme
dracula - Dracula dark theme
rose-pine / rosepine - Rosé Pine dark theme
kanagawa - Kanagawa Wave dark theme
Terminal window
```
raffi -t tokyo-night
```

--opacity number (default: 0.95)

Opacity of the window backgrounds, from 0.0 (see-through) to 1.0 (solid). Text and icons stay opaque. Overrides general.opacity. Below 1, the default renderer: auto draws on the GPU, which transparency needs. See Transparency and Blur.

raffi --opacity 0.7

Execution Options

-p, --print-only boolean (default: false)

Print the command to stdout instead of executing it.

Useful for debugging or integrating with window managers that execute commands separately.

raffi -p
# Output: env -- firefox --marionette

The output is a shell-ready command line: arguments that need it are single-quoted, so the result is meant to be evaluated by a shell (sh -c "$cmd") rather than word-split. Script entries print as <interpreter> -c '<script>' [<interpreter> <args>...], which means a multi-line script produces multi-line output.

Commands given by name are printed with an env prefix. That makes the receiving shell run the program from your PATH, the same one Raffi would launch itself, instead of a shell builtin, alias or function that happens to share the name. Entries configured with a full path are printed as-is.

Example with Sway:

cmd=$(raffi -p) && [ -n "$cmd" ] && swaymsg exec -- "$cmd"

Do not pipe the output through xargs: xargs strips quotes and splits on whitespace, which mangles arguments containing spaces and breaks script entries. Always quote "$cmd".

-P, --default-script-shell string (default: bash)

Set the default shell interpreter for script entries.

Used when a configuration entry has a script field but no explicit binary field. Common values include bash, zsh, sh, python3, etc.

raffi --default-script-shell zsh

Cache Management

-r, --refresh-cache boolean (default: false)

Refresh every local cache.

Raffi caches icon locations from system directories to speed up subsequent launches. Use this flag to force regeneration of the cache, for example after installing new icon themes. It also removes the private script-filter and browser-history snapshots, the Slack cache and the startup file list, and tells a running cache service to drop its state.

raffi -r

Caches live under $XDG_CACHE_HOME/raffi/ (defaults to ~/.cache/raffi/).

--cache-daemon boolean (default: false)

Run the optional background cache service in the foreground. It warms the script filters, Slack views and browser history you opted into, and serves requests over $XDG_RUNTIME_DIR/raffi/cache.sock. Raffi never starts it behind your back: run it from a terminal or a user service such as misc/systemd/raffi-cache.service.

raffi --cache-daemon

Without the service, Raffi still reads and writes the same private snapshots directly, so cached rows still show immediately; only the periodic warming while Raffi is closed is lost.

The service also keeps Raffi’s own startup files in memory. Each time the window opens, Raffi notes the files it needed to start (the binary, the graphics libraries, fonts, config and caches) in ~/.cache/raffi/hot-files.json. Every few minutes the service reads them back, so the kernel does not evict them, and a launch after a long idle stays as fast as a warm one. When the files are already cached, a pass costs a few tens of milliseconds.

When Raffi opens and finds the service running, the footer shows server. On a Slack view, browser history or a Script Filter with cache_seconds, it shows F5 server refresh instead: F5 asks the service to fetch that source again, waits for it, and reloads the list from the new snapshot. Ctrl+Shift+F5 does the same for every source the service caches, from any view, and has no footer hint.

The footer warns server config differs, restart it when the service was started with a different addons configuration, and server outdated, restart it when it comes from an older Raffi. F5 is disabled in the second case. If the service stops while Raffi is open, F5 shows server not reachable.

The service prints a line to its output each time F5 or Ctrl+Shift+F5 asks for a refresh, then another with how long it took or why it failed:

raffi: refreshing slack:unread
raffi: refreshed slack:unread in 0.7s

Examples

Basic Usage

Launch with default settings:

raffi

Custom Configuration

Use a custom config file:

raffi --configfile ~/.config/work/raffi.yaml

Light Theme

Launch with the light theme and no icons:

raffi -t light -I

Print-Only Mode

Print the selected command without executing:

raffi -p

Pre-filled Search

Launch with an initial search query:

raffi -i "screenshot"

Refresh Icons and Use Custom Shell

Refresh icon cache and use zsh for scripts:

raffi -r --default-script-shell zsh

Precedence

Command-line flags always take precedence over settings in the configuration file’s general section. This allows you to override persistent defaults on a per-launch basis.