Getting Started

spmenu is a simple X11 and Wayland menu application which takes standard input, parses it, lets the user choose an option and sends the selected option to standard output.

In addition to this, it also serves as a run launcher through the included shell script spmenu_run, which handles both $PATH listing, .desktop entries and file listing.

While spmenu is based on dmenu, and is also fully compatible with dmenu, spmenu introduces many new features which can be useful in shell scripting.

It also serves as a dmenu replacement for Wayland users.

Installing spmenu

For up-to-date compilation instructions for spmenu, see Installing spmenu or your bundled README.md.

Using spmenu as a run launcher

There is a more detailed article covering this, called Using spmenu as a run launcher. If you just want the basics though, they're covered here.

spmenu comes with a script called spmenu_run. This is a much more powerful run launcher than what dmenu provides. This script handles $PATH listing and executing, .desktop entries (including Steam games), and even file management.

For $PATH listing (the traditional dmenu_run behavior) you can simply run spmenu_run. It should be noted that the default behavior can be overriden and for this reason it is recommended (but not required) that you use spmenu_run -x instead. This mode simply lists out all binaries in your $PATH variable. Nothing super fancy. Do however note that you can append entries here, and create functions to parse and do stuff with your selected item/input in the configuration file which can be found at ~/.config/spmenu/run/config. Doing so is covered in Functions in spmenu_run.

Using spmenu as a .desktop entry launcher

On the other hand, spmenu_run provides a .desktop launcher mode as well. To use it, you simply run spmenu_run -d. The first time you run this it will take a few seconds depending on the number of .desktop entries you have on your computer. It will start up instantly after that though. It will display your .desktop entries, along with the title and a brief description of what the program does. Of course, you can also append entries to this as well or hide certain entries in the configuration file which can be found at ~/.config/spmenu/run/config.

On X11, the application icon will (optionally) be displayed alongside the desktop entry. Wayland does not yet support displaying images, though so the image will not be displayed.

While an option to clear the cache when a new program is installed is available, it does not always work and is disabled for this reason. To clear the cache manually, simply run spmenu_run -cc. If you wish to clear the cache every time (this is quite slow), do spmenu_run -cc -d.

Using spmenu to parse text

The core concept of spmenu is to take standard input (or the contents of a file), parse it and allow the user to select an item. All scripts written for spmenu use this concept.

This is covered in more detail in the article Using spmenu to parse text.

Customizing spmenu_run

To customize spmenu_run, you can edit the configuration file which is ~/.config/spmenu/run/config. For even more customization you can also use functions. A dedicated page for functions exists, called Functions in spmenu_run.

Customizing spmenu

A basic configuration file can be found at /usr/share/spmenu/spmenu.conf. You can use this configuration file by simply copying it to ~/.config/spmenu/spmenu.conf. If the directory does not already exist, create it.

This configuration file can be edited using any text editor you want. If you're the kind of person who likes to have many themes, you may want to consider checking out User themes and the powerful theme.conf.

If you prefer a simplier spmenu config with more traditional keybinds, you can copy this file to ~/.config/spmenu/binds.conf.

That's it

That's it. That's all you need to know to get started with spmenu.. and a little more for good measure. From here, you can take a break, or check out User scripts, User themes, Functions in spmenu_run, Using spmenu to parse text, or spmenu.conf documentation if you're hungry for more.