Lib.rs

thqm

A command line utility to generate and serve a dynamic menu web page.

thqm takes its name from the arabic تحكم, pronounced tahakoom, meaning control.

thqm is a nifty little command line utility. It dynamically generates a web page menu based on the provided stdin and outputs any selections to stdout.

In a sense, it functions similarly to dmenu/rofi but the menu is a web page served on the local network.

This makes it perfect to control scripts over the network.

See the examples folder for some example scripts.

📦 Installation

Manual

To compile and install manually from this repo, you'll need rust installed.

To compile the binary:

git clone https://github.com/loiccoyle/thqm-rs
cd thqm-rs
cargo build --release

The compiled binary will be located at ./target/release/thqm. Just place this binary somewhere in your $PATH.

Or to install it straight from cargo:

cargo install thqm

Make sure you have cargo's bin folder in your $PATH.

You'll also need to install the template styles with:

thqm --install-styles

This will install the styles in the user data folder.

Arch linux (AUR)

Using your favourite AUR helper:

paru -S thqm

The installation process will install the styles system wide in the /usr/share/thqm folder.

📋 Usage

CLI options

thqm has a few command line options, when in doubt see the --help.

$ thqm --help
A simple HTTP server to serve a dynamic menu web page.

thqm generates a menu based on the standard input and writes selections to standard output.

See https://github.com/loiccoyle/thqm-rs/tree/main/examples for script examples.

Basic usage:
$ echo 'Option 1\nOption 2' | thqm -u |
    while IFS= read -r sel; do
      case $sel in
      'Option 1') echo 'hello';;
      'Option 2') echo 'world';;
      *) echo "$sel";;
      esac
    done

Usage: thqm [OPTIONS]

Options:
  -p, --port <PORT>            The port to listen on [default: 8000]
  -U, --username <USERNAME>    The username to authenticate with
  -P, --password <PASSWORD>    The password to authenticate with
  -S, --separator <SEPARATOR>  The entry separator [default: "\n"]
  -t, --title <TITLE>          The page title [default: thqm]
  -s, --style <STYLE>          The page style [default: default]
      --style-dir <PATH>       Specify style with its root directory
  -Q, --qrcode                 Show the qrcode in terminal
      --save-qrcode <PATH>     Save the qrcode image to file
  -u, --url                    Show the page url
  -o, --oneshot                Shutdown server after first selection
  -c, --custom-input           Show custom input field
      --list-styles            List available page styles
      --no-shutdown            Don't allow the server to be shutdown from the page
      --no-qrcode              Don't allow the qrcode to be shown in the page
      --install-styles         Download and install styles to the user data directory
  -v, --verbose...             Increase logging verbosity
  -q, --quiet...               Decrease logging verbosity
  -h, --help                   Print help
  -V, --version                Print version

Scripting

thqm will generate a web page based on the provided stdin, the selected entry will be printed to stdout.

For this behaviour to actually be useful, we'll need to do a bit of scripting.

A typical script will look something like this:

#!/bin/sh

# define the handler function, i.e. what each option should do.
handler() {
  while IFS= read -r event; do
    case "$event" in
    "Option 1")
      # handle Option 1
      ;;
    "Option 2")
      # handle Option 2
      ;;
    *)
      # pass through thqm's output
      echo "$event"
      ;;
    esac
  done
}

printf "Option 1\nOption 2" | thqm "$@" | handler
# ^                                 ^      ^ Pass user selections to the handler
# │                                 └ Forward script's options to thqm
# └ Provide the options to thqm through stdin

See the examples folder for some example scripts.

🎨 Styling

thqm has a few pre-made menu styles, see the thqm-styles repository, which can be installed to your system's user data directory with the --install-styles flag.

To create your own styles, follow the same file structure as the included styles.

The {DATA_DIR} directory depends on the OS:

• Linux: ${XDG_DATA_HOME}
• MacOS: $HOME/Library/Application Support
• Windows: C:\Users\{USER}\AppData\Roaming

The style tera template options are documented here.

User provided styles take priority over system wide styles.

If you want to contribute your own styles, please feel free to submit them to the thqm-styles repository.