rofi-script(5)

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

NAME

6       rofi script mode - Rofi format for scriptable mode.
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 -modes "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  se‐
54       lected, 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
65              • 0: Initial call of script.
66
67              • 1: Selected an entry.
68
69              • 2: Selected a custom entry.
70
71              • 10-28:  Custom keybinding 1-19 ( need to be explicitly enabled
72                by script ).
73
74
75
76   ROFI_INFO
77       Environment get set when selected entry get set with the property value
78       of the 'info' row option, if set.
79
80
81   ROFI_DATA
82       Environment get set when script sets data option in header.
83
84

Passing mode options

86       Extra  options, like setting the prompt, can be set by the script.  Ex‐
87       tra options are lines that start with a NULL character (\0) followed by
88       a key, separator (\x1f) and value.
89
90
91       For example to set the prompt:
92
93
94                  echo -en "\0prompt\x1fChange prompt\n"
95
96
97
98       The following extra options exists:
99
100
101              • prompt:      Update the prompt text.
102
103              • message:     Update the message text.
104
105              • markup-rows: If 'true' renders markup in the row.
106
107              • urgent:       Mark  rows as urgent. (for syntax see the urgent
108                option in dmenu mode)
109
110              • active:      Mark rows as active. (for syntax see  the  active
111                option in dmenu mode)
112
113              • delim:        Set  the delimiter for for next rows. Default is
114                '\n' and this option should finish with this. Only  call  this
115                on  first  call  of  script,  it is remembered for consecutive
116                calls.
117
118              • no-custom:   If set to 'true'; only accept listed entries, ig‐
119                nore custom input.
120
121              • use-hot-keys:  If  set to true, it enabled the Custom keybind‐
122                ings for script. Warning this breaks the normal rofi flow.
123
124              • keep-selection: If set, the selection  is  not  moved  to  the
125                first  entry, but the current position is maintained. The fil‐
126                ter is cleared.
127
128              • new-selection: If keep-selection is set, this  allows  you  to
129                override the selected entry (absolute position).
130
131              • data:          Passed data to the next execution of the script
132                via ROFI_DATA.
133
134              • theme:       Small theme snippet to f.e. change the background
135                color of a widget.
136
137
138

Parsing row options

140       Extra  options for individual rows can be set.  The extra option can be
141       specified following the same syntax as mode option, but  following  the
142       entry.
143
144
145       For example:
146
147
148                  echo -en "aap\0icon\x1ffolder\n"
149
150
151
152       The following options are supported:
153
154
155              • icon: Set the icon for that row.
156
157              • meta: Specify invisible search terms.
158
159              • nonselectable: If true the row cannot activated.
160
161              • info:  Info  that,  on selection, gets placed in the ROFI_INFO
162                environment variable. This entry does not get searched.
163
164
165
166       multiple entries can be passed using the \x1f separator.
167
168
169                  echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"
170
171
172

Executing external program

174       If you want to launch an external program from the script, you need  to
175       make  sure it is launched in the background.  If not rofi will wait for
176       its output (to display).
177
178
179       In bash the best way to do this is using coproc.
180
181
182               coproc ( myApp  > /dev/null  2>&1 )
183
184
185

DASH shell

187       If you use the dash shell for your script, take special care  with  how
188       dash  handles  escaped  values  for the separators.  See issue #1201 on
189       github.
190
191

AUTHOR

198       Qball Cow qball@gmpclient.org ⟨mailto:qball@gmpclient.org⟩
199
200
201       Rasmus Steinke rasi@xssn.at ⟨mailto:rasi@xssn.at⟩
202
203
204       Morgane               Glidic               sardemff7+rofi@sardemff7.net
205       ⟨mailto:sardemff7+rofi@sardemff7.net⟩
206
207
208       Original code based on work  by:  Sean  Pringle  sean.pringle@gmail.com
209       ⟨mailto:sean.pringle@gmail.com⟩
210
211
212       For a full list of authors, check the AUTHORS file.
213
214
215
216                                  rofi-script                   ROFI-SCRIPT(5)