app.applescript - AppleScript API

Execute AppleScript scripts to interact with macOS system and applications.

Methods

app.applescript.execute(script)

Execute AppleScript code.

Parameters:

• script (string) - AppleScript code

Returns: string|nil, string|nil - result and error message

-- Simple script
local result, err = app.applescript.execute([[
    display dialog "Hello World"
]])

-- Get Finder information
local result, err = app.applescript.execute([[
    tell application "Finder"
        get name of front window
    end tell
]])
if result then
    app.log.info("Window name: " .. result)
end

app.applescript.executeFile(path)

Execute an AppleScript file.

Parameters:

• path (string) - Script file path (.scpt or .applescript)

Returns: string|nil, string|nil - result and error message

local result, err = app.applescript.executeFile("/path/to/script.scpt")

Examples

Finder Operations

-- Get files selected in Finder
local script = [[
    tell application "Finder"
        set selectedItems to selection
        set pathList to {}
        repeat with itemRef in selectedItems
            set end of pathList to POSIX path of (itemRef as alias)
        end repeat
        return pathList
    end tell
]]
local paths = app.applescript.execute(script)

-- Set file comment
local function setComment(path, comment)
    local script = string.format([[
        tell application "Finder"
            set theFile to POSIX file "%s" as alias
            set comment of theFile to "%s"
        end tell
    ]], path, comment)
    return app.applescript.execute(script)
end

Application Control

-- Check if an application is running
local function isAppRunning(appName)
    local script = string.format([[
        tell application "System Events"
            return (name of processes) contains "%s"
        end tell
    ]], appName)
    return app.applescript.execute(script)
end

-- Activate an application
local function activateApp(appName)
    local script = string.format([[
        tell application "%s" to activate
    ]], appName)
    app.applescript.execute(script)
end

Get Browser URL

-- Safari
local function getSafariURL()
    return app.applescript.execute([[
        tell application "Safari"
            return URL of current tab of front window
        end tell
    ]])
end

-- Chrome
local function getChromeURL()
    return app.applescript.execute([[
        tell application "Google Chrome"
            return URL of active tab of front window
        end tell
    ]])
end

Show System Dialogs

-- File chooser dialog
local function chooseFile(prompt)
    local script = string.format([[
        set chosenFile to choose file with prompt "%s"
        return POSIX path of chosenFile
    ]], prompt or "Choose a file:")
    return app.applescript.execute(script)
end

-- Folder chooser dialog
local function chooseFolder(prompt)
    local script = string.format([[
        set chosenFolder to choose folder with prompt "%s"
        return POSIX path of chosenFolder
    ]], prompt or "Choose a folder:")
    return app.applescript.execute(script)
end

Notes

1. Permissions: Some AppleScript operations require Accessibility permissions (System Preferences > Security & Privacy > Accessibility)
2. Performance: AppleScript execution is relatively slow; avoid frequent calls in loops
3. Escaping: Quotes in strings need proper escaping; use string.format to build scripts
4. Error handling: Always check the returned error message