Configure and manage Karabiner-Elements key remapping...
Manage Karabiner-Elements configuration for macOS keyboard customization including key remapping, complex modifications, and profile management.
~/.config/karabiner/karabiner.json/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli~/.config/karabiner/assets/complex_modifications/All modifications are limited to the internal MacBook keyboard using device_if conditions with is_built_in_keyboard: true.
karabiner_cli --select-profile 'Default profile'
karabiner_cli --show-current-profile-name
karabiner_cli --list-profile-names
List connected devices:
karabiner_cli --list-connected-devices
Returns JSON with device information:
device_id: unique device identifierdevice_identifiers: keyboard/pointing device flags, vendor/product IDsis_built_in_keyboard/is_built_in_pointing_device: built-in device flagsmanufacturer, product: device name and manufacturertransport: connection type (USB, Bluetooth, FIFO, Audio)Useful for finding vendor_id and product_id for device-specific mappings.
List system variables:
karabiner_cli --list-system-variables
Shows current system state variables:
system.now.milliseconds: current timestampsystem.scroll_direction_is_natural: natural scrolling enabledsystem.use_fkeys_as_standard_function_keys: function key behaviorsystem.temporarily_ignore_all_devices: temporary disable flagSet variables for complex modifications:
karabiner_cli --set-variables '{"cli_flag1":1, "cli_flag2":2}'
Use --silent flag to suppress output.
Run JavaScript files:
karabiner_cli --eval-js path/to/script.js
Executes JavaScript using Duktape engine. Useful for generating or manipulating complex modifications programmatically.
Lint configuration:
karabiner_cli --lint-complex-modifications ~/.config/karabiner/karabiner.json
Format JSON:
karabiner_cli --format-json ~/.config/karabiner/karabiner.json
Copy profile to system default (requires admin):
sudo karabiner_cli --copy-current-profile-to-system-default-profile
Remove system default profile:
sudo karabiner_cli --remove-system-default-profile
karabiner_cli --version
karabiner_cli --version-number
{
"profiles": [
{
"name": "Default profile",
"selected": true,
"complex_modifications": { "rules": [...] },
"devices": [...],
"simple_modifications": [...],
"virtual_hid_keyboard": { "keyboard_type_v2": "ansi" }
}
]
}
{
"description": "Description of the rule",
"manipulators": [
{
"type": "basic",
"from": {
"key_code": "h",
"modifiers": { "mandatory": ["left_option"] }
},
"to": { "key_code": "left_arrow" }
}
]
}
Tap vs hold:
{
"from": { "key_code": "return_or_enter" },
"to_if_alone": [{ "key_code": "return_or_enter" }],
"to_if_held_down": [{
"key_code": "left_shift",
"modifiers": ["right_shift", "left_control", "left_option"]
}],
"parameters": {
"basic.to_if_held_down_threshold_milliseconds": 200
}
}
Delayed actions:
{
"to_delayed_action": {
"to_if_canceled": [{ "key_code": "return_or_enter" }]
},
"parameters": {
"basic.to_delayed_action_delay_milliseconds": 200
}
}
{
"identifiers": {
"is_keyboard": true,
"product_id": 834,
"vendor_id": 1452
},
"simple_modifications": [
{
"from": { "key_code": "fn" },
"to": [{ "key_code": "escape" }]
}
]
}
Special device options:
ignore: true - ignore this devicedisable_built_in_keyboard_if_exists: true - disable built-in when this device connectedtreat_as_built_in_keyboard: true - treat as built-in keyboardmanipulate_caps_lock_led: false - don't manipulate caps lock LEDleft_command, right_commandleft_control, right_controlleft_shift, right_shiftleft_option, right_optioncaps_lock, fnreturn_or_enter, escape, delete_or_backspacetab, spacebarup_arrow, down_arrow, left_arrow, right_arrowpage_up, page_down, home, end{
"modifiers": {
"mandatory": ["left_option"],
"optional": ["caps_lock", "any"]
}
}
{
"description": "caps lock to escape",
"manipulators": [{
"type": "basic",
"from": { "key_code": "caps_lock" },
"to": [{ "key_code": "escape" }]
}]
}
{
"description": "opt+h to left arrow",
"manipulators": [{
"type": "basic",
"from": {
"key_code": "h",
"modifiers": { "mandatory": ["left_option"] }
},
"to": [{ "key_code": "left_arrow" }]
}]
}
{
"description": "return to hyper when held",
"manipulators": [{
"type": "basic",
"from": { "key_code": "return_or_enter" },
"to_if_alone": [{ "key_code": "return_or_enter" }],
"to_if_held_down": [{
"key_code": "left_shift",
"modifiers": ["right_shift", "left_control", "left_option"],
"repeat": false
}],
"parameters": {
"basic.to_if_held_down_threshold_milliseconds": 200
}
}]
}
After editing karabiner.json:
karabiner_cli --lint-complex-modifications to validate~/.config/karabiner/karabiner.jsonprofiles[0].complex_modifications.rules{
"conditions": [
{
"identifiers": [
{
"is_built_in_keyboard": true
}
],
"type": "device_if"
}
]
}
Use device_if conditions to limit modifications to specific devices. The is_built_in_keyboard flag targets only the internal MacBook keyboard, ignoring all external keyboards.
is_built_in_keyboard: Internal MacBook keyboardis_pointing_device: Trackpads and micevendor_id + product_id: Specific device by identifiersdevice_unless: Inverse condition (apply to all except specified devices)Current setup:
killall Karabiner-Elements && open -a Karabiner-Elementsidentifiers match in EventVieweris_keyboard: true is setkarabiner_cli --list-profile-names
karabiner_cli --show-current-profile-name
karabiner_cli --select-profile 'ProfileName'
