confhelp 0.1.1

Config-driven parser for keybindings with fzf interface

confhelp

Config-driven parser for extracting keybindings from dotfiles.

Why

Most developers accumulate keybindings across tmux, zsh, vim, and other tools. These bindings live scattered across config files, and remembering them all becomes impossible.

The typical solution is maintaining a static YAML or markdown file listing shortcuts. But this falls out of sync - you add a binding and forget to update the docs.

confhelp solves this by parsing your actual config files. Define regex patterns once, and confhelp extracts bindings directly from source. Your help system stays in sync because it reads the same files you edit.

Install

pip install confhelp

Usage

# Output all bindings
confhelp -c config.toml -b ~/dotfiles

# Interactive fzf selection
confhelp -c config.toml -b ~/dotfiles --select

# Select and open in $EDITOR at line
confhelp -c config.toml -b ~/dotfiles --edit

# JSON output
confhelp -c config.toml -b ~/dotfiles -f json

Example output:

[tmux]   prefix+g   display-popup -w 80%...   .tmux.conf:42
[alias]  gs         git status                .zsh_aliases:15
[bind]   ^[e        edit-command-line         .zshrc:89

The --edit flag drops you directly into the file at the exact line. Change the binding, save, done.

Config Format

Define parsers in TOML. Each section describes how to extract bindings from a set of files:

[tmux]
paths = [".tmux.conf"]
match_line = "^bind"
regex = 'bind(?:-key)?\s+(?:-n\s+)?(\S+)(.*)'
key_group = 1
desc_group = 2
type = "tmux"
truncate = 100

[alias]
paths = [".zsh_aliases", ".zsh_claude"]
regex = "alias\\s+(?:-[gs]\\s+)?([^=]+)=(.*)"
key_group = 1
desc_group = 2
type = "alias"
strip_quotes = true

[abbrev]
paths = [".zsh_abbreviations"]
mode = "abbrev_block"
type = "abbrev"

Config Options

Option	Description
paths	List of files to parse (relative to base-dir)
regex	Pattern with capture groups for key/desc
key_group	Capture group number for the key
desc_group	Capture group number for description
match_line	Only process lines matching this pattern
skip_comment	Skip lines starting with #
truncate	Max length for description
strip_quotes	Remove surrounding quotes from desc
desc_literal	Use fixed string as description
desc_from_comment	Extract desc from trailing # comment
mode	Special modes: abbrev_block for zsh abbreviations

Output Formats

• pipe (default): [type]|key|desc|file:line
• tsv: Tab-separated
• json: JSON array

The pipe format works well with column -t -s'|' for aligned display.

Integration Examples

confhelp outputs text. How you display it is up to you.

Alacritty Popup

Spawn a centered popup window showing bindings. Enter jumps to the file:

selection=$(confhelp -c config.toml -b ~/dotfiles | column -t -s'|' | fzf)
# parse selection, open in editor

See examples/alacritty-popup.sh for a complete implementation.

tmux Popup

tmux display-popup -w 80% -h 80% -E 'confhelp -c config.toml -b ~/dotfiles --select'

See examples/tmux-popup.sh for a complete implementation.

Rofi/dmenu

confhelp -c config.toml -b ~/dotfiles | rofi -dmenu

Acknowledgments

Inspired by Extracto.

License

MIT