keyd/docs/keyd.scdoc

keyd(1)

# NAME

*keyd* - A key remapping daemon.

# SYNOPSIS

*keyd* [command] [options]

# COMMANDS

*monitor [-t]*
	Print key events. If -t is supplied, also prints time since the last event in ms. Useful for discovering key names and debugging.

*listen*
	Print layer state changes of the running keyd daemon to stdout. Useful for scripting.

*bind <binding> [<binding>...]*
	Apply the supplied bindings. See _Bindings_ for details.

*list-keys*
	List valid key names.

*input [<text> [<text>...]]*
	Input the supplied text. If no arguments are given, read the input from STDIN.

*do [<exp>]*
	Execute the supplied expression. See MACROS for the format of <exp>. If no arguments are given, the expression is read from STDIN.

# OPTIONS

*-v, --version*
	Print the current version and exit.

*-h, --help*
	Print help and exit.

# DESCRIPTION

keyd is a system wide key remapping daemon which supports features like
layering, oneshot modifiers, and macros. In its most basic form it can be used
to define a custom key layout that persists across display server boundaries
(e.g wayland/X/tty).

The program runs in the foreground, printing diagnostic information to the
standard output streams, and is intended to be run as a single instance managed
by the init system.

*NOTE:*

Because keyd modifies your primary input device, it is possible to render your
machine unusable with a bad config file. If you find yourself in this situation
the panic sequence *<backspace>+<escape>+<enter>* will force keyd to
terminate.

# CONFIGURATION

Configuration files loosely follow an INI style file format and consist of sections
of the form _[section_name]_ followed by key-value pairs delimited
by an equal sign (one per line). Lines which are empty or begin with a hash sign
are ignored.

The files are stored in _/etc/keyd/_ and loaded upon initialization.
Changes can be triggered using the reload command (sudo keyd reload).

A valid config file has the extension _.conf_ and *must* begin with an _[ids]_
section that has one of the following forms:

```
	[ids]

	<vendor id 1>:<product id 1>
	<vendor id 2>:<product id 2>
	...
```

or

```
	[ids]

	*
	-<vendor id 1>:<product id 1>
	-<vendor id 2>:<product 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.

For example:

```
	[ids]
	*
	-0123:4567
```


Will match all devices which *do not*(2) have the id _0123:4567_, while:

```
	[ids]
	0123:4567
```

will exclusively match any devices which do.

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`).

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.

## 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 is where common bindings should be defined.

For example, the following 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
```

When capslock is held, the _nav_ layer occludes the _main_ layer
causing _hjkl_ to function as the corresponding arrow keys.

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.

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 _control+j_, which will
emit _down_. This makes it trivial to define custom modifiers which don't interfere with
one another.

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_.

As hinted at above, when a binding is activated through a key press, it inherits
the modifiers attached to all other currently active layers (irrespective of
their position in the layer stack) but ignores the modifier sets of the layer it
is defined on.

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_.

A consequence of this is that overriding modifier keys is a simple matter of
adding the desired bindings to an appropriate pre-defined layer.

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
```

A key may be bound multiple times on a given layer, in which
case every binding encountered overrides an earlier one. Furthermore, it is
allowed (but discouraged) to scatter layer bindings over multiple identically
named sections, again with later definitions taking precedence over earlier
ones. However, modifier sets of a repeated layer section are ignored. For
example

```
	[mylayer:A]
	a = b

	[control:C]
	j = down

	[mylayer:M]
	a = c
	b = d
```

is equivalent to

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

	[control:C]
	j = down
```

## 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
cannot be explicitly assigned. In the same way that an explicit binding on a
regular layer ignores the modifier set of that layer, an explicit binding on a
composite layer ignores the modifier sets of all constituents.

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.

*Note:* composite layers *must* always be defined _after_ the layers of which they
are 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 current layout can be set 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)
```


## Unicode Support

If keyd encounters a valid UTF8 sequence as a right hand value, it will try and
translate that sequence into a macro which emits a keyd-specific XKB sequence.

In order for this to work, the sequences defined in the compose file shipped
with keyd (_/usr/share/keyd/keyd.compose_) must be accessible. This can be achieved
globally by copying the file to the appropriate location in
_/usr/share/X11/locale_, or on a per-user basis by symlinking it to
~/.XCompose.

E.g.

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

**Additionally you will need to be using the default US layout on your
display server.** Users of non-english layouts are advised to set their layout
within keyd (see **Layouts**).

**Note:** You may have to restart your applications for this to take effect.

**Caveat:** Modifiers (in particular shift) are applied to this compose sequence
as usual, which might not be what you want. For example, pressing a key bound to
an accented letter while a shift modifier is active does not result in the
corresponding capital letter. In such cases, an explicit mapping on the shift
layer has to be added.

## Aliases

Each key may optionally be assigned to an *alias*. This alias may 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.

For example, the keys 'leftmeta' and 'rightmeta' are bound to the alias *meta*
by default. Thus the binding 'meta = a' is equivalent to the bindings 'leftmeta
= a' and 'rightmeta = a'. Further default aliases are *alt*, *shift*, *control*
(with bindings analogous to *meta*) and *altgr* (an alias for the key 'rightalt').

Aliases are defined in a special section called 'aliases' where each line takes
the form:

	<key> = <name>

where _<key>_ must be a valid key name.

Note that <name> may itself be a valid key name, in which case all references
to the key within the config file will be replaced with the new key.
Additionally, if the assigned alias is a valid key name, the corresponding
keycode will be assigned to the key by default. This makes it possible to
redefine keys before any bindings are applied and is particularly useful in
conjunction 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
```

Allows the user to define a set of universal bindings in /etc/keyd/common
without having to explicitly account for the transposed meta and alt keys within
the included config snippet.

## 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.

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

A special section called _[global]_ may be defined in the file
and 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.
	(default: 0)

	*macro_sequence_timeout:* If set, this will add a timeout (*in
	microseconds*) between each emitted key in a macro sequence. This is
	useful to avoid overflowing the input buffer on some systems.

	(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.

A valid macro expression has one of the following forms:

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

Where _<exp>_ has the form _<token1> [<token2>...]_ and each token is one of:

	- a valid key code (_keyd list-keys_ prints a list).
	- a type 2 macro.
	- a contiguous group of UTF-8 characters.
	- a group of key codes delimited by + to be depressed as a unit.
	- a timeout of the form _<time>ms_ (where _<time>_ < n1024).

The following are all valid macro expressions:

	- C-a
	- macro(C-a) (equivalent to the above)
	- macro(control+a) (yet another form of the above)
	- macro(a+control) (not equivalent to the above, as a is pressed earlier than control)
	- 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".

Some prerequisites are needed for non-ASCII characters to work, see _Unicode Support_.

# ACTIONS

A key may optionally be bound to an _action_ which accepts zero or more
arguments.

Whenever an argument is another action, a valid macro expressions may be supplied instead.

Whenever an argument is a layer, neither _main_, nor a composite layer are accepted.

## Manipulation of the layer stack

*layer(<layer>)*
	Activate the given layer for the duration of the keypress.

*oneshot(<layer>)* If tapped, activate the supplied layer for the duration of
	the next keypress. If _<layer>_ is a modifier layer then it will cause
	the key to behave as the corresponding modifiers while held. If the next
	pressed keys are bound to actions which resolve to further layer
	activations (such as _layer_, _overload_, _oneshot_ or a _timeout_
	resolving to one of the aforementioned three actions), the original
	oneshot layer _<layer>_ is kept active. This makes it possible to stack
	modifiers. Consider for example

```
	[main]
	shift = overload(shift, S-9)
	control = oneshot(control)
	alt = oneshot(alt)
	tab = timeout(oneshot(meta), 200, tab)
```

Here,
	- tapping control, tapping alt and then tapping a would result in C-A-a.
	- tapping control, holding shift and then tapping a would result in C-S-a.
	- tapping control, tapping tab within 200 ms and then tapping a would result in C-M-a, and so would tapping control, holding meta (by default bound to _layer(meta)_) and then tapping a.
	- tapping control, tapping tab within 200 ms, tapping alt and then tapping a would result in C-A-M-a.

*swap(<layer>)*
	Swap the currently active layer with the supplied one. The
	supplied layer is active for the duration of the depression of the
	current layer's activation key. This only works if a _layer_ action is
	currently active (i.e. another key is held down) and results in a noop
	otherwise.

```
	[control]

	x = swap(xlayer)

	[xlayer]

	s = C-s
	b = S-insert
```

*swap2(<layer>, <macro>)*

	Identical to *swap*, but accepts a macro to be executed immediately after the layer change.

*toggle(<layer>)*
	Permanently toggle the state of the given layer. Toggling the main layer
	is not allowed.

*toggle2(<layer>, <macro>)*
	Equivalent to *toggle*, but additionally executes the supplied macro before
	toggling the layer.

*setlayout(<layout>)*
	Set the current layout.

*clear()*
	Clear any active layers (the active layout is preserved).

## Key overloading

*overload(<layer>, <action>)*
	Activates the given layer while held and executes <action> on tap.

*overload2(<layer>, <action>, <timeout>)*
	Identical to overload, but only activates the layer if the bound key is
	held for \<timeout\> milliseconds. This is mainly useful for overloading keys
	which are commonly struck in sequence (e.g letter keys). 

	Note that this will add a visual delay when typing, since overlapping
	keys will be queued until the timeout expires or the bound key is
	released.

*overload3(<layer>, <action>, <timeout>)*
	Identical to overload2, but additionally resolves as a hold in the
	event of an intervening key tap.

*timeout(<action 1>, <timeout>, <action 2>)*
	If the key is held in isolation for more than _<timeout> ms_, activate the first
	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.

## Miscellaneous

*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),
use this feature judiciously.

*noop*
	Do nothing.

# IPC

To facilitate extensibility, keyd employs a client-server model accessible
through the use of *-e*. The keymap can thus be conceived of as a
living entity that can be modified at run time.

In addition to allowing the user to try new bindings on the fly, this
enables the user to fully leverage keyd's expressive power from other programs
without incurring a performance penalty.

For instance, the user may use this functionality to write a script which
alters the keymap when they switch between different tmux sessions.

The application remapping tool (*keyd-application-mapper(1)*) which ships with keyd
is a good example of this. It is a small python script which performs event
detection for the various display servers (e.g X/sway/gnome, etc) and feeds the
desired mappings to the core using _-e_.

*NOTE:* Users with access to the keyd socket should be considered privileged
(i.e assumed to have access to the entire system.).

## Bindings

The _bind_ command accepts one or more _bindings_, each of which 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.

As a special case, 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).

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
of _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
```

# AUTHOR

Written by Raheman Vaiya (2017-).

# BUGS

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

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