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)
Terminal window
```
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.

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.
Terminal window
```
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: firefox --marionette

Example with Sway:

raffi -p | xargs swaymsg exec --

-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.