{"id":18099945,"url":"https://github.com/rossmacarthur/kb-remap","last_synced_at":"2025-04-09T17:24:05.230Z","repository":{"id":57210151,"uuid":"349012933","full_name":"rossmacarthur/kb-remap","owner":"rossmacarthur","description":"⌨️ Tool to remap macOS keyboard keys","archived":false,"fork":false,"pushed_at":"2025-02-08T16:15:52.000Z","size":124,"stargazers_count":32,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"trunk","last_synced_at":"2025-04-02T11:52:39.786Z","etag":null,"topics":["cli","keyboard","macos","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rossmacarthur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-18T09:27:45.000Z","updated_at":"2025-03-16T00:41:57.000Z","dependencies_parsed_at":"2023-11-18T00:13:25.125Z","dependency_job_id":"a43b5a43-7f0b-45cf-b715-f1943329f756","html_url":"https://github.com/rossmacarthur/kb-remap","commit_stats":{"total_commits":52,"total_committers":1,"mean_commits":52.0,"dds":0.0,"last_synced_commit":"a59d12bfe8df75dc453321bd7b40b5415bd6a5f8"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rossmacarthur%2Fkb-remap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rossmacarthur%2Fkb-remap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rossmacarthur%2Fkb-remap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rossmacarthur%2Fkb-remap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rossmacarthur","download_url":"https://codeload.github.com/rossmacarthur/kb-remap/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075519,"owners_count":21043602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","keyboard","macos","rust"],"created_at":"2024-10-31T21:11:51.642Z","updated_at":"2025-04-09T17:24:05.209Z","avatar_url":"https://github.com/rossmacarthur.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kb-remap\n\n[![Crates.io Version](https://badgers.space/crates/version/kb-remap)](https://crates.io/crates/kb-remap)\n[![Build Status](https://badgers.space/github/checks/rossmacarthur/kb-remap/trunk?label=build)](https://github.com/rossmacarthur/kb-remap/actions/workflows/build.yaml)\n\nTool to assist remapping macOS keyboard keys.\n\n## 🚀 Getting started\n\nInstall the tool using Cargo.\n\n```sh\ncargo install kb-remap\n```\n\n## 🤸 Usage\n\nTo globally remap keys you can just run the tool with one or more `--map` or\n`--swap` options. For example the following remaps capslock to backspace and\nswaps § (section) and ` (backtick) on all keyboards.\n```sh\nkb-remap --map capslock:delete --swap '0x64:`'\n```\n\nReset the mapping using\n```sh\nkb-remap --reset\n```\n\n### Filtering keyboards\n\nYou can optionally filter which keyboards are remapped by using the `--name`\noption. Use the `--list` option to list the available HID devices and their\nnames.\n\n```sh\nkb-remap --list\n```\n```text\nVendor ID  Product ID  Name\n---------  ----------  ----------------------------------\n0x0        0x0         BTM\n0x0        0x0         Headset\n0x4c       0x269       Magic Mouse\n0x5ac      0x342       Apple Internal Keyboard / Trackpad\n0x5ac      0x342       Keyboard Backlight\n0xc45      0x7692      USB Keyboard\n0x1050     0x407       YubiKey OTP+FIDO+CCID\n```\n\nUsing the name listed above as `--name` you can remap any key you want using the\n`--map` or `--swap` options. For example the following remaps capslock to\nbackspace and swaps § (section) and ` (backtick) on a the internal macOS\nkeyboard.\n```sh\nkb-remap --name \"Apple Internal Keyboard / Trackpad\" --map capslock:delete --swap '0x64:`'\n```\n\nYou can reset the mapping using:\n```sh\nkb-remap --name \"Apple Internal Keyboard / Trackpad\" --reset\n```\n\nIf you want you can inspect the raw `hidutil` command that would be run for a\nparticular command using the `--dump` option.\n```\nkb-remap --name \"Apple Internal Keyboard / Trackpad\" --map capslock:delete --dump\n```\n\nWould output the following:\n```text\nhidutil property \\\n    --matching '{\"VendorID\":1452,\"ProductID\":834}' \\\n    --set '{\"UserKeyMapping\":[{\"HIDKeyboardModifierMappingSrc\":30064771129,\"HIDKeyboardModifierMappingDst\":30064771114}]}'\n```\n\n## Specifying keys\n\nThe `--map` and `--swap` options both expect the source and destination keys to\nbe specified and separated by a \":\" (colon).\n\nThere are three ways to specify keys:\n\n### Name\n\nSome keys you can specify using their name. For example the Return (Enter) key\n\"⏎\" can be specified as \"return\". These are added on a convenience basis.\n\n| Key                | Code                    | USB Usage Page | USB Usage ID |\n| ------------------ | ----------------------- | -------------: | -----------: |\n| Return (Enter)     | `return`                |           0x07 |         0x28 |\n| Escape             | `escape`                |           0x07 |         0x29 |\n| Delete (Backspace) | `delete`                |           0x07 |         0x2A |\n| Caps Lock          | `capslock`              |           0x07 |         0x39 |\n| Left Control       | `lcontrol`              |           0x07 |         0xE0 |\n| Left Shift         | `lshift`                |           0x07 |         0xE1 |\n| Left Option        | `loption`               |           0x07 |         0xE2 |\n| Left Command       | `lcommand`              |           0x07 |         0xE3 |\n| Right Control      | `rcontrol`              |           0x07 |         0xE4 |\n| Right Shift        | `rshift`                |           0x07 |         0xE5 |\n| Right Option       | `roption`               |           0x07 |         0xE6 |\n| Right Command      | `rcommand`              |           0x07 |         0xE7 |\n| Function           | `fn`                    |           0xFF |         0x03 |\n| F1, F2, ..., F12   | `f1`, `f2`, ..., `f12`  |           0x07 | 0x3A -\u003e 0x45 |\n| F13, F14, ..., F24 | `f13`, `f4`, ..., `f24` |           0x07 | 0x68 -\u003e 0x73 |\n\nAdditionally, the following special names are available and map multiple keys if\nthey are used.\n\n| Keys                 | Code      |\n| -------------------- | --------- |\n| Left \u0026 Right Control | `control` |\n| Left \u0026 Right Shift   | `shift`   |\n| Left \u0026 Right Option  | `option`  |\n| Left \u0026 Right Command | `command` |\n\n### Character\n\nMost typeable keys can be specified using their character. For example: the A\nkey can be specified using \"A\" or \"a\". The USB Usage ID used will the one that\nthe key corresponds to on a US keyboard.\n\n### Number\n\nAny key can be specified by using the USB Usage ID in hex. For example: Z has a\nUsage ID of \"0x1d\", in this case the USB Usage Page is assumed to be `0x07`\n(keyboard). You can also specify the Usage Page and the Usage ID together like\nthis: \"0x7_0000_001D\".\n\n## 🤔 Why? How?\n\nPowerful applications to remap macOS keys like [Karabiner-Elements] are often\noverkill for simple remappings. Additionally, they can sometimes take a while to\nsupport the latest macOS version. I wanted a simple reliable solution.\n\nInstead of a constantly running application `kb-remap` simply subprocesses to\nthe built-in macOS  `hidutil` command to fetch keyboard information and to remap\nkeys. This remapping does not persist if keyboards are unplugged or **if your\nMac is restarted**. `kb-remap` does not solve this problem for you yet. One\noption is to install a launchd service to automatically run `kb-remap` on boot.\n\n[Karabiner-Elements]: https://github.com/pqrs-org/Karabiner-Elements\n\n## License\n\nThis project is distributed under the terms of both the MIT license and the\nApache License (Version 2.0).\n\nSee [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frossmacarthur%2Fkb-remap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frossmacarthur%2Fkb-remap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frossmacarthur%2Fkb-remap/lists"}