#keyboard #macos

app kb-remap

Tool to assist remapping macOS keyboard keys

8 releases

0.2.1 Apr 9, 2022
0.2.0 Apr 6, 2022
0.1.0 Mar 13, 2022
0.0.5 Apr 22, 2021
0.0.4 Mar 22, 2021

#498 in Command line utilities

39 downloads per month


620 lines


Crates.io Version Build Status

Tool to assist remapping macOS keyboard keys.

๐Ÿš€ Getting started

Install the tool using Cargo.

cargo install kb-remap

๐Ÿคธ Usage

Running the tool without any options will list the available HID devices.

$ kb-remap --list
Vendor ID  Product ID  Name
---------  ----------  ----------------------------------
0x0        0x0         BTM
0x0        0x0         Headset
0x4c       0x269       Magic Mouse
0x5ac      0x342       Apple Internal Keyboard / Trackpad
0x5ac      0x342       Keyboard Backlight
0xc45      0x7692      USB Keyboard
0x1050     0x407       YubiKey OTP+FIDO+CCID

Usually it's pretty simple to pick out which devices are keyboards. Using the name listed above as --name you can remap any key you want using the --map or --swap options. For example the following remaps capslock to backspace and swaps ยง (section) and ` (backtick) on a the internal macOS keyboard.

$ kb-remap --name "Apple Internal Keyboard / Trackpad" --map capslock:delete --swap '0x64:`'

You can reset the mapping using:

$ kb-remap --name "Apple Internal Keyboard / Trackpad" --reset

If you want you can inspect the raw hidutil command that would be run for a particular command using the --dump option.

$ kb-remap --name "Apple Internal Keyboard / Trackpad" --map capslock:delete --dump

Would output the following:

hidutil property \
    --matching '{"VendorID":1452,"ProductID":834}' \
    --set '{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":30064771129,"HIDKeyboardModifierMappingDst":30064771114}]}'

Specifying keys

The --map and --swap options both expect the source and destination keys to be specified and separated by a ":" (colon).

There are three ways to specify keys:


Some keys you can specify using their name. For example the Return (Enter) key "โŽ" can be specified as "return". These are added on a convenience basis.

Key Code USB Usage ID
Return (Enter) return 0x28
Escape escape 0x29
Delete (Backspace) delete 0x2A
Caps Lock capslock 0x39
Left Control lcontrol 0xE0
Left Shift lshift 0xE1
Left Option loption 0xE2
Left Command lcommand 0xE3
Right Control rcontrol 0xE4
Right Shift rshift 0xE5
Right Option roption 0xE6
Right Command rcommand 0xE7

Additionally, the following special names are available and map multiple keys if they are used.

Keys Code
Left & Right Control control
Left & Right Shift shift
Left & Right Option option
Left & Right Command command


Most typeable keys can be specified using their character. For example: the A key can be specified using "A" or "a". The USB usage ID used will the one that the key corresponds to on a US keyboard.


Any key can be specified by using the USB usage ID in decimal or hex. For example: Z has a usage ID of "29", which can also be specified as "0x1d".

๐Ÿค” Why? How?

Powerful applications to remap macOS keys like Karabiner-Elements are often overkill for simple remappings. Additionally, they can sometimes take a while to support the latest macOS version. I wanted a simple reliable solution.

Instead of a constantly running application kb-remap simply subprocesses to the built-in macOS hidutil command to fetch keyboard information and to remap keys. This remapping does not persist if keyboards are unplugged or if your Mac goes to sleep. kb-remap does not solve this problem for you yet. One option is to install a launchd service to automatically run kb-remap.


Licensed under either of

at your option.


~113K SLoC