Custom Actions

The user may define a list of custom actions, which are shell commands bound to a specific key combination. These actions always have preference over those defined in Default Keybinds when they are bound to the same key combination.

Example

# ~/.config/miracle-wm/config.yaml

custom_actions:           # Set meta + D to open wofi
  - command: wofi --show=drun
    action: down
    modifiers:
      - primary
    key: d

Schema

A list of custom keybind actions:

custom_actions:
  - command: <string>
    action: <up|down|repeat|modifiers>
    modifiers: <Modifier[]>
    key: <KeysymName>
    allow_on_lockscreen: <bool>   # optional

Properties

command

required type: String

The shell command to execute when the keybind is triggered.

action

required type: up | down | repeat | modifiers

The key action that triggers the command:

• up — Triggered when the key is released
• down — Triggered when the key is pressed
• repeat — Triggered repeatedly while the key is held
• modifiers — Triggered when modifiers change

modifiers

required type: List of modifier keys

Modifier keys that must be held for the command to execute. Available modifiers:

Name	Description
primary	the key defined by the Action Key
alt	Any alt key
alt_left	The left alt key only
alt_right	The right alt key only
shift	Any shift key
shift_left	The left shift key only
shift_right	The right shift key only
ctrl	Any ctrl key
ctrl_left	The left ctrl key only
ctrl_right	The right ctrl key only
meta	The super or windows key
meta_left	The left super or windows key only
meta_right	The right super or windows key only
sym	The sym key
function	The fn key
caps_lock	The caps lock key
num_lock	The num lock key
scroll_lock	The scroll lock key

key

required type: KeysymName

Name of the XKB keysym that the action responds to. See the xkbcommon keysym list for available names (e.g., Return, z, Up).

For shifted characters, use the shifted keysym directly instead of combining a lowercase key with the shift modifier. For example, use Q instead of q + shift, and use exclam instead of 1 + shift.

allow_on_lockscreen

optional type: Boolean default: false

Whether the command may run while the session is locked. While the lock screen is up, every other key binding (including the Default Keybinds) is ignored and the key goes to the lock screen instead. This is useful for media, volume and brightness keys:

custom_actions:
  - command: wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
    action: down
    modifiers: []
    key: XF86AudioRaiseVolume
    allow_on_lockscreen: true

Warning

Anything bound with allow_on_lockscreen: true can be run by whoever is at the keyboard of a locked session. Never allow a command that unlocks the session, shows its contents or opens a shell.

Default

custom_actions: []