---
title: YAML Configuration Schema
description: Complete reference for raffi.yaml and launchers.yaml
---
Raffi reads settings from `~/.config/raffi/raffi.yaml` and launcher entries from `~/.config/raffi/launchers.yaml`.
## Top-Level Structure
`raffi.yaml` holds the settings:
```yaml title="raffi.yaml"
version: 1
general:
# General settings and UI configuration
addons:
# Addon configurations (currency, calculator, etc.)
```
`launchers.yaml` holds the entries, one top-level key per entry:
```yaml title="launchers.yaml"
entry_name:
binary: command
description: "Display name"
# ... other entry fields
```
`raffi.yaml` may also contain the entries under a `launchers:` key. In that case `launchers.yaml` is ignored, so pick one place for them. `launchers.yaml` is used when `raffi.yaml` is missing or has no `launchers:` section.
## General Section
Persistent defaults for UI and behavior. All fields are optional and can be overridden by command-line flags.
**`general.ui_type`** `string` (default: `native` in standard builds; `fuzzel` in Fuzzel-only builds)
Default UI backend to use. Native is the default and recommended option in
standard builds; Fuzzel is a deprecated legacy backend.
Valid values: `fuzzel` (deprecated), `native`
```yaml
general:
ui_type: native
```
**`general.default_script_shell`** `string` (default: `bash`)
Default interpreter for script entries.
Used when an entry has a `script` field but no explicit `binary` field.
```yaml
general:
default_script_shell: /bin/zsh
```
**`general.no_icons`** `boolean` (default: `false`)
Disable icon loading globally.
```yaml
general:
no_icons: true
```
**`general.show_preview`** `boolean` (default: `false` for launchers)
Show the right-hand preview pane for plain launcher entries. Addon results always preview. Toggle at runtime with `Ctrl+P`.
```yaml
general:
show_preview: true
```
**`general.preview`** `object`
Appearance of the preview pane: `font_size` (default `16`), `font_family`, `mono_font_family`, `width_percent` (default `50`, 10–80) and `colors` (`bg`, `bg_block`, `text_main`, `text_muted`, `accent`, `border`).
```yaml
general:
preview:
font_size: 18
width_percent: 55
colors:
accent: "#cba6f7"
```
**`general.theme`** `string` (default: `dark`)
Color theme for native UI.
Valid values: `dark`, `light`
```yaml
general:
theme: light
```
**`general.max_history`** `number` (default: `10`)
Maximum number of search query history entries to keep.
Set to `0` to disable history. Navigate history with Alt+P (previous) and Alt+N (next) in native mode.
```yaml
general:
max_history: 20
```
**`general.font_size`** `number` (default: `20`)
Base font size in pixels for native UI.
Other UI elements scale proportionally:
- Input text: 1.2× base size (24px by default)
- Item text: 1.0× base size (20px by default)
- Subtitle text: 0.7× base size (14px by default)
- Hint text: 0.6× base size (12px by default)
```yaml
general:
font_size: 16
```
**`general.font_family`** `string` (default: `system sans-serif`)
Font family name for native UI.
```yaml
general:
font_family: "Inter"
```
**`general.window_width`** `number` (default: `800`)
Window width in pixels for native UI.
```yaml
general:
window_width: 900
```
**`general.window_height`** `number` (default: `600`)
Window height in pixels for native UI.
```yaml
general:
window_height: 500
```
**`general.padding`** `number` (default: `20`)
Outer window padding in pixels for native UI.
By default, scales automatically with `font_size`. Set explicitly to override.
```yaml
general:
padding: 30
```
**`general.fallbacks`** `list of strings` (default: `[]`)
Addon entries shown at the bottom of the launcher list when typing a non-empty query. Useful for search-type addons (web searches, script filters).
Format: `addons.<type>."<name>"` where `<type>` is `web_searches` or `script_filters`.
```yaml
general:
fallbacks:
- addons.web_searches."Google"
- addons.script_filters."Search DuckDuckGo"
```
**`general.main_view`** `list of strings` (default: unset)
Sources mixed into the main list when typing without an addon trigger, grouped in this order. Native UI only. When set, launchers only appear if `launchers` is listed. See [Main view](../../configuration/general-settings/#main-view).
Entries: `launchers`, `browser_tabs`, `windows`, `system`, `media`, `audio`, `bluetooth`, `pass`, `text_snippets.<name>`, `script_filters.<name>`.
```yaml
general:
main_view:
- launchers
- browser_tabs
- text_snippets."Emails"
```
**`general.theme_colors`** `object`
Custom color overrides for the native UI theme.
Each field accepts a hex color string: `#RGB`, `#RRGGBB`, or `#RRGGBBAA`. Only specified colors are overridden; others use the base theme defaults.
Available color keys:
- `bg_base` - Main background color
- `bg_input` - Input field background
- `accent` - Accent color (selected items, borders)
- `accent_hover` - Hover state for accented elements
- `text_main` - Primary text color
- `text_muted` - Secondary/muted text color
- `selection_bg` - Selected item background
- `border` - Border color
```yaml
general:
theme: dark
theme_colors:
bg_base: "#1e1e2e"
bg_input: "#313244"
accent: "#cba6f7"
accent_hover: "#89b4fa"
text_main: "#cdd6f4"
text_muted: "#6c7086"
selection_bg: "#45475a"
border: "#585b70"
```
## Entry Fields
Each top-level key in `launchers.yaml` (or each key under `launchers` in `raffi.yaml`) defines a launcher entry.
**`binary`** `string` (optional)
The executable command to run.
If the binary is not found in `$PATH`, the entry is automatically hidden.
```yaml title="launchers.yaml"
firefox:
binary: firefox
description: "Firefox Browser"
```
**`description`** `string`
Display name shown in the launcher.
If omitted, the entry key or binary name is used.
```yaml title="launchers.yaml"
firefox:
binary: firefox
description: "Firefox Browser"
```
**`args`** `array[string]`
Command-line arguments to pass to the binary.
Supports tilde and environment variable expansion.
```yaml title="launchers.yaml"
firefox:
binary: firefox
args: ["--marionette", "--private-window"]
description: "Firefox Private"
```
**`icon`** `string`
Icon name resolved from system icon directories (`$XDG_DATA_DIRS/icons`, `$XDG_DATA_DIRS/pixmaps`). Prefers larger icons (48×48+) as Raffi renders at 48×48. Supports PNG and SVG formats.
```yaml title="launchers.yaml"
firefox:
binary: firefox
icon: firefox
description: "Firefox"
```
**`script`** `string`
Inline script content to execute.
When present, the `binary` field specifies the interpreter (defaults to `bash` or the value of `--default-script-shell`). The `args` field can provide arguments to the interpreter.
Script expansion (`~/` and `${VAR}`) is **not** performed on the script content itself.
```yaml title="launchers.yaml"
hello_script:
script: |
echo "Hello, world!"
date
description: "Hello Script"
python_script:
binary: python3
script: |
import datetime
print(f"Current time: {datetime.datetime.now()}")
description: "Python Time"
```
**`disabled`** `boolean` (default: `false`)
Hide this entry from the launcher.
```yaml title="launchers.yaml"
experimental_feature:
binary: experimental
description: "Experimental Feature"
disabled: true
```
**`show_preview`** `boolean` (default: `false`)
Show the right-hand preview pane for this entry in the native UI, regardless of `general.show_preview`.
```yaml title="launchers.yaml"
deploy:
script: |
kubectl apply -f deploy.yaml
description: "Deploy"
show_preview: true
```
### Conditional Display
Entries can be conditionally shown based on environment variables or file existence. Multiple conditions can be specified per entry — when present, they are AND-ed together (all must pass).
**`ifenveq`** `array[string]`
Show entry only if an environment variable equals a specific value.
Must be an array with exactly two elements: `[VARIABLE_NAME, expected_value]`
```yaml title="launchers.yaml"
gnome_settings:
binary: gnome-control-center
description: "Settings"
ifenveq: [DESKTOP_SESSION, GNOME]
```
**`ifenvset`** `string`
Show entry only if the specified environment variable is set (to any value).
```yaml title="launchers.yaml"
wayland_tool:
binary: some-wayland-tool
description: "Wayland Tool"
ifenvset: WAYLAND_DISPLAY
```
**`ifenvnotset`** `string`
Show entry only if the specified environment variable is **not** set.
```yaml title="launchers.yaml"
x11_only:
binary: some-x11-tool
description: "X11 Tool"
ifenvnotset: WAYLAND_DISPLAY
```
**`ifexist`** `string`
Show entry only if the specified binary exists in `$PATH`.
```yaml title="launchers.yaml"
spotify:
binary: spotify
description: "Spotify"
ifexist: spotify
```
## Addons Section
The `addons` section configures built-in addons for the native UI. See [Addon Configuration](../addon-configuration/) for detailed documentation.
```yaml
addons:
currency:
enabled: true
calculator:
enabled: true
file_browser:
enabled: true
script_filters: []
web_searches: []
text_snippets: []
```
## Validation
Raffi generates JSON Schemas for both files and keeps copies named `raffi-schema.json` and `launchers-schema.json` next to your config file. The copies are rewritten whenever they no longer match the running version of Raffi.
To explicitly write or refresh both schemas beside a config file, run:
```bash
raffi --generate-schemas --configfile /path/to/raffi.yaml
```
Point your editor at them by adding this line at the top of each file (supported by any editor using [yaml-language-server](https://github.com/redhat-developer/yaml-language-server)):
```yaml title="raffi.yaml"
# yaml-language-server: $schema=raffi-schema.json
```
```yaml title="launchers.yaml"
# yaml-language-server: $schema=launchers-schema.json
```
Unknown keys (a typo such as `binnary:`) and wrong value types are then flagged while you edit.
Raffi also validates the config every time it loads it. Problems are printed to stderr as warnings and Raffi keeps running, ignoring unknown keys as before:
```
raffi: config warning: /home/user/.config/raffi/launchers.yaml:12: /firefox: Additional properties are not allowed ('binnary' was unexpected)
```
To check a config explicitly, for example in a script or after editing, run `raffi --check-config`. It checks `raffi.yaml` and `launchers.yaml`, prints all problems and exits with a non-zero status if any were found.
The startup warnings and `--check-config` need the `config-validation` Cargo feature, which is enabled by default. Minimal `--no-default-features` builds skip them, though the schema file is still written for your editor.
## Path Expansion
Most configuration fields (except `script`) support path and variable expansion:
- `~/` expands to `$HOME`
- `${VAR}` expands to the value of environment variable `VAR` (empty string if unset)
```yaml title="launchers.yaml"
myapp:
binary: ${HOME}/bin/myapp
args: ["${XDG_DATA_HOME}/files", "~/Documents"]
icon: ~/icons/myapp.png
ifexist: ~/bin/myapp
```
## Complete Example
```yaml title="raffi.yaml"
version: 1
general:
ui_type: native
theme: dark
font_size: 20
font_family: "Inter"
window_width: 800
window_height: 600
max_history: 10
default_script_shell: bash
theme_colors:
accent: "#cba6f7"
addons:
currency:
enabled: true
trigger: "$"
default_currency: USD
calculator:
enabled: true
file_browser:
enabled: true
show_hidden: false
web_searches:
- name: "Google"
keyword: "g"
url: "https://google.com/search?q={query}"
icon: "google"
```
```yaml title="launchers.yaml"
firefox:
binary: firefox
args: ["--marionette"]
icon: firefox
description: "Firefox Browser"
thunder:
binary: thunar
args: ["~/Downloads/"]
description: "File Manager"
hello_script:
script: |
echo "Hello, world!"
date
description: "Hello Script"
icon: "script"
gnome_settings:
binary: gnome-control-center
description: "System Settings"
icon: preferences-system
ifenveq: [DESKTOP_SESSION, GNOME]
suspend:
binary: systemctl
args: [suspend]
description: "Suspend/Sleep"
icon: system-suspend
```