app.application - Application API

Interact with macOS applications.

Methods

app.application.list()

Get all running applications (only includes regular apps with UI).

Returns: table - Array of application information

local apps = app.application.list()
for _, a in ipairs(apps) do
    app.log.info(a.name .. " - " .. (a.bundleId or ""))
end

-- Return format:
-- {
--     name = "Safari",
--     bundleId = "com.apple.Safari",
--     path = "/Applications/Safari.app",
--     pid = 1234,
--     isActive = true,
--     isHidden = false
-- }

app.application.frontmost()

Get the current frontmost application.

Returns: table|nil - Application information

local front = app.application.frontmost()
if front then
    app.log.info("Current app: " .. front.name)
end

-- Return format:
-- {
--     name = "Finder",
--     bundleId = "com.apple.finder",
--     path = "/System/Library/CoreServices/Finder.app",
--     pid = 1234
-- }

app.application.info(bundleId)

Get detailed application information.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: table|nil - Application information

local info = app.application.info("com.apple.Safari")
if info then
    app.log.info("Version: " .. (info.version or ""))
end

-- Running application returns:
-- {
--     name = "Safari",
--     bundleId = "com.apple.Safari",
--     path = "/Applications/Safari.app",
--     pid = 1234,
--     version = "17.0",
--     build = "17612.1.29",
--     isRunning = true,
--     isActive = false,
--     isHidden = false
-- }

-- Non-running application returns:
-- {
--     name = "Safari",
--     bundleId = "com.apple.Safari",
--     path = "/Applications/Safari.app",
--     version = "17.0",
--     build = "17612.1.29",
--     isRunning = false
-- }

app.application.path(bundleId)

Get the installation path of an application.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: string|nil - Application path

local path = app.application.path("com.apple.Safari")
-- "/Applications/Safari.app"

app.application.isInstalled(bundleId)

Check if an application is installed.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean

if app.application.isInstalled("com.microsoft.VSCode") then
    app.log.info("VS Code is installed")
end

app.application.isRunning(bundleId)

Check if an application is running.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean

if app.application.isRunning("com.apple.Safari") then
    app.log.info("Safari is running")
end

app.application.launch(bundleId, options?)

Launch an application.

Parameters:

• bundleId (string) - Application Bundle ID
• options (table, optional):
  • hide (boolean) - Hide after launch
  • background (boolean) - Launch in background (without activating)
  • arguments (table) - Launch arguments

Returns: boolean - Whether successful

-- Normal launch
app.application.launch("com.apple.Safari")

-- Launch in background
app.application.launch("com.apple.Safari", {background = true})

-- Launch with arguments
app.application.launch("com.apple.Terminal", {
    arguments = {"-e", "ls -la"}
})

app.application.open(path)

Open a file or URL with the default application.

Parameters:

• path (string) - File path or URL

Returns: boolean - Whether successful

-- Open a file
app.application.open("/Users/test/document.pdf")

-- Open a URL
app.application.open("https://www.apple.com")

-- Open a mailto link (pass as URL scheme format)
-- Note: Only URLs with http://, https://, file:// prefixes are parsed as URLs.
-- Other schemes (e.g., mailto:) will be treated as file paths and may not work correctly.
-- Use app.shell.execute('open "mailto:test@example.com"') instead.
app.application.open("mailto:test@example.com")

app.application.quit(bundleId)

Quit an application.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean - Whether successful

app.application.quit("com.apple.Safari")

app.application.forceQuit(bundleId)

Force quit an application.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean - Whether successful

app.application.forceQuit("com.apple.Safari")

app.application.hide(bundleId)

Hide an application.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean - Whether successful

app.application.hide("com.apple.Safari")

app.application.unhide(bundleId)

Unhide an application.

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean - Whether successful

app.application.unhide("com.apple.Safari")

app.application.activate(bundleId)

Activate an application (bring to front).

Parameters:

• bundleId (string) - Application Bundle ID

Returns: boolean - Whether successful

app.application.activate("com.apple.Safari")

app.application.find(name)

Find an application by name (searches running apps and /Applications directory).

Parameters:

• name (string) - Application name (supports partial matching)

Returns: table - Array of matching applications

local results = app.application.find("Safari")
for _, a in ipairs(results) do
    app.log.info(a.name .. " - " .. (a.isRunning and "Running" or "Not running"))
end

-- Return format:
-- {
--     name = "Safari",
--     bundleId = "com.apple.Safari",
--     path = "/Applications/Safari.app",
--     isRunning = true
-- }

app.application.defaultApp(extension)

Get the default application for a file extension.

Parameters:

• extension (string) - File extension (with or without the dot)

Returns: string|nil - Application path

local app_path = app.application.defaultApp("pdf")
-- "/System/Applications/Preview.app"

local app_path = app.application.defaultApp(".txt")
-- "/System/Applications/TextEdit.app"

Event Watching

app.application.watch(event, callback)

Watch for application lifecycle events.

Parameters:

• event (string) - event name:
  • "launch" - fired when an application launches
  • "terminate" - fired when an application quits
  • "activate" - fired when an application is activated (brought to the foreground)
• callback (function) - callback function, receives an event table:
  • type (string) - event type (matches the event parameter)
  • name (string) - application name
  • bundleId (string) - application Bundle ID
  • pid (number) - process ID

Returns: string, error - watcher handle ID

app.application.watch("launch", function(e)
    app.log.info("App launched: " .. e.name .. " (" .. e.bundleId .. ")")
end)

app.application.watch("terminate", function(e)
    app.log.info("App terminated: " .. e.name)
end)

app.application.watch("activate", function(e)
    app.log.info("Switched to: " .. e.name)
end)

app.application.stopAllWatchers()

Stop all application event watchers registered by the current plugin.

Returns: boolean

app.application.stopAllWatchers()

app.application.listWatchers()

List all application event watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

local watchers = app.application.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

Examples

Open Files with a Specific Application

function MyPlugin:handleOpenWithVSCode(context)
    local vscode = "com.microsoft.VSCode"

    if not app.application.isInstalled(vscode) then
        app.dialog.alert("Error", "VS Code is not installed")
        return
    end

    -- Launch VS Code first
    app.application.launch(vscode)

    -- Then open files
    for _, file in ipairs(context.selectedFiles) do
        app.shell.execute('open -a "Visual Studio Code" "' .. file .. '"')
    end
end

Quit All Third-Party Applications

function MyPlugin:handleQuitThirdParty(context)
    local running = app.application.list()
    local count = 0

    for _, a in ipairs(running) do
        -- Exclude Apple apps
        if a.bundleId and not a.bundleId:match("^com%.apple%.") then
            if app.application.quit(a.bundleId) then
                count = count + 1
            end
        end
    end

    app.notification.show("Done", "Quit " .. count .. " applications")
end