rofi-script(5)

1ROFI-SCRIPT(5)                File Formats Manual               ROFI-SCRIPT(5)
2
3
4

NAME

6       rofi script mode - Rofi format for scriptable modi.
7
8

DESCRIPTION

10       rofi supports modes that use simple scripts in the background to gener‐
11       ate a list and process the result from user actions.   This  provide  a
12       simple interface to make simple extensions to rofi.
13
14

USAGE

16       To  specify  a  script  mode,  set  a  mode  with the following syntax:
17       "{name}:{executable}"
18
19
20       For example:
21
22
23              rofi -show fb -modi "fb:file_browser.sh"
24
25
26
27       The name should be unique.
28
29

API

31       Rofi calls the executable without arguments on  startup.   This  should
32       generate  a  list  of options, separated by a newline (\n) (This can be
33       changed by the script).  If the user selects an option, rofi calls  the
34       executable  with the text of that option as the first argument.  If the
35       script returns no entries, rofi quits.
36
37
38       A simple script would be:
39
40
41              #!/usr/bin/env bash
42
43              if [ x"$@" = x"quit" ]
44              then
45                  exit 0
46              fi
47              echo "reload"
48              echo "quit"
49
50
51
52
53       This shows two entries,  reload  and  quit.  When  the  quit  entry  is
54       selected, rofi closes.
55
56

Environment

58       Rofi sets the following environment variable when executing the script:
59
60
61   ROFI_RETV
62       An integer number with the current state:
63
64       · 0: Initial call of script.
65
66       · 1: Selected an entry.
67
68       · 2: Selected a custom entry.
69
70       · 10-28: Custom keybinding 1-19
71
72
73   ROFI_INFO
74       Environment get set when selected entry get set with the property value
75       of the 'info' row option, if set.
76
77

Passing mode options

79       Extra options, like setting the prompt,  can  be  set  by  the  script.
80       Extra  options are lines that start with a NULL character (\0) followed
81       by a key, separator (\x1f) and value.
82
83
84       For example to set the prompt:
85
86
87                  echo -en "\0prompt\x1fChange prompt\n"
88
89
90
91       The following extra options exists:
92
93       · prompt:      Update the prompt text.
94
95       · message:     Update the message text.
96
97       · markup-rows: If 'true' renders markup in the row.
98
99       · urgent:      Mark rows as urgent. (for syntax see the  urgent  option
100         in dmenu mode)
101
102       · active:       Mark  rows as active. (for syntax see the active option
103         in dmenu mode)
104
105       · delim:       Set the delimiter for for next rows. Default is '\n' and
106         this  option should finish with this. Only call this on first call of
107         script, it is remembered for consecutive calls.
108
109       · no-custom:   Only accept listed entries, ignore custom input.
110
111

Parsing row options

113       Extra options for individual rows can be set.  The extra option can  be
114       specified  following  the same syntax as mode option, but following the
115       entry.
116
117
118       For example:
119
120
121                  echo -en "aap\0icon\x1ffolder\n"
122
123
124
125       The following options are supported:
126
127       · icon: Set the icon for that row.
128
129       · meta: Specify invisible search terms.
130
131       · nonselectable: If true the row cannot activated.
132
133       · info: Info that, on selection, gets placed in the ROFI_INFO  environ‐
134         ment variable. This entry does not get searched.
135
136
137       multiple entries can be passed using the \x1f separator.
138
139
140                  echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"
141
142
143

DASH shell

145       If  you  use the dash shell for your script, take special care with how
146       dash handles escaped values for the separators.   See  issue  #1201  on
147       github.
148
149

AUTHOR

156       Qball Cow ⟨qball@gmpclient.org⟩
157
158
159       Rasmus Steinke ⟨rasi@xssn.at⟩
160
161
162       Quentin Glidic ⟨sardemff7+rofi@sardemff7.net⟩
163
164
165       Original code based on work by: Sean Pringle ⟨sean.pringle@gmail.com⟩
166
167
168       For a full list of authors, check the AUTHORS file.
169
170
171
172                                  rofi-script                   ROFI-SCRIPT(5)