Conditions

Overview

A custom entry can stay hidden until a condition holds. Use conditions to:

Show entries only in specific desktop environments or compositors
Display entries only when certain binaries are installed
Conditionally show entries based on environment variables

Multiple conditions can be specified per entry. When an entry has several, all of them must pass for it to show.

Condition Types

ifenvset

Shows the entry only if an environment variable is set (to any value).

ifenvset string

Environment variable name. Entry is shown only if this variable is set.

Example: Wayland-Only Entry

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

This entry appears only when WAYLAND_DISPLAY is set (i.e., in Wayland sessions).

Example: Sway-Specific Entry

cliphistory:
  binary: clipman
  args: ["pick", "-t", "wofi"]
  description: "Clipboard history"
  icon: accessories-clipboard
  ifenvset: SWAYSOCK

ifcompositor says the same thing more directly.

ifenvnotset

Shows the entry only if an environment variable is not set.

ifenvnotset string

Environment variable name. Entry is shown only if this variable is not set.

Example

x11-only:
  binary: xdotool
  description: "X11 Tool"
  ifenvnotset: WAYLAND_DISPLAY

ifenveq

Shows the entry only if an environment variable equals a specific value.

ifenveq array

Array with exactly two elements: [VARIABLE_NAME, EXPECTED_VALUE].

Entry is shown only if $VARIABLE_NAME == EXPECTED_VALUE.

Example: GNOME-Only Entry

keyboard-setting:
  binary: gnome-control-center
  args: [keyboard]
  description: "Keyboard setting"
  icon: preferences-desktop-keyboard-shortcuts
  ifenveq: [DESKTOP_SESSION, GNOME]

Example: X11-Only Entry

snap-window-around:
  binary: wmctrl-resize-and-center
  args: [rotate]
  description: "Snap window around"
  icon: wmaround
  ifenveq: [XDG_SESSION_TYPE, x11]

Example: Desktop Environment Check

gnome-shutdown:
  binary: gnome-session-quit
  args: [--power-off]
  description: "Shutdown / Poweroff"
  icon: gnome-shutdown
  ifenveq: [DESKTOP_SESSION, GNOME]

reboot:
  binary: gnome-session-quit
  args: [--reboot]
  description: "Reboot"
  icon: gnome-session-reboot
  ifenveq: [DESKTOP_SESSION, GNOME]

ifcompositor

Shows the entry only inside a given Wayland compositor.

ifcompositor string or array

One of hyprland, niri or sway, or a list of them. Raffi tells them apart with HYPRLAND_INSTANCE_SIGNATURE, NIRI_SOCKET and SWAYSOCK.

Example: Compositor-Specific Entries

hypr-reload:
  binary: hyprctl
  args: [reload]
  description: "Reload Hyprland config"
  ifcompositor: hyprland

overview:
  binary: niri
  args: [msg, action, toggle-overview]
  description: "Overview"
  ifcompositor: niri

lock:
  binary: swaylock
  description: "Lock screen"
  ifcompositor: [niri, sway]

ifexist

Shows the entry only if a specific binary or file exists.

ifexist string

Binary name. Entry is shown only if the binary exists in PATH.

Example: Binary Existence

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

Shown only if wally is installed in PATH.

Example: Multiple Entries for Same App

evolution-mail:
  binary: jumpapp
  args: ["-t", "Evolution", "-X", "evolution"]
  description: "Evolution Mail"
  icon: evolution-mail
  ifexist: evolution

signal:
  binary: jumpapp
  args: ["-X", "signal", "signal-desktop"]
  description: "Signal"
  icon: signal-desktop
  ifexist: signal-desktop

Example: File Path Check

custom-app:
  binary: ~/bin/myapp
  description: "My Application"
  icon: myapp
  ifexist: ~/bin/myapp

Combining with Other Fields

Conditions work with all other entry fields:

Script with Condition

my-script:
  script: |
    echo "Running on Wayland"
    env | grep WAYLAND
  description: "Wayland Info"
  icon: "info"
  ifenvset: WAYLAND_DISPLAY

Disabled Entry with Condition

optional-tool:
  binary: special-tool
  description: "Special Tool"
  ifexist: special-tool
  disabled: true

Real-World Examples

From the example configuration:

Environment-Specific System Commands

# GNOME-specific shutdown
gnome-shutdown:
  binary: gnome-session-quit
  args: [--power-off]
  description: "Shutdown / Poweroff"
  icon: gnome-shutdown
  ifenveq: [DESKTOP_SESSION, GNOME]

# Sway-specific shutdown
shutdown:
  binary: poweroff
  description: "Shutdown / Poweroff"
  icon: gnome-shutdown
  ifenvset: SWAYSOCK

Session Type Detection

# X11-only entry
red-hat-mail:
  binary: xdo-focus-a-tab
  args: ["chromium", "Red Hat Mail", "https://mail.google.com/a/redhat.com"]
  description: "Red Hat GMail"
  icon: gmail
  ifenveq: [XDG_SESSION_TYPE, x11]

# Wayland-only entry
screenshot-clipboard:
  binary: sway-screenshot
  args: [selection-clipboard]
  description: "Screenshot to clipboard"
  icon: screenshoticon
  ifenvset: SWAYSOCK

Optional Tools

emoji-picker:
  binary: splatmoji
  args: [copy]
  description: "Emoji Picker"
  icon: emoji
  ifexist: splatmoji

bpytop:
  binary: kitty-ctrl
  args: ["jump", "bpytop"]
  description: "BpyTOP"
  icon: bashtop
  ifexist: bpytop

start-kind:
  binary: kitty-ctrl
  args: ["jump", "-t", "Kind", "startkind"]
  description: "Start Kind"
  icon: kind-started
  ifexist: kind

Validation Logic

Raffi evaluates conditions on startup:

ifenveq: Checks if variable exists and equals expected value
ifenvset: Checks if variable exists (any value)
ifenvnotset: Checks if variable does not exist
ifexist: Checks if binary is in PATH or file exists

If any condition fails, the entry is hidden.

Automatic Binary Check

Even without conditions, Raffi automatically hides entries if:

binary doesn’t exist in PATH (for non-script entries)
Script interpreter doesn’t exist in PATH (for script entries)

# Automatically hidden if firefox is not installed
firefox:
  binary: firefox
  description: "Firefox"
  icon: firefox

Multiple Conditions

An entry can have several conditions, and all of them must pass for it to show.

# Entry shown only on GNOME Wayland sessions
gnome-wayland-tool:
  binary: my-tool
  description: "Tool (GNOME on Wayland)"
  ifenveq: [DESKTOP_SESSION, GNOME]
  ifenvset: WAYLAND_DISPLAY