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

Passing mode options

82       Extra  options, like setting the prompt, can be set by the script.  Ex‐
83       tra options are lines that start with a NULL character (\0) followed by
84       a key, separator (\x1f) and value.
85
86
87       For example to set the prompt:
88
89
90                  echo -en "\0prompt\x1fChange prompt\n"
91
92
93
94       The following extra options exists:
95
96
97              • prompt:      Update the prompt text.
98
99              • message:     Update the message text.
100
101              • markup-rows: If 'true' renders markup in the row.
102
103              • urgent:       Mark  rows as urgent. (for syntax see the urgent
104                option in dmenu mode)
105
106              • active:      Mark rows as active. (for syntax see  the  active
107                option in dmenu mode)
108
109              • delim:        Set  the delimiter for for next rows. Default is
110                '\n' and this option should finish with this. Only  call  this
111                on  first  call  of  script,  it is remembered for consecutive
112                calls.
113
114              • no-custom:   If set to 'true'; only accept listed entries, ig‐
115                nore custom input.
116
117              • use-hot-keys:  If  set to true, it enabled the Custom keybind‐
118                ings for script. Warning this breaks the normal rofi flow.
119
120
121

Parsing row options

123       Extra options for individual rows can be set.  The extra option can  be
124       specified  following  the same syntax as mode option, but following the
125       entry.
126
127
128       For example:
129
130
131                  echo -en "aap\0icon\x1ffolder\n"
132
133
134
135       The following options are supported:
136
137
138              • icon: Set the icon for that row.
139
140              • meta: Specify invisible search terms.
141
142              • nonselectable: If true the row cannot activated.
143
144              • info: Info that, on selection, gets placed  in  the  ROFI_INFO
145                environment variable. This entry does not get searched.
146
147
148
149       multiple entries can be passed using the \x1f separator.
150
151
152                  echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"
153
154
155

Executing external program

157       If  you want to launch an external program from the script, you need to
158       make sure it is launched in the background.  If not rofi will wait  for
159       its output (to display).
160
161
162       In bash the best way to do this is using coproc.
163
164
165               coproc ( myApp  > /dev/null  2>1 )
166
167
168

DASH shell

170       If  you  use the dash shell for your script, take special care with how
171       dash handles escaped values for the separators.   See  issue  #1201  on
172       github.
173
174

AUTHOR

181       Qball Cow ⟨qball@gmpclient.org⟩
182
183
184       Rasmus Steinke ⟨rasi@xssn.at⟩
185
186
187       Quentin Glidic ⟨sardemff7+rofi@sardemff7.net⟩
188
189
190       Original code based on work by: Sean Pringle ⟨sean.pringle@gmail.com⟩
191
192
193       For a full list of authors, check the AUTHORS file.
194
195
196
197                                  rofi-script                   ROFI-SCRIPT(5)