.TH CHD 1 "MAY 2026" "1.0" "CHD Manual"
.SH NAME
chd \- a lightweight socket-based X11 keybinding daemon
.SH SYNOPSIS
.B chd
[\fICONFIG_FILE\fR]
.br
.B chd bind
\fIKEYCOMBO\fR \fICOMMAND\fR
.br
.B chd wait
.SH DESCRIPTION
.B chd
is a minimal utility designed to manage X11 global hotkeys. It operates as a daemon that listens on a Unix domain socket for binding requests.
.PP
When started without a command,
.B chd
launches the daemon, creates a socket at \fB/tmp/chd.sock\fR, and executes the specified \fICONFIG_FILE\fR. This architecture allows for dynamic configuration using any scripting language.
.SH COMMANDS
.TP
.B (default)
Starts the daemon mode. If no \fICONFIG_FILE\fR is provided, it defaults to \fB~/.config/chd/chdrc\fR. The daemon exports the \fBCHD_BIN\fR environment variable to the child process.
.TP
.B bind \fIKEYCOMBO\fR \fICOMMAND\fR
Connects to the running daemon and registers a new binding. \fIKEYCOMBO\fR should follow the format "Modifier+Key" (e.g., "Super+Shift+Return").
.TP
.B wait
Blocks execution until the daemon has successfully initialized its Unix socket. This is essential for preventing race conditions in configuration scripts.
.SH ENVIRONMENT
.TP
.B CHD_BIN
Set by the daemon to the absolute path of the current binary. Recommended for use within scripts to ensure the client calls the correct version of the tool.
.SH FILES
.TP
.I /tmp/chd.sock
The Unix domain socket used for IPC communication.
.TP
.I ~/.config/chd/chdrc
The default user configuration script (must be executable).
.SH EXAMPLES
.PP
Example of a Lua-based \fBchdrc\fR:
.IP
#!/usr/bin/lua
.br
local p = os.getenv("CHD_BIN") or "chd"
.br
os.execute(p .. " wait")
.br
os.execute(p .. ' bind "Super+Return" "alacritty"')
.SH TROUBLESHOOTING
.TP
.B Syntax error: "(" unexpected
This occurs if the daemon tries to run a Lua config using \fB/bin/sh\fR. Ensure your \fBchdrc\fR has a proper shebang (\fB#!/usr/bin/lua\fR) and that the daemon is using \fBexecvp\fR instead of \fBexecl\fR.
.TP
.B chd: cannot open display
The \fBDISPLAY\fR environment variable is not set. Ensure you are running \fBchd\fR within an active X11 session.
.TP
.B Bindings not working
Check if another window manager or application has already "grabbed" the key. \fBchd\fR cannot override existing global grabs from programs like \fBi3\fR or \fBbspwm\fR if they started first.
.TP
.B Connection refused
The \fBchd wait\fR command timed out or the daemon crashed. Check if \fB/tmp/chd.sock\fR exists. If a stale socket remains after a crash, delete it manually.
.SH DIAGNOSTICS
If \fBchd\fR fails to launch the config script, ensure the script is executable (\fBchmod +x\fR) and has a valid shebang line.