raffi 0.22.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 are defined under the `launchers` key in your configuration file.

## Entry Structure

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

```yaml
launchers:
  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](/configuration/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](/configuration/scripts) for details.


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

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


## Examples

### Basic Application

```yaml
launchers:
  firefox:
    binary: firefox
    description: "Firefox"
    icon: firefox
```

### Application with Arguments

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

### Application with Icon

```yaml
launchers:
  golang:
    binary: goland
    description: "Goland"
    icon: goland
```

### Entry with Conditional Display

```yaml
launchers:
  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](/configuration/conditions) for conditional visibility options.

### System Commands

```yaml
launchers:
  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
launchers:
  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](/configuration/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 displays them alphabetically by description in the launcher.

```yaml
# Browsers
launchers:
  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
launchers:
  wally:
    binary: jumpapp
    args: ["-X", "wally"]
    description: "Wally"
    icon: wally
    ifexist: wally
```

### SSH Connections

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

### Desktop Applications with Custom Profiles

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