---
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. Launcher 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}`).
```bash
raffi -c ~/custom/config.yaml
raffi --configfile ~/custom/config.yaml
```
**`--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.
```bash
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.
```bash
raffi --generate-schemas --configfile /path/to/raffi.yaml
```
**`--install-browser-host`** `boolean` (default: `false`)
Register Raffi as the native messaging host of the Vicinae browser extension, for the [browser tabs](../../features/browser-tabs/) list, and exit.
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.
```bash
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.
```bash
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` (default: `native` in standard builds; `fuzzel` in Fuzzel-only builds)
Select the user interface backend. Native is the default and recommended option
in standard builds; Fuzzel is a deprecated legacy backend.
Valid values:
- `fuzzel` - Uses the deprecated 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
```
**`--app-name`** `string` (default: `com.chmouel.raffi`)
Set the application ID reported for the native window on Linux. This is useful for targeting the window with compositor or window-manager rules. It has no effect when using Fuzzel.
```bash
raffi -u native --app-name org.example.raffi
```
**`-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.
Addon keywords need their trailing space here too, so use `-i "sn "` to open a
snippet source directly.
In native mode, opening help temporarily clears the initial query so all help
entries are visible. Closing help restores it.
```bash
raffi -u native -i firefox
```
**`-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. Native UI only.
```bash
raffi -1 -i firefox
raffi --select-1 --initial-query firefox
```
**`-t, --theme`** `string` (default: `dark`)
Select the color theme for the native UI.
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
Only affects native UI mode.
```bash
raffi -u native -t tokyo-night
```
## 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.