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.

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

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

UI Options

-u, --ui-type string (default: fuzzel)

Select the user interface backend.

Valid values:

• fuzzel - Uses the external Fuzzel launcher (requires Fuzzel to be installed)

• native - Uses the built-in iced-based graphical interface (requires build with wayland feature)

  raffi -u native

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

Disable icon loading for faster startup.

When enabled, no icons will be displayed in the launcher interface. 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.

Only works in native UI mode. 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.

raffi -u native -i firefox

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

Select the color theme for the native UI.

Valid values:

• dark - Dracula-inspired dark theme (default)

• light - Rose Pine Dawn light theme

  Only affects native UI mode.

  raffi -u native -t light

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 the cached icon paths.

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.

raffi -r

Cache location: $XDG_CACHE_HOME/raffi/icon.cache (defaults to ~/.cache/raffi/icon.cache)

Examples

Basic Usage

Launch with default settings:

raffi

Custom Configuration

Use a custom config file:

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

Native UI with Light Theme

Launch the native UI with light theme and no icons:

raffi -u native -t light -I

Print-Only Mode

Print the selected command without executing:

raffi -p

Pre-filled Search

Launch with an initial search query:

raffi -u native -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.