app.keyboard - Keyboard Simulation API

Simulates keyboard input and shortcut key operations.

Permission: Requires keyboard declared in the manifest (L3 dangerous) System requirement: Requires Accessibility Permission

Methods

app.keyboard.type(text)

Simulates keyboard text input. Types character by character, supporting Unicode characters.

Parameters:

• text (string) - Text to type

Returns: boolean, error

local ok, err = app.keyboard.type("Hello, World!")

-- Type Chinese characters
local ok, err = app.keyboard.type("你好世界")

app.keyboard.pressKey(key, modifiers?)

Simulates pressing a single key.

Parameters:

• key (string) - Key name (see key list below)
• modifiers (array, optional) - Modifier key array

Returns: boolean, error

-- Press Return key
app.keyboard.pressKey("return")

-- Press Tab
app.keyboard.pressKey("tab")

-- With modifier keys
app.keyboard.pressKey("a", {"cmd", "shift"})

app.keyboard.hotkey(modifiers, key)

Simulates a keyboard shortcut combination.

Parameters:

• modifiers (array) - Modifier key array
• key (string) - Key name

Returns: boolean, error

-- Cmd+C (Copy)
app.keyboard.hotkey({"cmd"}, "c")

-- Cmd+Shift+S (Save As)
app.keyboard.hotkey({"cmd", "shift"}, "s")

-- Ctrl+Alt+Delete
app.keyboard.hotkey({"ctrl", "alt"}, "delete")

Key Names

Letters and Numbers

a-z, 0-9

Function Keys

Arrow Keys

left, right, up, down

Function Keys

f1 - f12

Navigation Keys

home, end, pageup, pagedown

Symbol Keys

-, =, [, ], ;, ', ,, ., /, \, `

Modifier Keys

Examples

Auto-fill a form

function MyPlugin:handleAutoFill(context)
    -- Switch to the target app
    app.keyboard.hotkey({"cmd"}, "tab")
    app.thread.sleep(0.5)

    -- Type username
    app.keyboard.type("admin@example.com")
    app.keyboard.pressKey("tab")  -- Move to the next field

    -- Type password
    app.keyboard.type("password123")
    app.keyboard.pressKey("return")  -- Submit
end

Quick actions

function MyPlugin:handleQuickAction(context)
    -- Select All
    app.keyboard.hotkey({"cmd"}, "a")
    app.thread.sleep(0.1)

    -- Copy
    app.keyboard.hotkey({"cmd"}, "c")
    app.thread.sleep(0.1)

    -- New Document
    app.keyboard.hotkey({"cmd"}, "n")
    app.thread.sleep(0.5)

    -- Paste
    app.keyboard.hotkey({"cmd"}, "v")
end

Notes

1. Accessibility Permission: On first use, the user will be prompted to grant Accessibility Permission, which must be manually allowed in System Settings
2. Permission level: L3 dangerous; requires keyboard permission declared in the manifest
3. Input delay: type() inputs character by character with approximately 10ms between each character
4. Focus requirement: Keyboard events are sent to the currently focused window; ensure the target app is in the foreground