raffi 0.25.0

---
title: Launcher Entries
description: Define applications, commands, and scripts in your Raffi launcher
---

## Overview

Entries are the core of Raffi's configuration. Each entry represents an application, command, or script that appears in the launcher. Entries live in `~/.config/raffi/launchers.yaml`, where each top-level key is an entry. They can also go under a `launchers:` key in `raffi.yaml`, see [Configuration Files](../overview/#configuration-files).

You don't need an entry for every application: [Installed Apps](../../features/installed-apps/) lists the apps installed on your system next to your entries, leaving out those an entry already covers.

## Entry Structure

Each entry is identified by a unique key and contains configuration fields:

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

## Configuration Fields

**`binary`** `string` (optional)

Executable name looked up in PATH. Examples: `firefox`, `kitty`.

  If the binary doesn't exist in PATH, the entry is automatically hidden.

  For scripts, this field specifies the interpreter (defaults to `bash` if omitted).


**`description`** `string`

Label shown in the launcher.

  If `binary` is not specified, `description` is used as the binary name.


**`args`** `array`

Command-line arguments passed to the binary.

  Supports path expansion (`~/` and `${VAR}`).


**`icon`** `string`

Icon name from system theme (e.g., `firefox`, `terminal`).

  Raffi looks up the icon by name from system icon directories. See [Icons](../icons/) for details on icon discovery and caching.


**`script`** `string`

Inline script content. When present, the entry executes this script instead of launching `binary` directly.

  See [Scripts](../scripts/) for details.


**`disabled`** `boolean` (default: `false`)

When `true`, hides the entry from the launcher.


**`show_preview`** `boolean` (default: `false`)

When `true`, the native UI shows the right-hand preview pane for this entry (full command or script, conditions, launch stats) even when `general.show_preview` is off. Set to `false` to never preview it.


## Examples

### Basic Application

```yaml title="launchers.yaml"
firefox:
  binary: firefox
  description: "Firefox"
  icon: firefox
```

### Application with Arguments

```yaml title="launchers.yaml"
thunar:
  binary: thunar
  args: ["~/Downloads/"]
  description: "Thunar"
```

### Application with Icon

```yaml title="launchers.yaml"
golang:
  binary: goland
  description: "Goland"
  icon: goland
```

### Entry with Conditional Display

```yaml title="launchers.yaml"
rbw-pass:
  binary: rofi-rbw
  args:
    [
      "--selector wofi --clipboarder wl-copy --action copy-password --typer xdotool",
    ]
  description: "Password Manager"
  icon: password-manager
  ifenvset: WAYLAND_DISPLAY
```

See [Conditions](../conditions/) for conditional visibility options.

### System Commands

```yaml title="launchers.yaml"
suspend:
  binary: systemctl
  args: [suspend]
  description: "Suspend/Sleep or Hibernate"
  icon: system-suspend-hibernate

reboot:
  binary: systemctl
  args: [reboot]
  description: "Reboot / Restart"
  icon: gnome-session-reboot
```

### Disabled Entry

```yaml title="launchers.yaml"
google-meet:
  binary: google-chrome
  args:
    [
      "--profile-directory=Default",
      "--app-id=kjgfgldnnfoeklkmfkjfagphfepbbdan",
    ]
  description: "Google Meet"
  icon: "google-meet"
  disabled: true
```

## Entry Validation

Raffi automatically validates entries on startup. An entry is hidden if:

1. `disabled` is set to `true`
2. The `binary` (or interpreter for scripts) doesn't exist in PATH
3. Conditional checks fail (see [Conditions](../conditions/))

### Binary Discovery

Raffi searches for binaries in directories listed in the `PATH` environment variable. If a binary path is:

- Relative (e.g., `firefox`) - Raffi searches PATH
- Absolute (e.g., `/usr/bin/firefox`) - Raffi checks if the file exists
- Expanded (e.g., `~/bin/myapp`) - Raffi expands the path, then checks existence

## Entry Organization

Entries can be organized in any order in your configuration file. Raffi lists the ones you use first, ranked by [`sort_mode`](../general-settings/#sort_mode); the rest keep the order they have in the file.

```yaml title="launchers.yaml"
# Browsers
firefox:
  binary: firefox
  description: "Firefox"
  icon: firefox

chrome:
  binary: chromium
  description: "Chromium"
  icon: chromium

# System tools
suspend:
  binary: systemctl
  args: [suspend]
  description: "Suspend/Sleep"
  icon: system-suspend-hibernate

reboot:
  binary: systemctl
  args: [reboot]
  description: "Reboot"
  icon: gnome-session-reboot
```

## Common Patterns

### Jump or Raise Applications

```yaml title="launchers.yaml"
wally:
  binary: jumpapp
  args: ["-X", "wally"]
  description: "Wally"
  icon: wally
  ifexist: wally
```

### SSH Connections

```yaml title="launchers.yaml"
ssh-pi:
  binary: kitty-ctrl
  args: ["jump", "-t", "PI", "ssh", "pi"]
  description: "PI"
  icon: raspberry
```

### Desktop Applications with Custom Profiles

```yaml title="launchers.yaml"
chrome-work:
  binary: chromium
  args: ["--profile-directory=Work"]
  description: "Chromium (Work Profile)"
  icon: chromium
```