app.hotkey - Global Hotkey API

Registers and manages global keyboard shortcuts. Plugins can respond to shortcuts in the background.

Permission: L3 dangerous (requires Accessibility Permission)

Methods

app.hotkey.bind(mods, key, callback)

Registers a global shortcut.

Parameters:

• mods (array) - Modifier key array: "cmd", "shift", "alt"/"option", "ctrl"/"control", "fn"
• key (string) - Key name: "a"-"z", "0"-"9", "f1"-"f12", "space", "return", "tab", "escape", "left", "right", "up", "down", "delete", "home", "end", "pageup", "pagedown", etc.
• callback (function) - Callback function executed when the shortcut is triggered

Returns: hotkeyHandle - The hotkey handle; nil, error on failure

This is a handle table, not a string id. Concatenating it raises attempt to concatenate a table value. Its methods: disable() / enable() / enabled() / unbind().

-- Register Cmd+Shift+T
local hk, err = app.hotkey.bind({"cmd", "shift"}, "t", function()
    app.notification.show("Hotkey", "Cmd+Shift+T was pressed!")
end)

-- Register Ctrl+Alt+Space
app.hotkey.bind({"ctrl", "alt"}, "space", function()
    app.log.info("Quick launch")
end)

handle:unbind()

Unregisters the specified shortcut.

Returns: boolean, error

local ok, err = hk:unbind()

handle:enabled()

Whether this hotkey is currently enabled.

Returns: boolean

if not hk:enabled() then
    hk:enable()
end

app.hotkey.unbindAll()

Unregisters all shortcuts for the current plugin.

Returns: boolean

app.hotkey.unbindAll()

app.hotkey.list()

Lists registered shortcuts for the current plugin.

Returns: array<table> - Each item contains:

• id (string) - Hotkey ID
• key (string) - Key name
• mods (array) - Modifier key array
• enabled (boolean) - Whether it is enabled

local hotkeys = app.hotkey.list()
for _, hk in ipairs(hotkeys) do
    local mods = table.concat(hk.mods, "+")
    app.log.info(hk.id .. ": " .. mods .. "+" .. hk.key .. " enabled=" .. tostring(hk.enabled))
end

handle:enable()

Enables a previously disabled shortcut.

Returns: boolean, error

handle:disable()

Temporarily disables a shortcut (without removing the registration).

Returns: boolean, error

-- Temporarily disable
hk:disable()
-- ... after some operations ...
-- Re-enable
hk:enable()

Description

• Each plugin can register up to 20 shortcuts
• Requires macOS Accessibility Permission (System Settings > Privacy & Security > Accessibility)
• The same key combination cannot be registered by multiple plugins
• Shortcuts are active across all windows and other applications
• Shortcuts are automatically unregistered when the plugin is unloaded
• Callbacks are invoked on the plugin execution queue (thread-safe)
• Shortcuts do not consume the original event; other applications can still receive it

Examples

Quick action panel

function MyPlugin:init()
    -- Cmd+Shift+K to open quick actions
    app.hotkey.bind({"cmd", "shift"}, "k", function()
        local items = {
            {text = "New File", id = "new"},
            {text = "Open Terminal", id = "terminal"},
            {text = "Copy Path", id = "copypath"},
        }
        local selected = app.chooser.show({
            title = "Quick Actions",
            items = items,
        })
        if selected then
            self:executeAction(selected[1])
        end
    end)
end