rofi-script - Man Page

Rofi format for scriptable mode.


rofi supports modes that use simple scripts in the background to generate a list and process the result from user actions.  This provide a simple interface to make simple extensions to rofi.


To specify a script mode, set a mode with the following syntax: "{name}:{executable}"

For example:

rofi -show fb -modes ""

The name should be unique.


Rofi calls the executable without arguments on startup.  This should generate a list of options, separated by a newline (\n) (This can be changed by the script). If the user selects an option, rofi calls the executable with the text of that option as the first argument. If the script returns no entries, rofi quits.

A simple script would be:

#!/usr/bin/env bash

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

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


Rofi sets the following environment variable when executing the script:


An integer number with the current state:

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


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


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. 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 exists:

Parsing row options

Extra options for individual rows can be set. 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:

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).

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.

See Also

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


Qball Cow ⟨⟩

Rasmus Steinke ⟨⟩

Morgane Glidic ⟨⟩

Original code based on work by: Sean Pringle ⟨⟩

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

Referenced By

rofi(1), rofi-debugging(5), rofi-dmenu(5), rofi-keys(5), rofi-theme(5).