rofi-docs

docs.md

---

Title: How to write modi scripts ...

rofi can call a script as a modi. To do this your script must do the following:

1. The last argument of the script is reserved for rofi. It must be allowed to be omitted.
2. When the mode is first activated, the script is called with that argument omitted. At this point, the script should print a newline-separated list of entries to stdout which rofi would then slurp and display to the user.
3. The option that the user submits will then be supplied as the argument, which would handle the argument normally.
4. This will continue as long as the script continues to print text to stdout, which is useful if you want to provide followup prompts. If no text has been written to stdout, then rofi exits.

Example

Consider a script that, if given an argument, would print all the numbers from 0 to the argument. If the argument is omitted, 5 is assumed; if 0 is supplied, then no numbers are outputted. It might look like this:

#!/bin/zsh

arg=${1-5}
if [[ $arg == 0 ]]; then
    exit 0
fi

for i in {0..$arg}; do
    print $i
done

Now save it as example.sh, allow it to be executed, and in the same directory run:

rofi -show test -modi test:example.sh

rofi would show up with a list of numbers from 0 to 5, because example.sh outputs a list of numbers from 0 to 5.

If we select 3 and press RET, the list would change to only display numbers from 0 to 3, because example.sh 3 outputs

0
1
2
3

If we input 25 and press RET, example.sh would receive an argument of 25 and therefore output a list of numbers from 0 to 25.

Finally if we select 0 and press RET, then example.sh would output any text at all. Because there's no output from the script, rofi exits.

What a script can do

• Be activated along with the built-in mode and other scripts (e.g. via rofi -modi run,ssh,baz:baz-script)
• Be combined with other modes using combi-modi
• Provide a prompt string, which is its name

What a script cannot do

• Mark lines as urgent or active
• Provide a message (as in rofi -dmenu -mesg <string>)
• Have a prompt that's different from the mode name