keyd.rvaiya(1)

📦
version 2.5.0 · 2 versions
, in ubuntu resolute, ubuntu stonking

🌸 keyd.rvaiya — the manual page (General Commands Manual) 🌸

okay bestie, sit down, hydrate, because this is the keyd.rvaiya(1) page and it's long — but it's also iconic, so we're doing this together 💖

✨ NAME ✨

keyd.rvaiya — a key remapping daemon. that's it. that's the vibe. 💅

✨ SYNOPSIS ✨

keyd.rvaiya [command] [options]

🎀 COMMANDS 🎀

  • monitor [-t] — prints key events for you, like a little gossip feed of everything your keyboard is saying. if you also pass -t, it also prints the time since the last event, in ms. super useful for finding out key names and device ids, and for debugging. 🔍
  • listen — prints the layer state changes of the running keyd daemon straight to stdout. great for scripting, lowkey a blessing for automation girlies. 🦋
  • bind reset|<binding> [<binding>...] — applies the bindings you hand it. see Bindings for the deets. 💫
  • reload — reloads the config files. the classic "did you try turning it off and on again" but for configs. 🔄
  • list-keys — lists all the valid key names. king behavior. 👑
  • input [-t <timeout>] <text> [<text>...] — inputs the text you give it. if you give it no arguments, it reads the input from STDIN instead. you can optionally pass a timeout in microseconds, which corresponds to the time between emitted events. ⏱️
  • do [-t <timeout>] [<exp>] — executes the expression you supply. see MACROS for the format of <exp> (yes, it literally spells it <exp>, we don't question it). if you give no arguments at all, the expression gets read from STDIN. and if you do supply it, <timeout> corresponds to the macro_sequence_timeout. 🪄

✨ OPTIONS ✨

  • -v, --version — prints the current version and then dips out. 🫶
  • -h, --help — prints help and exits. the "help me bestie" flag. 😭

💜 DESCRIPTION 💜

keyd is a system wide key remapping daemon, and it supports features like layering, oneshot modifiers, and macros. in its most basic form you can use it to define a custom key layout that persists across display server boundaries (like wayland / X / tty — she does not care which one you're in, she's universal). 🌈

the program runs in the foreground, printing diagnostic information to the standard output streams, and it's intended to be run as a single instance managed by the init system. one instance, one queen, no drama. 👑

NOTE: because keyd modifies your primary input device, it is genuinely possible to render your machine unusable with a bad config file. 😭 if you ever find yourself in that situation, the panic sequence backspace+escape+enter will force keyd to terminate. memorize it. tattoo it. it will save you. 💀

🎀 CONFIGURATION 🎀

config files loosely follow an INI style format — key word is loosely, she's an INI girlie but she's not gonna be strict about it. it consists of headers of the form [section_name] followed by a set of bindings. any line beginning with a hash is ignored. 🚫

config files live in /etc/keyd/ and get loaded upon initialization. the reload command can be used to update the working set of config files (e.g. sudo keyd reload). ✨

a valid config file has the extension .conf and it must begin with an [ids] section that has one of the following forms:

[ids]

<id 1 (obtained via keyd.rvaiya monitor)>
<id 2>
...

or

[ids]

*
-<id 1>
-<id 2>
...

the first form specifies a list of ids to be explicitly matched, while the second matches any id which has not been explicitly excluded. pick your fighter. 💅

for example:

[ids]
*
-0123:4567

will match all keyboards which do not(2) have the id 0123:4567, while:

[ids]

0123:4567

will exclusively match any devices which do. device ids can be obtained from the monitor command (see COMMANDS). note that a device id may only be listed in a single config file. no double dipping. 🙈

each subsequent section of the file corresponds to a layer (with the exception of [global] (see GLOBALS).

config errors will appear in the log output and can be accessed in the usual way using your system's service manager (e.g. sudo journalctl -eu keyd). 🔎

if an id matches more than one device type, the prefix k: may be used to exclusively match keyboards and the prefix m: may be used to exclusively match mice. (e.g. m:046d:b01d) 🐭

Note: all keyboards defined within a given config file will share the same state. this is useful for linking separate input devices together (e.g. foot pedals). 🦶
Note 2: the wildcard will only match devices which keyd identifies as keyboards. keyd is also capable of managing mice (e.g. to facilitate clearing of oneshot modifiers on click), but their ids must be explicitly listed.
Note 3: mouse support is currently experimental, and is mostly confined to traditional mice (e.g. touchpads). adding some mice to your ids section may break your pointer. 😭 it may also be necessary to explicitly blacklist mice which are misidentified as keyboards (e.g. if you find your moused misbehaving).

🦋 Layers 🦋

a layer is a collection of bindings, each of which specifies the behaviour of a particular key. multiple layers may be active at any given time, forming a stack of occluding keymaps consulted in activation order. the default layer is called main and that's where your common bindings should go. 💖

for example, this config snippet defines a layer called nav and creates a toggle for it in the main layer:

[main]

capslock = layer(nav)

[nav]

h = left
k = up
j = down
l = right

so when capslock is held, the nav layer occludes the main layer, which makes hjkl function as the corresponding arrow keys. vim girlies, we see you. 👀

unlike most other remapping tools, keyd provides first class support for modifiers. a layer name may optionally end with a ':' followed by a set of modifiers to emulate in the absence of an explicit mapping. layer names may consist of a maximum of 64 characters (including all modifiers). bestie, sixty-four. don't push it. 🫠

these layers play nicely with other modifiers and preserve existing stacking semantics. ✨

for example:

[main]

capslock = layer(capslock)

[capslock:C]

j = down

will cause capslock to behave as control, except in the case of capslock+j, which will emit down. this makes it trivial to define custom modifiers which don't interfere with one another. slay. 💅

note that bindings are not affected by the modifiers of the layer in which they are defined. thus capslock+j will produce an unmodified down keypress, while shift+capslock+j will produce shift+down as expected. 🌸

formally, each layer heading has the following form:

"[" <layer name>[:<modifier set>] "]"

where <modifier_set> has the form:

<modifier1>[-<modifier2>]...

and each modifier is one of:

C - Control
M - Meta/Super
A - Alt
S - Shift
G - AltGr

finally, each layer heading is followed by a set of bindings which take the form:

<key> | <alias> = <key>|<macro>|<action>

for a description of <action> and <macro> see ACTIONS and MACROS.

by default, each key is bound to itself within the main layer. the exception to this are the modifier keys, which are instead bound to eponymously named layers with the corresponding modifiers. 💫

for example, meta is actually bound to layer(meta), where meta is internally defined as meta:M.

the full set of modifier bindings are as follows:

control = layer(control)
meta = layer(meta)
shift = layer(shift)
leftalt = layer(alt)
rightalt = layer(altgr)

a consequence of this is that overriding modifier keys is a simple matter of adding the desired bindings to an appropriate pre-defined layer. so easy it's giving main character energy. 👑

thus

[ids]
*

[control]
j = down

is a completely valid config, which does what the benighted user might expect. internally, the full config actually looks something like this:

[ids]
*

[main]
leftcontrol = layer(control)
rightcontrol = layer(control)

[control:C]
j = down

if multiple bindings for the same key are present, the most recent one takes precedence. last one wins, periodt. 💅

a layer heading may also appear multiple times, in which case the layer will contain the sum of all bindings. note that the layer type may not be reassigned. 🙅

that is:

[mylayer:A]
a = b
c = d

[mylayer:C]
a = x
b = c

is equivalent to:

[mylayer:A]
a = x
b = c
c = d

🌈 Composite Layers 🌈

a special kind of layer called a composite layer can be defined by creating a layer with a name consisting of existing layers delimited by +. the resultant layer will be activated and given precedence when all of its constituents are activated. composite layers are not allowed to have modifiers attached and they cannot be explicitly assigned. she's built different and she cannot be tamed. 🦋

e.g.

[control+alt]
h = left

will cause the sequence control+alt+h to produce left (ignoring the control and alt modifiers attached to the active control and alt layers), while pressing control+alt+f1 preserves those modifiers, emitting exactly what was pressed, as there is no explicit binding for f1 on the composite layer. facts only. ✅

[main]
capslock = layer(capslock)

[capslock:C]

[capslock+shift]
h = left

will cause the sequence capslock+shift+h to produce left, while preserving the expected functionality of capslock and shift in isolation. ✨

Note: composite layers must always be defined after the layers of which they're comprised.

that is:

[layer1]
[layer2]
[layer1+layer2]

and not

[layer1+layer2]
[layer1]
[layer2]

🎀 Layouts 🎀

a layout is a special kind of layer intended for modifying alpha keys. unlike layers, layouts cannot have any associated modifiers, and only one layout may be active at a given time. the default layout is called 'main', and it can be changed using the setlayout() action. 👑

for convenience, keyd ships with a number of common letter layouts in /usr/share/keyd/layouts. before including these, it is instructive to inspect them. non-english layouts include a dedicated shift layer (making order of inclusion important) and require the use of keyd's compose definitions (see Unicode Support). 🌍

e.g.

# Include the shipped colemak layout.
include layouts/colemak

[global]
default_layout = mylayout

[mylayout:layout]
a = b
b = c
#etc...

[control]
1 = setlayout(customlayout)
2 = setlayout(colemak)

💜 Chording 💜

chords are groups of keys which are treated as a unit when simultaneously depressed. a chord can be defined by using a group of + delimited key names as a left hand value. the corresponding action will be activated if all keys are struck within the chording interval (chord_timeout). 🤝

e.g.

j+k = esc

will cause esc to be produced if both j and k are simultaneously depressed. piano hands, activate. 🎹

Note: it may be desirable to change the default chording interval (50ms) to account for the physical characteristics of your keyboard. every keyboard is a different girlie. 💅

💖 Unicode Support 💖

OK so bestie, if keyd spots a valid UTF8 sequence sitting on the right hand side of a binding, it's gonna try and translate that whole sequence into a macro that emits a keyd-specific XKB sequence. Iconic, right? ✨

But for that to actually work, the sequences defined in the compose file that ships with keyd (/usr/share/keyd/keyd.compose) have to be accessible. Two ways to do that:

  • Globally — copy the file to the appropriate location inside /usr/share/X11/locale
  • Per-user — symlink it to ~/.XCompose

E.g.:

ln -s /usr/share/keyd/keyd.compose ~/.XCompose

On top of that, you also need to be running the default US layout on your display server. If you're on a non-english layout, the advice is: set your layout within keyd instead (see Layouts) so you don't get conflicts between the display server layout and keyd's unicode functionality. 🫶

Note: you may have to restart your applications for this to take effect.
Note 2: the generated compose sequences are affected by modifiers in the normal way. So if you want Shift to produce a different symbol, you're gonna need to define a custom shift layer (the included layout files have an example of that).
Note 3: GTK4 currently has a bug 💀 which causes it to crash in the presence of large XCompose files (like /usr/share/keyd/keyd.compose).

🎀 Aliases 🎀

Each key may optionally be assigned an alias, and that alias can then be used in place of the key as a valid left hand value. Multiple keys may be bound to the same alias — but only one alias may be assigned to a key at a given time. That's the rule, no cap. 💅

For example, the keys leftmeta and rightmeta are bound to the alias meta by default. So the binding meta = a is equivalent to the bindings leftmeta = a and rightmeta = a.

Aliases get defined in a special section called aliases, where each line looks like:

<key> = <name>

where <key> must be a valid key name.

Now here's the spicy part 🌶️ — <name> may itself be a valid key name. If that happens, all references to the key within the config file get replaced with the new key. And on top of that, if the assigned alias is a valid key name, the corresponding keycode gets assigned to the key by default. This is what makes it possible to redefine keys before any bindings are applied, and it's particularly useful when you team it up with the include mechanism to account for variations in hardware.

For example:

/etc/keyd/common:
     meta = oneshot(meta)
     alt = oneshot(alt)

     a = a
     s = o
     # etc..

/etc/keyd/default.conf:
     [ids]
     *

     [main]
     include common

/etc/keyd/magic_keyboard.conf:
     [ids]
     004c:0267

     [aliases]
     leftalt = meta
     rightalt = meta
     rightmeta = alt
     leftmeta = alt

     [main]
     include common

This lets you define a set of universal bindings in /etc/keyd/common without having to explicitly account for the transposed meta and alt keys inside the included config snippet. Chef's kiss. 👑

🦋 File Inclusion 🦋

Config files may include other files located within the config directory using the include keyword. A line of the form include <file> may appear at any point after the [ids] section. The resultant config will behave as though the contents of the included file appear in place of the include statement. Like magic ✨ except it's just text substitution, bestie.

Making strategic use of these statements makes it possible to share common functionality between configs.

Include paths are relative and must be placed in one of the following directories:

  • /etc/keyd/
  • /usr/share/keyd/

E.g.:

/etc/keyd/default.conf:
     [ids]
     *

     # Add our shared custom bindings.
     include common

     # Appends bindings to the main layer
     # defined in /etc/keyd/common (order matters)
     [main]
     capslock = layer(capslock)

     [capslock]
     1 = setlayout(colemak)
     2 = setlayout(dvorak)

/etc/keyd/common:
     [main]

     rightmeta = layer(nav)

     [nav]

     h = left
     j = down
     k = up
     l = right

/usr/share/keyd/layouts/dvorak:
     a = a
     s = o
     ...

Limitations:

  • All include statements should appear after the [ids] section in the including file.
  • Included files should not contain an ids section.
  • Included files should not include other files (inclusion is non-recursive).
  • Included files should not end in .conf.

✨ GLOBALS ✨

There's a special section called [global] that you can define in the file, and it can contain any of the following options:

  • macro_timeout — The time (in milliseconds) separating the initial execution of a macro sequence and the first repetition. (default: 600)
  • macro_repeat_timeout — The time separating successive executions of a macro. (default: 50)
  • layer_indicator — If set, this will turn the capslock light on whenever a layer is active. Note: some wayland compositors will aggressively toggle LED state, rendering this option unusable. (default: 0)
  • macro_sequence_timeout — If set, this will add a timeout (in microseconds) between each emitted key in a macro sequence. Useful to avoid overflowing the input buffer on some systems.
  • chord_timeout — The maximum time between successive keys interpreted as part of a chord. (default: 50)
  • chord_hold_timeout — The length of time a chord must be held before being activated. (default: 0)
  • oneshot_timeout — If non-zero, timeout a oneshot layer activation after the supplied number of milliseconds. (default: 0)
  • disable_modifier_guard — By default, keyd will inject additional control keypresses where necessary in order to prevent programs from seeing additional modifier taps (E.g alt in firefox). If set, this option disables that behaviour. (default: 0)
  • overload_tap_timeout — If non-zero, ignore the tap behaviour of an overloaded key if it is held for the given number of miliseconds. (default: 0).
Note: Unicode characters and key sequences are treated as macros, and are consequently affected by the corresponding timeout options. 🌸

🔥 MACROS 🔥

Various keyd actions accept macro expressions, and a macro expression has one of the following forms:

  1. macro(<exp>)
  2. [<modifier 1>[-<modifier 2>...]-<key>
  3. <char>

Where <char> is a valid unicode character and <exp> has the form <token1> [<token2>...] and each token is one of:

  • A valid key code.
  • A type 2 macro.
  • A contiguous group of unicode characters.
  • A group of key codes delimited by + to be depressed as a unit.
  • A timeout of the form <time>ms (where <time> < 1024).

The following are all valid macro expressions:

  • C-a
  • macro(C-a)
  • macro(leftcontrol+leftmeta) # simultaneously taps the left meta and left control keys
  • A-M-x
  • macro(Hello space World)
  • macro(h e l l o space w o r ld) (identical to the above)
  • macro(C-t 100ms google.com enter)

Splitting into smaller tokens serves as an escaping mechanism: macro(space) inserts a space, but macro(s pace) writes "space". Likewise, macro(3+5) depresses the 3 and 5 keys as a unit, while macro(3 + 5) writes "3+5". Sibling behavior, honestly. 😭

Some prerequisites are needed for non-ASCII characters to work, see Unicode Support.

🎬 ACTIONS

A key can optionally be bound to an action, and actions take zero or more arguments. Some take none, some take a layer, some take a whole macro, some will take your whole keyboard hostage (we'll get to that one 💀).

  • layer(<layer>) — Activate the given layer for the duration of the keypress. Let go, layer's gone. Simple. Beautiful.
  • oneshot(<layer>) — If the key is tapped, activate the supplied layer for the duration of the next keypress. It's giving "one little favor, then we're done" energy ✨
  • swap(<layer>) — Swap the currently active layer with the supplied one. If the current layer is toggled, it gets deactivated and the supplied layer gets toggled instead. Otherwise the active layer is deactivated and the supplied layer stays active for as long as you hold the key that summoned it.

Example vibes:

[control]

x = swap(xlayer)

[xlayer]

s = C-s
b = S-insert
NOTE 🚨 You probably don't need this unless you're doing something quite involved. Think hard about whether what you're trying to achieve could be done by other means, because it is so easy to end up in states which are impossible to exit. No cap. Trapped in the layer dimension fr fr 😭
  • setlayout(<layout>) — Set the current layout.
  • clear() — Clear any toggled or oneshot layers. Big "fresh start" energy 🧹✨
  • toggle(<layer>) — Permanently toggle the state of the given layer. It stays on. It stays off. It flips when flipped.
  • layerm(<layer>, <macro>) — Identical to layer, but runs the supplied macro before the layer change.
  • oneshotm(<layer>, <macro>) — Identical to oneshot, but runs the supplied macro before the layer change.
  • swapm(<layer>, <macro>) — Identical to swap, but takes a macro to be executed immediately after the layer change.
  • togglem(<layer>, <macro>) — Equivalent to toggle, but also runs the supplied macro before toggling the layer.
  • clearm(<macro>) — Identical to clear, but runs the supplied macro before clearing layers.

🧠 Key overloading

The main character of procrastination-free typing. Peak. Iconic. 💅

  • overload(<layer>, <action>) — Activates the given layer while held, and executes action on tap. Held = layer. Tapped = action. Chef's kiss 👑
  • overloadt(<layer>, <action>, <timeout>) — Same as overload, except the layer only kicks in if the bound key is held for timeout milliseconds. This is mostly for overloading keys you commonly strike in sequence (letter keys, hi 💖).

Heads up bestie: this adds a visual delay when typing, since overlapping keys get queued up until the timeout expires or you release the bound key. Slight lag, big payoff 🐢✨

  • overloadt2(<layer>, <action>, <timeout>) — Identical to overloadt, but it also resolves as a hold if an intervening key tap happens. Best of both worlds.
  • overloadi(<action 1>, <action 2>, <idle timeout>) — Activate action 1 if the last non-action (i.e symbol) key was struck less than timeout milliseconds ago, otherwise activate action 2.

This plays super nicely with other overload timeouts and is especially useful for overloading letter keys — the thing people call 'homerow mods' 🏠

For example:

a = overloadi(a, overloadt2(control, a, 200), 150)

will produce a if and only if:

  • a is struck within 150ms of another non-action key.
  • a is struck more than 150ms after the last non-action key, but held for less than 200ms and there are no intervening key taps.

This cuts the visual latency by instantly resolving the key as a letter when you type it midword, while still letting it work as a layer trigger if you hold it long enough with no intervening symbols. The way it does both 😭💖

Since this is such a common usecase, a macro called lettermod (defined below) exists to make these definitions easier.

  • lettermod(<layer>, <key>, <idle timeout>, <hold timeout>) — An alias for:
overloadi(<key>, overloadt2(<layer>, <key>, <hold timeout>), <idle timeout>)
  • timeout(<action 1>, <timeout>, <action 2>) — If the key is held in isolation for more than timeout ms, activate the second action. If the key is held for less than timeout ms, or another key is struck before timeout ms expires, execute the first action.

E.g.

timeout(a, 500, layer(control))

Will cause the assigned key to behave as control if it is held for more than 500 ms.

  • macro2(<timeout>, <repeat timeout>, <macro>) — Creates a macro with the given timeout and repeat timeout. If a timeout value of 0 is used, macro repeat is disabled.

Note that macro must be a valid macro expression.

E.g.

macro2(400, 50, macro(Hello space World))
macro2(120, 80, left)
  • command(<shell command>) — Execute the given shell command.

E.g.

command(brightness down)
NOTE ⚠️ Commands are executed by the user running the keyd process (probably root), so use this feature judiciously. That's a lot of power in one little line, bestie 🔥
  • noop — Do nothing. Literally nothing. The key is just there. A little decorative rock. 🪨

🛰️ IPC

To facilitate extensibility, keyd employs a client-server model accessible through the use of -e. So the keymap isn't some frozen artifact — it's a living entity that can be modified at run time. Main character energy fr ✨

Besides letting you try new bindings on the fly, this lets you fully leverage keyd's expressive power from other programs without incurring a performance penalty. Zero. None. 🎀

For instance, you could write a script that alters the keymap whenever you switch between different tmux sessions. Obsessed with that idea actually.

The application remapping tool (keyd-application-mapper(1)) that ships with keyd is a great example of this in the wild. It's a small python script that does event detection for the various display servers (e.g X/sway/gnome, etc) and feeds the desired mappings to the core using -e. It's giving intern energy but make it powerful. 🐍💅

NOTE 🚨 Users with access to the keyd socket should be considered privileged (i.e assumed to have access to the entire system). Gatekeep the socket, bestie. 🔐

📝 Bindings

The bind command accepts one or more bindings, and each one must have the following form:

[<layer>.]<key> = <key>|<macro>|<action>

Where layer is the name of an (existing) layer in which the key is to be bound. Yes, it has to exist. Check your work 💖

Special case alert: the string "reset" may be used in place of a binding, in which case the current keymap will revert to its original state (all dynamically applied bindings will be dropped). It's the factory reset of bindings 🌈

Examples:

$ keyd bind '- = C-c'
$ keyd bind reset '+ = C-c' # Reset the keyboard before applying the '+' binding (drops the previous '-' binding)

By default, expressions apply to the most recently active keyboard. ✨

🌟 EXAMPLES

✨ Example 1

Make esc+q toggle the dvorak letter layout.

[ids]
*

[main]
esc = layer(esc)

[dvorak]

a = a
s = o
...

[esc]

q = toggle(dvorak)

🎀 Example 2

Invert the behaviour of the shift key without breaking modifier behaviour.

[ids]
*

[main]
1 = !
2 = @
3 = #
4 = $
5 = %
6 = ^
7 = &
8 = *
9 = (
0 = )

[shift]
0 = 0
1 = 1
2 = 2
3 = 3
4 = 4
5 = 5
6 = 6
7 = 7
8 = 8
9 = 9

💅 Example 3

Tapping control once causes it to apply to the next key, tapping it twice activates it until it is pressed again, and holding it produces expected behaviour.

[main]

control = oneshot(control)

[control]

control = toggle(control)

🦋 Example 4

Meta behaves as normal except when ` is pressed, after which the alt_tab layer is activated for the duration of the leftmeta keypress. Subsequent actuations will thus produce A-tab instead of M-\.

[meta]

` = swap(alt_tab, A-tab)

[alt_tab:A]

tab = A-S-tab
` = A-tab

🍓 Example 5

# Uses the compose key functionality of the display server to generate
# international glyphs.  # For this to work 'setxkbmap -option
# compose:menu' must # be run after keyd has started.

# A list of sequences can be found in /usr/share/X11/locale/en_US.UTF-8/Compose
# on most systems.

[main]

rightalt = layer(dia)

[dia]

# Map o to ö
o = macro(compose o ")

# Map e to €
e = macro(compose c =)

🧚 Example 6

# Tapping both shift keys will activate capslock.

[shift]

leftshift = capslock
rightshift = capslock

👑 Example 7

Capslock will behave as control in all instances except when used in conjunction with 'h/j/k/l', in which case it will produce arrow keys. If tapped, it will function as escape.

[main]
capslock = overload(capslock, esc)
esc = capslock

[capslock:C]
h = left
k = up
j = down
l = right

💀 Example 8

Disables the esc and end keys.

[main]
esc = noop
end = noop

🌸 ENVIRONMENT VARIABLES

  • KEYD_DEBUG — Debug log level. 0,1,2 can be specified (default: 0). Crank it up when things get weird 🐛

💖 AUTHOR

Written by Raheman Vaiya (2017-). Legend behaviour, honestly. 🫶

🐛 BUGS

Please file any bugs or feature requests at the following url:

<https://github.com/rvaiya/keyd/issues>

Go off, report the bug, make it better 💜

That's the whole keyd.rvaiya(1) page bestie — this one landed on 2025-08-12, and it's the keyd.rvaiya(1) manual page, section 1, so you know it's the real deal. Now go bind something unhinged. Slay. 🎀💅✨

📦 where this page comes from