raffi 0.25.0

---
title: Configuration Overview
description: Learn how to configure Raffi's launcher entries and settings
---

import { Aside, Card, CardGrid } from '@astrojs/starlight/components';

## Configuration Files

Raffi reads two files from `$HOME/.config/raffi/`:

```
$HOME/.config/raffi/raffi.yaml       # general settings and addons
$HOME/.config/raffi/launchers.yaml   # launcher entries
```

Keeping launchers in `launchers.yaml` is the recommended layout: the file you edit most stays short and free of settings, and `raffi.yaml` only holds what you rarely touch. Both files are optional. Raffi reads `launchers.yaml` when `raffi.yaml` is missing or has no `launchers:` section of its own; if `raffi.yaml` does define launchers, those win and `launchers.yaml` is ignored with a warning.

You can override the location of `raffi.yaml` with the `-c` or `--configfile` flag. Raffi then looks for `launchers.yaml` in the same directory:

```bash
raffi --configfile /path/to/custom/raffi.yaml
```

Raffi writes `raffi-schema.json` and `launchers-schema.json` next to your config so editors can validate both files as you type, and warns on stderr about unknown or invalid keys when it starts. Run `raffi --check-config` to validate them on demand. See [Validation](../../reference/yaml-schema/#validation) for details.

## Basic Structure

`launchers.yaml` is a mapping of entry names to [entries](../entries/). `raffi.yaml` has two main sections:

1. **General settings** - UI preferences, theme, fonts, window dimensions
2. **Addons** - Optional features like script filters, web searches, text snippets

### Minimal Example

```yaml title="launchers.yaml"
firefox:
  binary: firefox
  args: [--marionette]
  icon: firefox
  description: Firefox browser with marionette enabled
```

### Complete Structure

```yaml title="raffi.yaml"
version: 1

# General settings (optional)
general:
  ui_type: native
  theme: dark
  font_size: 20
  window_width: 800
  window_height: 600

# Addons (optional)
addons:
  script_filters:
    - name: "Timezones"
      keyword: "tz"
      command: "batz"
      args: ["-j"]

  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
```

```yaml title="launchers.yaml"
firefox:
  binary: firefox
  description: "Firefox"
  icon: firefox
  args: ["--marionette"]

terminal:
  binary: kitty
  description: "Terminal"
  icon: terminal
```

### Launchers Inside raffi.yaml

A single file still works. Put the entries under a `launchers:` key in `raffi.yaml`, indented one level. The snippets in these docs are written for `launchers.yaml`; to use one in `raffi.yaml`, nest it under `launchers:`:

```yaml title="raffi.yaml"
version: 1

launchers:
  firefox:
    binary: firefox
    icon: firefox
```

## Configuration Sections

<div class="nav-cards">
  <CardGrid>
    <a href="../general-settings/">
      <Card title="General Settings" icon="setting">
        UI type, theme, fonts, and window settings
      </Card>
    </a>
    <a href="../entries/">
      <Card title="Entries" icon="rocket">
        Define launcher entries with binaries, scripts, and arguments
      </Card>
    </a>
    <a href="../icons/">
      <Card title="Icons" icon="star">
        Icon caching, discovery, and path configuration
      </Card>
    </a>
    <a href="../scripts/">
      <Card title="Scripts" icon="pencil">
        Inline scripts with bash, python, or custom interpreters
      </Card>
    </a>
    <a href="../conditions/">
      <Card title="Conditions" icon="magnifier">
        Conditional visibility based on environment or binary existence
      </Card>
    </a>
    <a href="../../reference/addon-configuration/">
      <Card title="Addons" icon="puzzle">
        Optional features like script filters, web searches, and text snippets
      </Card>
    </a>
  </CardGrid>
</div>

<style>
{`
  .nav-cards a {
    text-decoration: none !important;
    color: inherit;
    display: flex;
    height: 100%;
  }
  .nav-cards a article {
    flex: 1;
    transition: all 0.2s ease-in-out;
    cursor: pointer;
    display: flex;
    flex-direction: column;
    gap: 1rem;
    border: 1px solid var(--sl-color-gray-5);
    background-color: var(--sl-color-black);
  }
  .nav-cards a article .title {
    display: flex;
    flex-direction: column;
    align-items: flex-start;
    gap: 1rem;
    font-size: 1.2rem;
  }
  .nav-cards a article .title .icon {
    font-size: 2.5rem !important; /* Huge icons */
    color: var(--sl-color-purple);
    background: var(--sl-color-purple-low);
    padding: 0.5rem;
    border-radius: 0.5rem;
    border: 1px solid var(--sl-color-purple);
  }
  .nav-cards a:hover article {
    border-color: var(--sl-color-text-accent);
    background-color: var(--sl-color-gray-6);
  }
`}
</style>

## Path Expansion

Most configuration fields support path expansion:

- `~/` expands to your home directory
- `${VAR}` expands to environment variable values
- Unset variables expand to empty strings

```yaml title="launchers.yaml"
myapp:
  binary: ${HOME}/bin/myapp
  args: ["${XDG_DATA_HOME}/files", "~/Documents"]
  icon: ~/icons/myapp.png
  ifexist: ~/bin/myapp
```

<Aside type="note">
Path expansion is **not** applied to script content (`script` field). Only use it for paths, binaries, icons, and arguments.
</Aside>