---
title: CLI Options
description: Command-line flags and options for Raffi
---
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}`).
```bash
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)
```bash
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.
```bash
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.
```bash
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.
```bash
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.
```bash
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:
```bash
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.
```bash
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.
```bash
raffi -r
```
Cache location: `$XDG_CACHE_HOME/raffi/icon.cache` (defaults to `~/.cache/raffi/icon.cache`)
## Examples
### Basic Usage
Launch with default settings:
```bash
raffi
```
### Custom Configuration
Use a custom config file:
```bash
raffi --configfile ~/.config/work/raffi.yaml
```
### Native UI with Light Theme
Launch the native UI with light theme and no icons:
```bash
raffi -u native -t light -I
```
### Print-Only Mode
Print the selected command without executing:
```bash
raffi -p
```
### Pre-filled Search
Launch with an initial search query:
```bash
raffi -u native -i "screenshot"
```
### Refresh Icons and Use Custom Shell
Refresh icon cache and use zsh for scripts:
```bash
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.