rofi-script(5)

✨ rofi-script ✨ (manual page 5, bestie)

Okay so this page is literally all about rofi script mode — the Rofi format for making your own scriptable modes. It's giving "DIY rofi extensions" energy and I'm obsessed. 💖

---

🌸 NAME 🌸

rofi script mode — Rofi format for scriptable mode, but make it ✨extensions✨.

🦋 SYNOPSIS 🦋

rofi -show {name} -modes "{name}:{executable}"

💜 DESCRIPTION 💜

rofi supports modes that use simple scripts running in the background to generate a list and then process whatever the user picks. It's a whole low-key simple interface so you can make your own little extensions to rofi. No cap. 🫶

🎀 USAGE 🎀

To specify a script mode, set a mode using this exact syntax:

"{name}:{executable}"

For example:

rofi -show fb -modes "fb:file_browser.sh"

And bestie, the name should be unique. Don't be out here reusing names like it's a group chat with three Alexes. 💅

✨ API ✨

So here's the tea: rofi calls the executable with no arguments on startup. The script should generate a list of options separated by a newline (\n) — and yes, this can be changed by the script itself, slay. If the user selects an option, rofi calls the executable with the text of that option as the first argument. And if the script returns no entries, rofi just quits. Iconic behavior. 😭

A simple script would be:

#!/usr/bin/env bash

if [ x"$@" = x"quit" ]
then
    exit 0
fi
echo "reload"
echo "quit"

This shows two entries: reload and quit. When the quit entry is selected, rofi closes. Periodt. 🌈

🧚 Environment 🧚

Rofi sets the following environment variable when executing the script:

💖 ROFI_RETV 💖

An integer number with the current state:

• 0: Initial call of script.
• 1: Selected an entry.
• 2: Selected a custom entry.
• 3: Deleted an entry.
• 10-28: Custom keybinding 1-19 (need to be explicitly enabled by script).

🦋 ROFI_INFO 🦋

Environment get set when selected entry get set with the property value of the info row option, if set.

🍓 ROFI_DATA 🍓

Environment get set when script sets data option in header.

🌟 Passing mode options 🌟

Extra options — like setting the prompt — can be set by the script. These extra options are lines that start with a NULL character (\0) followed by a key, separator (\x1f) and value.

For example, to set the prompt:

echo -en "\0prompt\x1fChange prompt\n"

The following extra options exist (and yes, I'm listing every single one because we don't skip):

• prompt — Update the prompt text.
• message — Update the message text.
• markup-rows — If true, renders markup in the row.
• urgent — Mark rows as urgent. (for syntax see the urgent option in dmenu mode)
• active — Mark rows as active. (for syntax see the active option in dmenu mode)
• delim — Set the delimiter for for next rows. Default is `` and this option should finish with this. Only call this on first call of script, it is remembered for consecutive calls.
• no-custom — If set to true; only accept listed entries, ignore custom input.
• use-hot-keys — If set to true, it enabled the Custom keybindings for script. Warning this breaks the normal rofi flow.
• keep-selection — If set, the selection is not moved to the first entry, but the current position is maintained. The filter is cleared.
• keep-filter — If set, the filter is not cleared.
• new-selection — If keep-selection is set, this allows you to override the selected entry (absolute position).
• data — Passed data to the next execution of the script via ROFI_DATA.
• theme — Small theme snippet to f.e. change the background color of a widget.

💀 The theme property cannot change the interface while running, it is only usable for small changes in, for example background color, of widgets that get updated during display like the row color of the listview. So don't come for rofi when your mid-run theme swap doesn't hit. 🙈

🎀 Parsing row options 🎀

Extra options for individual rows can be set too! The extra option can be specified following the same syntax as mode option, but following the entry.

For example:

echo -en "aap\0icon\x1ffolder\n"

The following options are supported:

• icon — Set the icon for that row.
• display — Replace the displayed string. (Original string will still be used for filtering)
• meta — Specify invisible search terms used for filtering.
• nonselectable — If true the row cannot activated.
• permanent — If true the row always shows, independent of filter.
• info — Info that, on selection, gets placed in the ROFI_INFO environment variable. This entry does not get searched for filtering.
• urgent — Set urgent flag on entry (true/false)
• active — Set active flag on entry (true/false)

Multiple entries can be passed using the \x1f separator:

echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"

👑 Executing external program 👑

If you want to launch an external program from the script, you need to make sure it is launched in the background. If not, rofi will wait for its output (to display). And nobody has time for that. 😴

In bash the best way to do this is using coproc:

coproc ( myApp  > /dev/null  2>&1 )

🌈 DASH shell 🌈

If you use the dash shell for your script, take special care with how dash handles escaped values for the separators. See issue #1201 on github. It's giving "read the fine print bestie" energy. 📖

⭐ Script locations ⭐

To specify a script there are the following options:

• Specify an absolute path to the script.
• The script is executable and located in your $PATH

Scripts located in the following location are loaded on startup and can be directly launched based on the filename (without extension):

• The script is in $XDG_CONFIG_HOME/rofi/scripts/, this is usually ~/.config/rofi/scripts/.

If you have a script mymode.sh in this folder you can open it using:

rofi -show mymode

See rofi -h output for a list of detected scripts. Slay. 💅

💜 SEE ALSO 💜

rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-theme-selector(1)

🌟 AUTHOR 🌟

• Qball Cow <qball@gmpclient.org>
• Rasmus Steinke <rasi@xssn.at>
• Morgane Glidic <sardemff7+rofi@sardemff7.net>
• Original code based on work by: Sean Pringle <sean.pringle@gmail.com>

For a full list of authors, check the AUTHORS file.

---

And that's the whole vibe check, bestie. This iconic page is brought to you by rofi 💖 — the manual page rofi-script(5) — and honestly, the date is just whenever you're reading this, but the version is giving "current release" energy. Stay slay, keep scripting, and don't forget the \0 separator. 😘💅✨