xd

xd is tiny command line program written in Go that generates dmenu based on provided easily configurable yaml files.

simplescreenrecorder-2023-06-07_03.53.28.mp4

Installation and Usage

# Build
make build
# Install
sudo make install
# Uninstall
sudo make uninstall

# Usage:
xd -config=/path/to/config.yaml -command=bluetooth -- -l 10 additional dmenu args...
# -config - Specifies a particular configuration file to use. 
#           Any config files in the default configuration directory will be ignored.
# -command - Allows for the direct execution of a top-level command parsed from the configuration file. 
#            This can be useful for binding shortcuts, such as in dwm/config.
#            For instance: 'ctrl+shift+b' could map to 'xd -command bluetooth'

Configuration

The xd utility uses configuration files to define the commands it can run.
If the -config flag is not provided when running xd, it will look for configuration files in the directory specified by $XDG_CONFIG_HOME/xd/.
If this directory does not contain any configuration files, xd will automatically create a default one.

Importantly, xd supports multiple configuration files. When loading its configuration, xd will read all the .yaml files located in the $XDG_CONFIG_HOME/xd/ directory and merge the commands defined in them. This allows you to split your commands across multiple files for better organization, if desired.

Here's an example of a configuration file with detailed explanation:

# A top-level command
- name: Mpv               # The name of the command that will be displayed on the dmenu
  prompt: "Paste URL... [Ctrl+Shift+Y] " # The prompt that will be displayed when this command is selected
  cmd: mpv $selected      # The actual command to run. '$selected' will be replaced by the user's input

# Another top-level command
- name: WiFi
  list: "nmcli device wifi list | sed '1d'" # The 'list' command generates dynamic options for the dmenu
  cmd: "device=$(echo $selected | tr -s ' ' | cut -d ' ' -f1); nmcli device wifi connect $device" 
  # The actual command to run. '$selected' will be replaced by the user's selection from the options generated by 'list'

# A top-level command containing sub-commands
- name: System
  commands:              # A list of sub-commands nested under 'System'
    - name: Reboot       # The name of the sub-command that will be displayed on the dmenu
      cmd: reboot        # The actual command to run when this sub-command is selected
    - name: Shutdown
      cmd: shutdown now
    - name: Suspend
      cmd: systemctl suspend

For additional examples of configuration files, please refer to the examples directory in this repository.

Pass Args to Dmenu

You can pass additional arguments to dmenu after specifying the -config or -command flags. It is crucial to add -- after your flags to indicate the end of command options and ensure subsequent arguments are passed to dmenu correctly.

For example, to pass the -l argument (which controls the number of lines dmenu displays) to dmenu, you would write:

xd -config=/path/to/config.yaml -- -l 15

License

xd is released under the MIT License.