Karabiner-Elements

https://karabiner-elements.pqrs.org/docs
Admin
Karabiner-Elements is a powerful and flexible keyboard customizer for macOS, allowing users to remap...
Tokens:87,213
Snippets:686
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### karabiner_environment example with PATH and LC_ALL

Source: https://karabiner-elements.pqrs.org/docs/help/advanced-topics/set-environment-variables

Example contents of the karabiner_environment file. Defines environment variables one per line, with '#' for comments and support for expanding existing variables like $HOME.

```plaintext
# Add ~/opt/bin to PATH
PATH=$HOME/opt/bin:$PATH
# Set locale
LC_ALL=C

```

--------------------------------

### open_application JSON example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/software_function/open_application

Example JSON configuration for the open_application software function, specifying the bundle_identifier for Safari. Either bundle_identifier, file_path, or frontmost_application_history_index must be specified.

```json
{
    "to": [
        {
            "software_function": {
                "open_application": { "bundle_identifier": "com.apple.Safari" }
            }
        }
    ]
}
```

--------------------------------

### Example: Put the system to sleep using fn+z

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/software_function/iokit_power_management_sleep_system

Example configuration that triggers the sleep system function when fn+z is pressed. The delay_milliseconds is set to 500, but it is optional and defaults to 500 ms if unspecified.

```json
{
    "description": "Put the system to sleep using fn+z",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "z",
                "modifiers": {
                    "mandatory": ["fn"],
                    "optional": ["caps_lock"]
                }
            },
            "to": [
                {
                    "software_function": {
                        "iokit_power_management_sleep_system": {
                            "delay_milliseconds": 500
                        }
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### mouse_motion_and_wheel_to_key configuration example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/other-types/mouse-motion-and-wheel-to-key

Example JSON configuration for the `mouse_motion_and_wheel_to_key` manipulator. It shows the required `type` and `from.source` fields, optional `modifiers`, `threshold`, `sampling_interval_milliseconds`, `cooldown_milliseconds`, and the `to` object with `up`, `down`, `left`, `right` arrays. The `conditions` field is also shown as optional.

```json
{
    "type": "mouse_motion_and_wheel_to_key",

    "from": {
        "source": "xy",
        "modifiers": {
            "mandatory": [...],
            "optional": [...]
        },
        "threshold": 20,
        "sampling_interval_milliseconds": 100,
        "cooldown_milliseconds": 100
    },

    "to": {
        "up": [...],
        "down": [...],
        "left": [...],
        "right": [...]
    },

    "conditions": ...
}
```

--------------------------------

### Show karabiner_cli help

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Run this command in a terminal to display the help text for karabiner_cli, which lists all available options and examples.

```bash
'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli'
```

--------------------------------

### Multiple identifiers (AND logic) example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/device

Example showing that multiple identifiers within a single entry are joined by 'and'. This condition matches if Vendor ID is 1111 AND Product ID is 2222 AND it is a keyboard.

```json
{
    "type": "device_if",
    "identifiers": [
        {
            "vendor_id": 1111,
            "product_id": 2222,
            "is_keyboard": true
        }
    ]
}
```

--------------------------------

### Multiple bundle identifiers example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/frontmost-application

Example condition that matches if the bundle identifier is either com.apple.Terminal or com.googlecode.iterm2, demonstrating that multiple entries are joined by 'or'.

```json
{
    "type": "frontmost_application_if",
    "bundle_identifiers": [
        "^com\\.apple\\.Terminal$",
        "^com\\.googlecode\\.iterm2$"
    ]
}
```

--------------------------------

### Multiple entries (OR logic) example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/device

Example showing that multiple entries in the identifiers array are joined by 'or'. This condition matches if Vendor ID is 1111 OR 1112.

```json
{
    "type": "device_if",
    "identifiers": [
        {
            "vendor_id": 1111
        },
        {
            "vendor_id": 1112
        }
    ]
}
```

--------------------------------

### Example: Change button4 + mouse movement to scroll

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/other-types/mouse-motion-to-scroll

Complete JSON configuration that changes button4 plus mouse movement to scroll. It uses a basic manipulator to set a variable when button4 is pressed, and a mouse_motion_to_scroll manipulator that activates only when that variable is true. This example demonstrates the recommended pattern of using conditions to avoid always converting mouse movement to scroll.

```json
{
    "description": "Change button4 + mouse movement to scroll",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "pointing_button": "button4",
                "modifiers": { "optional": ["any"] }
            },
            "to": [
                {
                    "set_variable": {
                        "name": "enable_mouse_motion_to_scroll",
                        "value": true,
                        "key_up_value": false
                    }
                }
            ]
        },
        {
            "type": "mouse_motion_to_scroll",
            "from": {
                "modifiers": { "optional": ["any"] }
            },
            "conditions": [
                {
                    "type": "variable_if",
                    "name": "enable_mouse_motion_to_scroll",
                    "value": true
                }
            ]
        }
    ]
}
```

--------------------------------

### Log output for setenv from console_user_server

Source: https://karabiner-elements.pqrs.org/docs/help/advanced-topics/set-environment-variables

Example log output showing the environment variables defined in karabiner_environment. Note that these variables are logged, so avoid storing sensitive information.

```plaintext
[info] [console_user_server] setenv: PATH = /Users/tekezo/opt/bin:/usr/bin:/bin:/usr/sbin:/sbin
[info] [console_user_server] setenv: LC_ALL = C

```

--------------------------------

### karabiner_cli --show-settings-window-guidance

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Shows the settings window guidance state.

```APIDOC
## karabiner_cli --show-settings-window-guidance

### Description
Show the settings window guidance state.

### Command
`karabiner_cli --show-settings-window-guidance`

```

--------------------------------

### karabiner_cli --help

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Prints help information.

```APIDOC
## karabiner_cli --help

### Description
Print help.

### Command
`karabiner_cli --help`

```

--------------------------------

### Start socat server for testing send_user_command

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/send-user-command

Starts a socat server that receives UNIX domain datagrams and prints them to stdout. Useful for verifying that your custom server can receive messages from `send_user_command`.

```bash
socat -u UNIX-RECVFROM:/tmp/karabiner-elements-user-command-server.sock,fork STDOUT
```

--------------------------------

### karabiner_cli help output

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Output of running karabiner_cli with no arguments, showing the full usage and available options.

```text
A command line utility of Karabiner-Elements
Usage:
  karabiner_cli [OPTION...] positional parameters

      --select-profile arg      Select a profile by name
      --show-current-profile-name
                                Show current profile name
      --list-profile-names      Show all profile names
      --list-connected-devices  Show all connected devices
      --list-system-variables   Show all system variables
      --list-multitouch-extension-variables
                                Show all multitouch extension variables
      --watch-multitouch-extension-variables [=polling-interval-in-milliseconds(=500)]
                                Watch multitouch extension variables and
                                print all of them in one line whenever any
                                variable changes
      --set-variables arg       Json string: {[key: string]:
                                number|boolean|string}
      --set-variables-from-stdin
                                Read one variables JSON object per line
                                from stdin
      --copy-current-profile-to-system-default-profile
                                Copy the current profile to system default
                                profile
      --remove-system-default-profile
                                Remove the system default profile
      --show-settings-window-guidance
                                Show the settings window guidance state
      --lint-complex-modifications glob-patterns
                                Validate complex modifications JSON and
                                JavaScript files for distribution
      --format-json glob-patterns
                                Format json files
      --eval-js glob-patterns   Run javascript files using Duktape
      --eval-js-to-json file    Evaluate a JavaScript file and print the
                                returned object as JSON
      --version                 Displays version
      --version-number          Displays version_number
      --help                    Print help
      --silent                  Suppress messages
      --verbose                 Print variables successfully set by
                                --set-variables-from-stdin

Examples:
  karabiner_cli --select-profile 'Default profile'
  karabiner_cli --show-current-profile-name
  karabiner_cli --list-profile-names
  karabiner_cli --set-variables '{"cli_flag1":1, "cli_flag2":2}'
  printf '{"cli_flag1":1}\n{"cli_flag2":2}\n' | karabiner_cli --set-variables-from-stdin --verbose
```

--------------------------------

### event_changed_if condition example

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/event-changed

Example of using event_changed_if condition in a basic manipulator. Changes tab to return_or_enter only if the tab key is the physical tab key, ignoring keys modified by simple modifications.

```json
{
    "description": "Change tab key to return_or_enter if the tab key is the physical tab key",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "tab",
                "modifiers": { "optional": ["any"] }
            },
            "to": [{ "key_code": "return_or_enter" }],
            "conditions": [
                {
                    "type": "event_changed_if",
                    "value": false
                }
            ]
        }
    ]
}
```

--------------------------------

### JSON example: simultaneous a+s+d to mission_control

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/from/simultaneous

Defines a basic manipulator that changes the simultaneous press of a, s, and d to the mission_control key. The `modifiers` field is set to `optional: ["any"]` to allow any modifiers. This example is used to demonstrate the `simultaneous` manipulator.

```json
{
    "description": "Pressing the a,s,d keys simultaneously launches Mission Control",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "simultaneous": [
                    { "key_code": "a" },
                    { "key_code": "s" },
                    { "key_code": "d" }
                ],
                "modifiers": { "optional": ["any"] }
            },
            "to": [{ "apple_vendor_keyboard_key_code": "mission_control" }]
        }
    ]
}
```

--------------------------------

### List all profile names

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

List all available profile names.

```bash
'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --list-profile-names
```

--------------------------------

### Open files in Finder using the return key

Source: https://karabiner-elements.pqrs.org/docs/json/typical-complex-modifications-examples

Maps return_or_enter to Command+O in Finder, but only when the focused UI element is not a text field, using expression_unless with accessibility.focused_ui_element.role_string.

```json
{
    "description": "Open files in Finder using the return key",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "return_or_enter",
                "modifiers": { "optional": ["caps_lock"] }
            },
            "to": [
                {
                    "key_code": "o",
                    "modifiers": ["left_command"]
                }
            ],
            "conditions": [
                {
                    "type": "frontmost_application_if",
                    "bundle_identifiers": ["^com\\.apple\\.finder$"]
                },
                {
                    "type": "expression_unless",
                    "expression": "accessibility.focused_ui_element.role_string like 'AXText*'"
                }
            ]
        }
    ]
}
```

--------------------------------

### device_if condition example: caps_lock to escape on Apple keyboards

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/device

Example of a basic manipulator that changes caps_lock to escape only on Apple keyboards (vendor IDs 1452 or 76) or built-in keyboards. Uses the device_if condition with multiple identifiers.

```json
{
    "description": "Change caps_lock to escape on Apple keyboards",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "caps_lock",
                "modifiers": { "optional": ["any"] }
            },
            "to": [{ "key_code": "escape" }],
            "conditions": [
                {
                    "type": "device_if",
                    "identifiers": [
                        { "vendor_id": 1452 },
                        { "vendor_id": 76 },
                        { "is_built_in_keyboard": true }
                    ]
                }
            ]
        }
    ]
}
```

--------------------------------

### karabiner_cli --verbose

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Prints variables successfully set by --set-variables-from-stdin.

```APIDOC
## karabiner_cli --verbose

### Description
Print variables successfully set by --set-variables-from-stdin.

### Command
`karabiner_cli --verbose`

```

--------------------------------

### Example: Using to.conditions inside to_if_invoked and to_if_canceled

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/to-conditions

This example shows how to use `conditions` inside `to_if_invoked` and `to_if_canceled` to prevent the `q` key from being sent via `to_delayed_action` when the `escape` key is pressed. It uses a variable `q pressed` to track the state. The configuration is a JSON array of manipulators.

```json
{
    "description": "Change double press of q to escape",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "q",
                "modifiers": { "optional": ["any"] }
            },
            "to": [
                { "set_variable": { "name": "q pressed", "value": false } },
                { "key_code": "escape" }
            ],
            "conditions": [
                { "type": "variable_if", "name": "q pressed", "value": true }
            ]
        },
        {
            "type": "basic",
            "from": {
                "key_code": "q",
                "modifiers": { "optional": ["any"] }
            },
            "to": [{ "set_variable": { "name": "q pressed", "value": true } }],
            "to_delayed_action": {
                "to_if_invoked": [
                    {
                        "key_code": "q",
                        "conditions": [
                            {
                                "type": "variable_if",
                                "name": "q pressed",
                                "value": true
                            }
                        ]
                    },
                    { "set_variable": { "name": "q pressed", "value": false } }
                ],
                "to_if_canceled": [
                    {
                        "key_code": "q",
                        "conditions": [
                            {
                                "type": "variable_if",
                                "name": "q pressed",
                                "value": true
                            }
                        ]
                    },
                    { "set_variable": { "name": "q pressed", "value": false } }
                ]
            }
        }
    ]
}
```

--------------------------------

### Example: Mouse cursor and scroll with right_shift and right_command

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/mouse-key

Full Karabiner-Elements configuration that maps right_shift + arrows to mouse cursor movement, right_shift + f to fast movement, right_shift + v to click, and right_command + arrows to scrolling. Uses mouse_key values of 1536 for movement and 32 for wheel scrolling. Speed and scroll direction depend on System Settings > Mouse configuration.

```json
{
    "description": "Move mouse cursor by right_shift + arrows, scroll by right_command + arrows",
    "manipulators": [
        // y
        {
            "type": "basic",
            "from": {
                "key_code": "up_arrow",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "mouse_key": { "y": -1536 } }]
        },
        {
            "type": "basic",
            "from": {
                "key_code": "down_arrow",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "mouse_key": { "y": 1536 } }]
        },

        // x
        {
            "type": "basic",
            "from": {
                "key_code": "left_arrow",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "mouse_key": { "x": -1536 } }]
        },
        {
            "type": "basic",
            "from": {
                "key_code": "right_arrow",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "mouse_key": { "x": 1536 } }]
        },

        // speed_multiplier
        {
            "type": "basic",
            "from": {
                "key_code": "f",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "mouse_key": { "speed_multiplier": 4.0 } }]
        },

        // click
        {
            "type": "basic",
            "from": {
                "key_code": "v",
                "modifiers": { "mandatory": "right_shift", "optional": ["any"] }
            },
            "to": [{ "pointing_button": "button1" }]
        },

        // vertical_wheel
        {
            "type": "basic",
            "from": {
                "key_code": "up_arrow",
                "modifiers": {
                    "mandatory": "right_command",
                    "optional": ["any"]
                }
            },
            "to": [{ "mouse_key": { "vertical_wheel": -32 } }]
        },
        {
            "type": "basic",
            "from": {
                "key_code": "down_arrow",
                "modifiers": {
                    "mandatory": "right_command",
                    "optional": ["any"]
                }
            },
            "to": [{ "mouse_key": { "vertical_wheel": 32 } }]
        },

        // horizontal_wheel
        {
            "type": "basic",
            "from": {
                "key_code": "left_arrow",
                "modifiers": {
                    "mandatory": "right_command",
                    "optional": ["any"]
                }
            },
            "to": [{ "mouse_key": { "horizontal_wheel": 32 } }]
        },
        {
            "type": "basic",
            "from": {
                "key_code": "right_arrow",
                "modifiers": {
                    "mandatory": "right_command",
                    "optional": ["any"]
                }
            },
            "to": [{ "mouse_key": { "horizontal_wheel": -32 } }]
        }
    ]
}
```

--------------------------------

### Advanced example: Conditions evaluated before first event

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/to-conditions

This example demonstrates that conditions in `to` are evaluated when the first event in the sequence is processed. Even if a variable is set earlier in the `to` array, the condition will not see the updated value. The comment in the code explains that the condition will return false because `example_flag` is not yet true at evaluation time.

```json
{
    "description": "to.conditions example",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "escape",
                "modifiers": { "optional": ["any"] }
            },
            "to": [
                {
                    "set_variable": {
                        "name": "example_flag",
                        "value": true
                    }
                },
                {
                    "key_code": "spacebar",
                    "conditions": [
                        // Because this condition are evaluated before the first event is processed,
                        // the value of example_flag is not true at that stage, so the evaluation will return false.
                        {
                            "type": "variable_if",
                            "name": "example_flag",
                            "value": true
                        }
                    ]
                },
                {
                    "set_variable": {
                        "name": "example_flag",
                        "value": false
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### karabiner_cli --list-connected-devices

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Lists all connected devices.

```APIDOC
## karabiner_cli --list-connected-devices

### Description
Show all connected devices.

### Command
`karabiner_cli --list-connected-devices`

```

--------------------------------

### karabiner_cli --list-system-variables

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Lists all system variables.

```APIDOC
## karabiner_cli --list-system-variables

### Description
Show all system variables.

### Command
`karabiner_cli --list-system-variables`

```

--------------------------------

### karabiner_cli --version

Source: https://karabiner-elements.pqrs.org/docs/manual/misc/command-line-interface

Displays the version.

```APIDOC
## karabiner_cli --version

### Description
Displays version.

### Command
`karabiner_cli --version`

```

--------------------------------

### Multiple sticky modifiers

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/sticky-modifier

Example showing how to activate multiple sticky modifiers by putting multiple sticky_modifier entries in the to array.

```json
{
    "to": [
        {
            "sticky_modifier": {
                "left_control": "toggle"
            }
        },
        {
            "sticky_modifier": {
                "left_shift": "toggle"
            }
        }
    ]
}
```

--------------------------------

### Change right_shift to sticky modifier

Source: https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/to/sticky-modifier

Example configuration that changes right_shift to a sticky modifier using to_if_alone with sticky_modifier set to toggle.

```json
{
    "description": "Change right_shift to sticky modifier",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "right_shift",
                "modifiers": { "optional": ["any"] }
            },
            "to": [{ "key_code": "right_shift" }],
            "to_if_alone": [{ "sticky_modifier": { "right_shift": "toggle" } }]
        }
    ]
}
```

--------------------------------

### Machine-specific settings in karabiner.json

Source: https://karabiner-elements.pqrs.org/docs/privacy

Example of machine-specific settings stored in karabiner.json, using a karabiner_machine_identifier (krbn-...). The identifier is random and safe to share.

```json
{
    "machine_specific": {
        "krbn-818632bf-2a88-4ac0-ad0b-4524721c217b": {
            "enable_multitouch_extension": true,
            "external_editor_path": "/Applications/Visual Studio Code.app"
        }
    }
}
```
Tokens:
Raw