instantMENU is a simple menu for instantOS it is used for instantASSIST and in some other places
git clone https://github.com/instantOS/instantMENU
cd instantMENU
cargo build --locked
# Or install the debug build and helper scripts for your user:
just installRelease archives, Arch Linux packages, and Debian packages are also attached to each GitHub release.
The version-bump workflow opens a release/version-bump pull request using
conventional commits to choose the next version. Merging that PR creates the
matching v* tag and publishes the release artifacts. A patch, minor, or major
bump can also be selected manually from the workflow dispatch form.
- alt-tab switcher mode: cycle with Alt+Tab, release Alt to pick
(
--alt-tab) - mouse support
- animations and hover over indicators
- composable item metadata for icons, colors, headings, hidden match terms, and single-key menus
- slider mode (
instantmenu slide 'brightnessctl s') - streamed input: the menu opens instantly and items appear as stdin produces them
- Catppuccin, classic and Gruvbox themes (
--theme)
instantmenu reads one optional file: $XDG_CONFIG_HOME/instantmenu/config.toml,
or ~/.config/instantmenu/config.toml when XDG_CONFIG_HOME is unset. Use
--config PATH to require another file, or --no-config to skip configuration.
The file is deliberately limited to font and colors:
font = "Iosevka:size=13"
theme = "gruvbox" # catppuccin (default), classic, or gruvbox
[colors.normal]
foreground = "#EBDBB2"
background = "#282828"
detail = "#504945"
[colors.selected]
foreground = "#282828"
background = "#83A598"
detail = "#8EC07C"Every scheme is named: normal, fade, highlight, hover, selected,
output, green, yellow, and red; each accepts foreground, background,
and detail. Unknown keys and invalid colors are errors. A configured theme is
applied first, then configured colors, then command-line --theme and color
overrides.
instantMENU started as a fork of dmenu and keeps the dmenu workflow (items on stdin,
selection on stdout, full keyboard control), with all extra features optional. The
command line uses modern long options (--width, --right-command, ...) with a few
single-letter shortcuts (-i, -p, -l, ...) instead of dmenu's historical flags.
For agent guidance on scripting and item markup, run instantmenu skill
(also available as instantmenu --skill). It prints a self-contained Markdown
skill without opening a display.
Each input line is normally its visible label and selected output. A leading attribute block adds metadata without becoming part of either:
Display
{blue icon=display match="monitor screen"} Display
{heading green} System actions
{red icon=power key=q} Power off
Known color names may be bare ({red}) or explicit ({color=red}). Other
attributes are icon, key, shortcut, match, value, and the heading flag. Quote values
that contain spaces. Run with --single-key to show and activate only entries
that have key=…. Prefix a literal markup-like label with an extra opening
brace: {{red} literal displays {red} literal. Use value to set a
different output from the display label: {value="file:/tmp/a b"} My File displays
My File but prints file:/tmp/a b.
All item activation paths use that same output value: Enter, mouse clicks,
numbered shortcuts, Alt release, single-key activation, auto-confirm, and bound
commands. For example, {key=h value=sh} Help displays Help in a single-key
menu but outputs sh. Ctrl-Enter/Ctrl-click accept without closing. Shift-Return
explicitly submits the input text instead (unless --reject-no-match is set);
Shift-click still accepts the clicked item. Tab completion and hover prompts
continue to use display labels.
Use shortcut=… in a regular menu to activate an entry directly while keeping
its full label visible. Hints align to the right of each entry with a left separator,
using symbols for Ctrl (⌃), Alt (⎇), Shift (⇧), and Super (⊞):
instantmenu -l 5 <<'MENU'
{icon=folder shortcut=super-o value=open} Open folder
{blue shortcut=ctrl-shift-e value=edit} Edit
{shortcut=f2 value=rename} Rename
MENUCombine ctrl-, alt-, shift-, and super- in any order before a character,
function key (f1–f35), or named key (space, enter, tab, backspace,
delete, insert, left, right, up, down, home, end, page-up,
page-down). Letter names ignore case; request Shift explicitly. Plain
characters are allowed but take precedence over typing into the search field.
Escape, Ctrl-C, Ctrl-G, and unmodified Enter/Tab remain reserved.
Shortcuts activate only entries in the current search results, including other
pages. They print the entry's value= (or label) and close the menu. Use unique
shortcuts; duplicates select the first matching entry in input order. Global
--bind actions take precedence on conflicts. Headings cannot have shortcuts,
and shortcuts are inactive in --single-key, input-only, password, and toast
modes. {key=q} remains the separate single-character --single-key interface.