qst 0.11.0

A Community Driven CLI Quick Script Tool
qst-0.11.0 is not a library.

Qst, pronounced "quest", is a TUI Linux application launcher built with Rust + Ratatui.

Highlights

  • Fast .desktop app scanning and fuzzy search.
  • Usage/favorites-based ordering.
  • Launch arguments support.
  • File explorer mode enabled by default.
  • Keyboard-first navigation and customization.
  • Extensible plugin system with script-based plugins.

Plugin model

qst is the host runtime. Plugins are script-based and live in ~/.config/qst/scripts/. Plugins can define custom triggers, query handling, and output formatting via a simple line-oriented protocol.

Note: qst bundles a helper script, loader.sh, and will install it into ~/.config/qst/scripts/ on first run so users can browse and install community plugins without manually copying files.

Scripts can be executable files (any language) or extension-based scripts run through supported interpreters (.sh, .bash, .zsh, .fish, .py, .pl, .rb, .js, .lua).

The plugin ecosystem is cataloged in awesome-qst:

Install

Install via Nix (recommended):

nix profile install "github:GitanElyon/qst"

Or via the AUR (Arch Linux):

yay -S qst

Or via Cargo:

cargo install --locked qst

Or build from source:

git clone https://github.com/GitanElyon/qst.git
cd qst
cargo install --locked --path .

Usage

Either run qst from the terminal:

qst

You can also use launch-time flags:

qst --config <path>       # points Qst to a new different config file
qst --prefill <string>    # seeds the initial search text
qst --shy                 # opens launcher with text hidden untill query is entered
qst --no-fuzzy            # disables fuzzy finding
qst --clear-history       # clears Qst's launch history
qst --clear-favorites     # clears favorite list
qst --program <program>   # launches the first result of the query
qst --script <script>     # opens the script on startup
qst --list-programs       # lists available programs
qst --list-scripts        # lets available scripts
qst --debug-overlay       # start with the debug overlay visible
qst --log-level debug     # set log level: debug, info, warn, error (default: info)

Or bind to a global hotkey (e.g. Super+Space) using your desktop environment's keyboard settings.

Example for hyperland users to mimic rofi:

bind = $mod, space, exec, [float; size 350 400] $terminal -e qst

Keybindings

  • Up/Down: move selection
  • Left/Right: move cursor in input
  • Tab: autocomplete path
  • Enter: launch/open selected item
  • Esc: quit
  • Alt+f: toggle favorite
  • Ctrl+d: toggle debug overlay

Logging

qst writes logs to ~/.local/state/qst/qst.log with the following format:

[2024-06-15 10:30:45.123] [INFO] [src/app.rs:127] Loaded 17 scripts

Log levels

Level Purpose
DEBUG All actions, user movement, key events, renders
INFO Script loads, program launches, config loaded
WARN Minor errors (parsing issues, script timeouts)
ERROR Fatal errors (script won't load, app crashes)

Default level is INFO. Configure via --log-level <level> flag or log_level in config.toml ([general] section).

Session history

Each qst session starts fresh. The previous session's log is moved to ~/.local/state/qst/sessions/<timestamp>.log automatically.

Debug overlay

Press Ctrl+d (or your configured debug_key) to toggle a diagnostic bar at the top of the TUI:

FPS: 60 | Frame: 16.5ms | Entries: 42 | Events: 1234

Shows real-time FPS, frame render time, current entry count, and total key events this session.

The keybinding can be customized in ~/.config/qst/config.toml:

[general]
debug_key = "ctrl+d"

Start with the overlay enabled via --debug-overlay.

Config files

  • ~/.config/qst/config.toml
  • ~/.config/qst/alias.toml (optional script and app aliases)

See DOCS.md for full configuration details.