# kb-remap
[](https://crates.io/crates/kb-remap)
[](https://github.com/rossmacarthur/kb-remap/actions/workflows/build.yaml)
Tool to assist remapping macOS keyboard keys.
## 🚀 Getting started
Install the tool using Cargo.
```sh
cargo install kb-remap
```
## 🤸 Usage
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.
```sh
kb-remap --map capslock:delete --swap '0x64:`'
```
Reset the mapping using
```sh
kb-remap --reset
```
### Filtering keyboards
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.
```sh
kb-remap --list
```
```text
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.
```sh
kb-remap --name "Apple Internal Keyboard / Trackpad" --map capslock:delete --swap '0x64:`'
```
You can reset the mapping using:
```sh
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:
```text
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:
### Name
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.
| 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.
| Left & Right Control | `control` |
| Left & Right Shift | `shift` |
| Left & Right Option | `option` |
| Left & Right Command | `command` |
### Character
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.
### Number
Any key can be specified by using the USB usage ID in hex. For example: Z has a
usage ID of "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 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.
[Karabiner-Elements]: https://github.com/pqrs-org/Karabiner-Elements
## License
This project is distributed under the terms of both the MIT license and the
Apache License (Version 2.0).
See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.