Tool to assist remapping macOS keyboard keys.
Install the tool using Cargo.
cargo install kb-remap
To globally remap keys you can just run the tool with one or more --map
or
--swap
options. For example the following remaps capslock to backspace and
swaps § (section) and ` (backtick) on all keyboards.
kb-remap --map capslock:delete --swap '0x64:`'
Reset the mapping using
kb-remap --reset
You can optionally filter which keyboards are remapped by using the --name
option. Use the --list
option to list the available HID devices and their
names.
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
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}]}'
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 |
Function | fn |
|
F1, F2, ..., F12 | f1 , f2 , ..., f12 |
0x3A -> 0x45 |
F13, F14, ..., F24 | f13 , f4 , ..., f24 |
0x68 -> 0x73 |
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 hex. For example: Z has a usage ID of "0x1d".
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 is restarted. kb-remap
does not solve this problem for you yet. One
option is to install a launchd service to automatically run kb-remap
on boot.
This project is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT for details.