Launcher Entries

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:

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 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 for details.

disabled boolean (default: false)

When true, hides the entry from the launcher.

Examples

Basic Application

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

Application with Arguments

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

Application with Icon

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

Entry with Conditional Display

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 for conditional visibility options.

System Commands

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

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)

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.

# 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

launchers:
  wally:
    binary: jumpapp
    args: ["-X", "wally"]
    description: "Wally"
    icon: wally
    ifexist: wally

SSH Connections

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

Desktop Applications with Custom Profiles

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