Remapping Keys With hidutil on macOS

Sold for macOS, Left-Hand Pad places a dozen keys in a four-column, three-row layout beside two rotary knobs. Apple's built-in hidutil can make simple key substitutions without installing a third-party remapper.

What can hidutil remap without extra software?

Apple's technical note documents a UserKeyMapping property that changes one HID keyboard usage into another. It suits direct substitutions such as exchanging two ordinary keys or converting a pad output into a spare function key. The command does not require special privileges.

The mapping applies at the keyboard-service level rather than providing an application-aware macro system. It is not a good fit for window conditions, tap-versus-hold behavior, text sequences or shell execution. It also does not offer an obvious simple per-device selector in Apple's documented command.

How do you write and apply a remap command?

Identify the source and destination usages, then construct the JSON property shown in Apple's hidutil documentation. Each entry contains a source usage and a destination usage. The value combines the keyboard usage page with the selected key's usage code, so copying a decimal keycode from another tool is unsafe.

Apply one mapping first, then inspect the current state with hidutil property --get UserKeyMapping. Test the pad and the normal keyboard. Because the mapping can affect both when they emit the same usage, do not start with a letter or modifier needed to undo your work.

How do you make the mapping survive a reboot?

Apple states that these remaps are lost after restart or when the last keyboard service disappears. hidutil has no documented save switch. Persistence therefore means rerunning a reviewed command at login, commonly through an administrator-approved script or launch agent.

Keep that script in a stable location, use a minimal environment and log failures. A managed Mac may prohibit login agents even though the hidutil command itself needs no elevated privilege. In that case, accept a manual setup command instead of bypassing policy.

When do you need Karabiner instead?

Use a fuller remapper when only the macropad should change, the rule needs application conditions or a control has different press and hold behavior. Karabiner also provides EventViewer for observing the device before writing a rule. The extra software adds configuration and accessibility permissions, so hidutil remains attractive for a truly global one-to-one change.

The Left-Hand Pad has more controls than a simple global map should claim. Use hidutil for a small reversible substitution, preserve the original property value and test again after disconnects or macOS upgrades. Keep the exact usage values beside a plain-language description so the command can be audited without decoding hexadecimal again.