1bemenu(1) General Commands Manual bemenu(1)
2
6 bemenu - dynamic menu inspired by dmenu(1)
7
9 bemenu [-hCiKTvwx] [-I <index>] [-l <lines>] [-P <prefix>]
10 [-p <prompt>] [--ifne] [--scrollbar none|always|autohide] [--bind‐
11 ing vim] [--fork] [backend_options]
12 bemenu-run [-hCiKTvwx] [-I <index>] [-l <lines>] [-P <prefix>]
14 [-p <prompt>] [--ifne] [--scrollbar none|always|autohide] [--bind‐
15 ing vim] [--fork] [--no-exec] [backend-options]
16
18 bemenu is a dynamic menu for tty(4) (using ncurses(3)), X11 and Way‐
19 land, inspired by dmenu(1).
20 It reads a list of newline-separated items from standard input and then
22 presents them as a list, where the user can select one or more of them.
23 When pressing <carriage-return>, the selected items are printed to
24 standard output (one per line) and bemenu exits.
25 Entering text will filter the items to those that match the input. If
27 the number of items exceeds the size of the list, the items will be
28 paginated.
29 bemenu-run is a special-case invocation of bemenu, where the input is
31 the list of executables under PATH and the selected items are executed.
32
34 -h, --help
35 Print a help message to standard output and exit.
36 -C, --no-cursor
38 Disable all cursor events.
39 -I, --index <index>
41 Highlight the item at index at the start. Indices start at 0. By
42 default, the first item is highlighted.
43 -i, --ignorecase
45 Filter items case-insensitively.
46 -K, --no-keyboard
48 Disable all keyboard events.
49 -l, --list <number>
51 List items vertically with the given number of lines.
52 -P, --prefix <prefix>
54 Display prefix before the highlighted item in a vertical list.
55 -p, --prompt <prompt>
57 Defines the prompt text to be displayed to the left of the input
58 field. Defaults to ‘bemenu’.
59 -s, --no-spacing
61 Disable the title spacing on entries.
62 -T, --no-touch
64 Disable all touch events.
65 -v, --version
67 Print the bemenu version number to standard output and exit.
68 -w, --wrap
70 Advancing past the end of the list returns you to the start.
71 -x, --password
73 Hide filter text.
74 --fixed-height
76 Prevent the display from changing height on filter.
77 --accept-single
79 Immediately return if there is only one item.
80 --binding
82 Use alternative key bindings. Available options: vim
83 --fork
85 Always fork(2) before executing the selections. Disabled by default
86 when using the terminal backend.
87 --ifne
89 Only display menu if there are items.
90 --no-exec
92 Print the selected items to standard output instead of executing
93 them.
94 --scrollbar none|always|autohide
96 Specify when to show a scrollbar for vertical lists:
97 ┌─────────┬────────────────────────────────────────────────────────────┐
99 │none │ Never display a scrollbar (the default). │
100 ├─────────┼────────────────────────────────────────────────────────────┤
101 │always │ Always display a scrollbar. │
102 ├─────────┼────────────────────────────────────────────────────────────┤
103 │autohide │ Only display a scrollbar when the number of items exceeds │
104 │ │ the number of lines. │
105 └─────────┴────────────────────────────────────────────────────────────┘
106 -e, --vim-esc-exits
107 Exit bemenu when pressing escape in normal mode for vim bindings.
108 -F, --filter
110 Filter items for a given string before showing the menu. Affects
111 --ifne and --accept-single
112 Backend options
114 These options are only available on backends specified in the parenthe‐
115 ses:
116 -b, --bottom (Wayland, X11)
118 The list will appear at the bottom of the screen.
119 -c, --center (Wayland, X11)
121 The list will appear at the center of the screen. (wx)
122 -f, --grab (Wayland, X11)
124 Show the bemenu window whilst reading the items.
125 -B, --border (Wayland, X11)
127 Specify the width of the border in pixels around the menu.
128 --bdr (Wayland, X11)
130 Specify the border color.
131 -R, --border-radius (Wayland, X11)
133 Specify the radius of the border around the menu (0 = no curved
134 borders).
135 -H, --line-height <height> (Wayland, X11)
137 Specify the height in point size to make each entry.
138 --ch (Wayland, X11)
140 Specify the height of the cursor (0 = scales with line height).
141 --cw (Wayland, X11)
143 Specify the width of the cursor.
144 -m, --monitor <index> (Wayland, X11)
146 Specify the monitor index where the list should appear. Monitor in‐
147 dices start at zero. The interpretation of the given argument de‐
148 pends on the utilized backend. With X11 and Wayland, a value of
149 ‘-1’ or focused indicates that the current monitor should be used
150 (the default). With Wayland, the index should be a string specify‐
151 ing a specific monitor name. The value ‘-2’ or all indicates that
152 the list should appear on all monitors.
153 -n, --no-overlap (Wayland)
155 Set the bemenu window to be on top of any other panels.
156 -M, --margin <margin> (Wayland, X11)
158 Specify the margin (empty space) in pixels to leave between menu
159 and vertical view borders. bemenu will reduce it's size to fit in
160 space between gaps.
161 --hp (Wayland, X11)
163 Specify the horizontal padding for the entries in single line mode.
164 -W, --width-factor <factor> (Wayland, X11)
166 Specify the relative width factor as a floating point number. It
167 makes sense to set it between 0 and 1 to define how much of the
168 screen width bemenu will use. However, bemenu will still respect
169 margin, so if resulting size is greater than space between gaps,
170 bemenu will ignore factor and use available space instead.
171 --fn <name [size]> (Wayland, X11)
173 Specify the font family name and size to be used. For more options,
174 consult the Pango Reference Manual for pango_font_descrip‐
175 tion_from_string().
176 The following options control the colours for various parts of the list
178 for the Wayland and X11 backends. Each takes an argument in the form
179 of:
180 #RGB[A]
182 where R, G, B and A are hexadecimal integers from 00–FF that control
184 the red, green, blue and alpha-transparency channels.
185 --tb <color> Title background.
187 --tf <color> Title foreground.
189 --fb <color> Filter background.
191 --ff <color> Filter foreground
193 --cb <color> Cursor background.
195 --cf <color> Cursor foreground
197 --nb <color> Normal background.
199 --nf <color> Normal foreground.
201 --hb <color> Highlighted background.
203 --hf <color> Highlighted foreground.
205 --fbb <color> Feedback background.
207 --fbf <color> Feedback foreground.
209 --sb <color> Selected background.
211 --sf <color> Selected foreground.
213 --ab <color> Alternating background color.
215 --af <color> Alternating foreground color.
217 --scb <color> Scrollbar background.
219 --scf <color> Scrollbar foreground.
221
223 bemenu supports keyboard commands to move around the list and edit the
224 filter. In the following examples, C-x means <control-x>, M-x means
225 <alt-x> and S-x means <shift-x>:
226 <cursor-up>, S-<cursor-left>, C-p, M-j, M-l
228 Highlight the previous item.
229 <cursor-down>, <tab>, C-n, M-h, M-k
231 Highlight the next item.
232 PageUp, M-v, M-u
234 Show the previous page of items, preserving the offset of the cur‐
235 rently highlighted item, if possible.
236 PageDown, C-v, M-d
238 Show the next page of items, preserving the offset of the currently
239 highlighted item, if possible.
240 S-M-<, S-PageUp
242 Highlight the first item in the list.
243 S-M->, S-PageDown
245 Highlight the last item in the list.
246 S-<tab>
248 Copy the highlighted item to the filter.
249 <escape>, C-g
251 Terminate bemenu without printing items.
252 C-<carriage-return>, C-m
254 Print selected items and the currently highlighted one, and exit.
255 Items are printed in the order they were selected, with the cur‐
256 rently highlighted item printed last.
257 S-<carriage-return>, Insert
259 Print the filter text to standard output and exit.
260 C-l, <cursor-left>
262 Move cursor left.
263 C-f, <cursor-right>
265 Move cursor right.
266 C-a, Home
268 Move cursor to the start.
269 C-e, End
271 Move cursor to the end.
272 <backspace> C-h
274 Remove character before the cursor.
275 <delete>
277 Remove character at the cursor.
278 C-u, S-<delete>
280 Remove all characters before the cursor.
281 C-k
283 Remove all characters after the cursor.
284 C-w
286 Clear the filter.
287 C-y
289 Paste the clipboard.
290 M-[1-9]
292 Print selected items and exit with a custom error code 10 (M-1)
293 through 18 (M-9), see EXIT STATUS.
294 M-0
296 Print selected items and exit with the custom error code 19, see
297 EXIT STATUS.
298
300 ┌─────────────────┬────────────────────────────────────────────────────┐
301 │BEMENU_OPTS │ An alternative way to pass command line arguments │
302 │ │ to bemenu. │
303 ├─────────────────┼────────────────────────────────────────────────────┤
304 │BEMENU_BACKEND │ Force a backend to be used. If empty, one of the │
305 │ │ GUI backends (Wayland, X11) will be selected auto‐ │
306 │ │ matically. The accepted values are curses, wayland │
307 │ │ and x11. │
308 ├─────────────────┼────────────────────────────────────────────────────┤
309 │BEMENU_RENDERER │ Force a backend by loading its shared object from │
310 │ │ the set value. │
311 ├─────────────────┼────────────────────────────────────────────────────┤
312 │BEMENU_RENDERERS │ Override the backend search path to the set value. │
313 │ │ Defaults to /usr/lib64/bemenu. │
314 ├─────────────────┼────────────────────────────────────────────────────┤
315 │BEMENU_SCALE │ Override the rendering scale factor for the GUI │
316 │ │ backends. │
317 └─────────────────┴────────────────────────────────────────────────────┘
318
320 0
321 bemenu ran successfully.
322 1
324 The user exited without selecting, or bemenu encountered an error.
325 10-19
327 The user specified a custom exit code with M-[0-9], see KEYBOARD
328 COMMANDS.
329
331 dmenu(1), fork(2), ncurses(3), tty(4)
332 Pango Reference Manual, https://developer.gnome.org/pango/1.46/, August
334 20, 2020, Fonts — pango_font_description_from_string().
335
337 bemenu is written and maintained by Jari Vetoniemi <mail‐
338 roxas@gmail.com> with the help of various contributors.
339 2023-09-04 bemenu(1)