SXHKD(1)

💖 sxhkd — your new bestie, the Simple X hotkey daemon 💖

Okay so picture this: a tiny little daemon whose whole personality is listening to your keyboard and running commands. That's sxhkd, bestie — she's got a seriously powerful and compact config syntax and she's not sorry about it. ✨

---

🦋 SYNOPSIS 🦋

sxhkd [OPTIONS] [EXTRA_CONFIG ...]

---

🌸 DESCRIPTION 🌸

sxhkd is a simple X hotkey daemon — and like, simple as in elegant, not simple as in boring. She comes with a configuration syntax that's powerful AND compact, which is genuinely the dream combo. iykyk. 💅

---

✨ OPTIONS ✨

• -h — prints the synopsis to standard output and then dips. bye bestie 👋
• -v — prints the version information to standard output and exits. iconique behavior.
• -m COUNT — handle the first COUNT mapping notify events. yes, only the first COUNT of them, she's picky.
• -t TIMEOUT — timeout in seconds for the recording of chord chains. ticking clock vibes ⏳
• -c CONFIG_FILE — read the main configuration from this given file instead of the default one.
• -r REDIR_FILE — redirect the commands output to the given file. catching all the receipts 🧾
• -s STATUS_FIFO — output status information to the given FIFO. very much a "keep me posted" moment.
• -a ABORT_KEYSYM — name of the keysym used for aborting chord chains. the panic button, essentially 🫶

---

🔥 BEHAVIOR 🔥

So sxhkd is a daemon — she sits there, listens to keyboard events, and executes commands. main character energy fr fr 👑

By default she reads her configuration file from $XDG_CONFIG_HOME/sxhkd/sxhkdrc, or from the file you hand her with the -c option if you're feeling specific.

You can also pass additional configuration files as arguments. more config, more power, no cap.

If sxhkd receives a SIGUSR1 signal, she reloads her configuration file. If she receives a SIGUSR2 signal, she toggles the grabbing state of all her bindings. two signals, two whole moods 😭

If sxhkd receives a SIGALRM signal, she'll break the current chain — if there even is one in progress. no chain, no drama.

The commands are executed via SHELL -c COMMAND — which means yes, you absolutely can use environment variables in them. slay. 💜

SHELL will be the content of the first defined environment variable in this list, in this exact order: SXHKD_SHELL, SHELL.

SXHKD_PID gets automatically set to the pid of sxhkd in processes spawned by sxhkd. lowkey genius — which means the child process can easily send signals like SIGALRM to the correct instance of sxhkd. no more "which pid was it again" chaos 🙈

Okay listen, this next bit matters: if you have a non-QWERTY keyboard or a non-standard layout configuration, you should provide a COUNT of 1 to the -m option — or -1 (interpreted as infinity) if you constantly switch from one layout to the other. Why? Because sxhkd ignores all mapping notify events by default, since the majority of those events are pointless. she's just being efficient, okay? 💅

---

🎀 CONFIGURATION 🎀

Each line of the configuration file gets interpreted like so:

• If it's empty or starts with #, it is ignored. (rest, queen.)
• If it starts with a space, it is read as a command.
• Otherwise, it is read as a hotkey.

The general syntax, gorgeous and exact:

HOTKEY
    [;]COMMAND

HOTKEY      := CHORD_1 ; CHORD_2 ; ... ; CHORD_n
CHORD_i     := [MODIFIERS_i +] [~][@]KEYSYM_i
MODIFIERS_i := MODIFIER_i1 + MODIFIER_i2 + ... + MODIFIER_ik

The valid modifier names are: super, hyper, meta, alt, control, ctrl, shift, mode_switch, lock, mod1, mod2, mod3, mod4, mod5 and any. yes, both control and ctrl — she's flexible like that 💖

The keysym names are given by the output of xev -event keyboard. that's the plug, go get your names from there.

Hotkeys and commands can be spread across multiple lines by ending each partial line with a backslash character. long hotkey? no problem, just \ and keep going 🦋

When multiple chords are separated by semicolons, the hotkey is a chord chain — the command will only be executed after receiving each chord of the chain in consecutive order. it's giving combo move ⭐

The colon character can be used instead of the semicolon to indicate that the chord chain shall not be aborted when the chain tail is reached. tiny punctuation difference, big behavioral difference, be careful bestie 😭

If a command starts with a semicolon, it will be executed synchronously, otherwise asynchronously. that leading ; is doing a LOT of work.

The Escape key can be used to abort a chord chain. your get-out-of-jail key fr fr.

If @ is added at the beginning of the keysym, the command will be run on key release events, otherwise on key press events. and if ~ is added at the beginning of the keysym, the captured event will be replayed for the other clients. subtle, powerful, iconic 🎀

Pointer hotkeys can be defined by using one of the following special keysym names: button1, button2, button3, ..., button24. yes, all the way up to twenty-four, she's thorough. 🖱️

The hotkey and the command may contain sequences of the form {STRING_1,...,STRING_N}. and braces can be escaped with \. 🌈

In addition, the sequences can contain ranges of the form A-Z where A and Z are alphanumeric characters. ranges, bestie!! so much typing saved ✨

The underscore character represents an empty sequence element. don't forget her, she's the quiet one. 💜

---

👑 AUTHOR 👑

Bastien Dejean <nihilhill at gmail.com> 💖

---

🍓 MAILING LIST 🍓

sxhkd at librelist.com — come through, say hi 🫶

---

✨ that's the whole page, bestie ✨ this was Sxhkd 0.6.3, dated 09/27/2025 — go forth and bind your keys, you magnificent icon 💅👑