bemenu(1)

🎀 NAME 🎀

bemenu — dynamic menu inspired by dmenu(1). Bestie, this is the bemenu(1) page from the General Commands Manual, and it’s literally the main character of dynamic menus. 💅

---

✨ SYNOPSIS ✨

bemenu [-hCiKTvwx] [-I <index>] [-l <lines>] [-P <prefix>]
    [-p <prompt>] [--ifne] [--scrollbar none|always|autohide] [--binding
    vim] [--fork] [backend_options]

bemenu-run [-hCiKTvwx] [-I <index>] [-l <lines>] [-P <prefix>]
    [-p <prompt>] [--ifne] [--scrollbar none|always|autohide] [--binding
    vim] [--fork] [--no-exec] [backend-options]

---

💖 DESCRIPTION 💖

bemenu is a dynamic menu for tty(4) (using ncurses(3)), X11 and Wayland, inspired by dmenu(1). It’s giving “picker but make it fashion,” and honestly? Obsessed. 🦋

It reads a list of newline-separated items from standard input and then presents them as a list, where you can select one or more of them. When you press carriage-return, the selected items are printed to standard output (one per line) and bemenu exits. Slay. ✨

Entering text will filter the items to those that match the input. If the number of items exceeds the size of the list, the items will be paginated. No cap, it just keeps things tidy. 🎀

bemenu-run is a special-case invocation of bemenu, where the input is the list of executables under PATH and the selected items are executed. It’s the “run it, bestie” mode. 🔥

---

💅 OPTIONS 💅

Okay so here’s the full options lineup — every flag, every value, no skipping. Iykyk. 🌸

• -h, --help — print a help message to standard output and exit.
• -C, --no-cursor — disable all cursor events.
• -I, --index <index> — highlight the item at index at the start. Indices start at 0. By default, the first item is highlighted.
• -i, --ignorecase — filter items case-insensitively.
• -K, --no-keyboard — disable all keyboard events.
• -l, --list "<number> down|up" — list items vertically down or up with the given number of lines.
• -P, --prefix <prefix> — display prefix before the highlighted item in a vertical list.
• -p, --prompt <prompt> — defines the prompt text to be displayed to the left of the input field. Defaults to bemenu.
• -s, --no-spacing — disable the title spacing on entries.
• -T, --no-touch — disable all touch events.
• -v, --version — print the bemenu version number to standard output and exit.
• -w, --wrap — advancing past the end of the list returns you to the start.
• -x, --password none|hide|indicator — specify how the filter text should be displayed:
  • none — display the input (the default).
  • hide — do not display any input.
  • indicator — replace input with asterisks.
• --fixed-height — prevent the display from changing height on filter.
• --accept-single — immediately return if there is only one item.
• --auto-select — when one entry is left, automatically select it.
• --binding — use alternative key bindings. Available options: vim
• --fork — always fork(2) before executing the selections. Disabled by default when using the terminal backend.
• --ifne — only display menu if there are items.
• --single-instance — force a single menu instance.
• --no-exec — print the selected items to standard output instead of executing them.
• --scrollbar none|always|autohide — specify when to show a scrollbar for vertical lists:
  • none — never display a scrollbar (the default).
  • always — always display a scrollbar.
  • autohide — only display a scrollbar when the number of items exceeds the number of lines.
• -e, --vim-esc-exits — exit bemenu when pressing escape in normal mode for vim bindings.
• -N, --vim-normal-mode — start in normal mode for vim bindings.
• -F, --filter — filter items for a given string before showing the menu. Affects --ifne and --accept-single

🛠️ Backend options 🛠️

Heads up bestie: these options are only available on backends specified in the parentheses. 💀

• -b, --bottom — (Wayland, X11) the list will appear at the bottom of the screen.
• -c, --center — (Wayland, X11) the list will appear at the center of the screen. (wx)
• -f, --grab — (Wayland, X11) show the bemenu window whilst reading the items.
• -B, --border — (Wayland, X11) specify the width of the border in pixels around the menu.
• --bdr — (Wayland, X11) specify the border color.
• -R, --border-radius — (Wayland, X11) specify the radius of the border around the menu (0 = no curved borders).
• -H, --line-height <height> — (Wayland, X11) specify the height in point size to make each entry.
• --ch — (Wayland, X11) specify the height of the cursor (0 = scales with line height).
• --cw — (Wayland, X11) specify the width of the cursor.
• -m, --monitor <index> — (Wayland, X11) specify the monitor index where the list should appear. Monitor indices start at zero. The interpretation of the given argument depends on the utilized backend. With X11 and Wayland, a value of -1 or focused indicates that the current monitor should be used (the default). With Wayland, the index should be a string specifying a specific monitor name. The value -2 or all indicates that the list should appear on all monitors.
• -n, --no-overlap — (Wayland) set the bemenu window to be on top of any other panels.
• -M, --margin <margin> — (Wayland, X11) specify the margin (empty space) in pixels to leave between menu and vertical view borders. bemenu will reduce its size to fit in space between gaps.
• --hp — (Wayland, X11) specify the horizontal padding for the entries in single line mode.
• -W, --width-factor <factor> — (Wayland, X11) specify the relative width factor as a floating point number. It makes sense to set it between 0 and 1 to define how much of the screen width bemenu will use. However, bemenu will still respect margin, so if resulting size is greater than space between gaps, bemenu will ignore factor and use available space instead.
• --fn <name [size]> — (Wayland, X11) specify the font family name and size to be used. For more options, consult the Pango Reference Manual for pango_font_description_from_string().

The following options control the colours for various parts of the list for the Wayland and X11 backends. Each takes an argument in the form of #RGB[A], where R, G, B and A are hexadecimal integers from 00–FF that control the red, green, blue and alpha-transparency channels. 🌈

• --tb <color> — title background.
• --tf <color> — title foreground.
• --fb <color> — filter background.
• --ff <color> — filter foreground.
• --cb <color> — cursor background.
• --cf <color> — cursor foreground.
• --nb <color> — normal background.
• --nf <color> — normal foreground.
• --hb <color> — highlighted background.
• --hf <color> — highlighted foreground.
• --fbb <color> — feedback background.
• --fbf <color> — feedback foreground.
• --sb <color> — selected background.
• --sf <color> — selected foreground.
• --ab <color> — alternating background color.
• --af <color> — alternating foreground color.
• --scb <color> — scrollbar background.
• --scf <color> — scrollbar foreground.

⌨️ KEYBOARD COMMANDS ⌨️

okay so bemenu is fully keyboard-driven and honestly that's the vibe 💅 — you've got commands to scoot around the list and to edit your filter. quick legend before we go, because the notation is a whole thing: C-x means Ctrl+x, M-x means Alt+x, and S-x means Shift+x. periodt. ✨

• <cursor-up>, S-<cursor-left>, C-p, M-j, M-l — highlight the previous item, slay ⬆️
• <cursor-down>, <tab>, C-n, M-h, M-k — highlight the next item, keep it moving ⬇️
• PageUp, M-v, M-u — show the previous page of items, and it preserves the offset of the currently highlighted item if possible (keyword: if possible, bestie, don't come for me) 🦋
• PageDown, C-v, M-d — show the next page of items, same deal — offset of the currently highlighted item preserved if possible 🦋
• S-M-<, S-PageUp — highlight the first item in the list, back to the top we go 👑
• S-M->, S-PageDown — highlight the last item in the list, bottom of the barrel bestie 🔥
• S-<tab> — copy the highlighted item into the filter. literally so useful 😭
• <escape>, C-g — terminate bemenu without printing items. we're leaving, no receipts 💀
• C-<carriage-return>, C-m — print the selected items and the currently highlighted one, then exit. items print in the order they were selected, with the currently highlighted item printed last 🎀
• S-<carriage-return>, Insert — print the filter text to standard output and exit ✨
• C-b, C-l, <cursor-left> — move cursor left
• C-f, <cursor-right> — move cursor right
• C-a, Home — move cursor to the start
• C-e, End — move cursor to the end
• <backspace>, C-h — remove the character before the cursor
• <delete> — remove the character at the cursor
• C-u, S-<delete> — remove all characters before the cursor
• C-k — remove all characters after the cursor
• C-w — clear the filter, fresh start energy 🌸
• C-y, C-Y — paste selection (C-y for "primary", C-Y for "clipboard"). yes those are different, no you may not mix them up 🫶
• M-[1-9] — print selected items and exit with a custom error code 10 (M-1) through 18 (M-9), see EXIT STATUS. custom codes, main character behaviour 💅
• M-0 — print selected items and exit with the custom error code 19, see EXIT STATUS

🌈 Vim bindings 🌈

so if you invoke bemenu with --binding vim, you get vim-like modal entry — these bindings roughly emulate insert and normal vim modes. the initial mode is insert mode, unless --vim-normal-mode is specified. iykyk 🧚

insert mode

in insert mode, all the keys up top function exactly as described above, except for this one:

• <escape> — switch to normal mode. welcome to normal mode bestie 🌸

normal mode

in normal mode, only the following keys have meaning. everything else? crickets. 🙈

• q — terminate bemenu without printing items
• i — enter insert mode
• I — enter insert mode after moving the cursor to the start
• a — enter insert mode after moving the cursor right
• A — enter insert mode after moving the cursor to the end
• cc — enter insert mode after clearing the filter
• cw — enter insert mode after removing all characters between the cursor and the start of the next word
• cb — enter insert mode after removing all characters between the start of the word and the cursor
• c$ — enter insert mode after removing all characters after the cursor
• c0 — enter insert mode after removing all characters before the cursor
• n, j — highlight the next item
• p, k — highlight the previous item
• gg — highlight the first item in the list
• G — highlight the last item in the list
• H — highlight the first visible item
• M — highlight the middle-most visible item
• L — highlight the last visible item
• v — select or deselect the highlighted item
• F — show the next page of items
• B — show the previous page of items
• h — move cursor left
• l — move cursor right
• 0 — move cursor to the start
• $ — move cursor to the end
• w — move cursor forward to the start of a word
• b — move cursor backward to the start of a word
• e — move cursor forward to the end of a word
• x — remove the character at the cursor
• X — remove the character before the cursor
• dw — remove all characters between the cursor and the start of the next word
• db — remove all characters between the start of the word and the cursor
• d$ — remove all characters after the cursor
• d0 — remove all characters before the cursor
• dd — clear the filter

---

🌱 ENVIRONMENT 🌱

env vars, bestie, the little knobs that change everything 🎀 (the original put these in a cute little box, we're doing bullets because bullets ate):

• BEMENU_OPTS — an alternative way to pass command line arguments to bemenu. sneaky and iconic ✨
• BEMENU_BACKEND — force a backend to be used. if empty, one of the GUI backends (Wayland, X11) will be selected automatically. the accepted values are curses, wayland and x11.
• BEMENU_RENDERER — force a backend by loading its shared object from the set value 👑
• BEMENU_RENDERERS — override the backend search path to the set value. defaults to /usr/lib64/bemenu. no cap, that's the path 🦋
• BEMENU_SCALE — override the rendering scale factor for the GUI backends. make it big, make it small, it's giving control 💅

---

💀 EXIT STATUS 💀

• 0 — bemenu ran successfully. we love a happy ending 💖
• 1 — the user exited without selecting, or bemenu encountered an error. two very different moods, same number 😭
• 10-19 — the user specified a custom exit code with M-[0-9], see KEYBOARD COMMANDS. yes you can pick your own number, diva behaviour 🔥

---

🫶 SEE ALSO 🫶

• dmenu(1)
• fork(2)
• ncurses(3)
• tty(4)

also the Pango Reference Manual, https://developer.gnome.org/pango/1.46/, August 20, 2020, Fonts — pango_font_description_from_string(). go read it, it's right there 🌈

---

👑 AUTHORS 👑

bemenu is written and maintained by Jari Vetoniemi <mailroxas@gmail.com> with the help of various contributors. absolute icons, all of them 🎀

---

and that's the page!! 🦋 this build is the 2024-07-19 version of bemenu(1) — go forth and pick your items, bestie, mwah 💜