app.shortcuts - Apple Shortcuts API

Run and list Apple Shortcuts.

Requires macOS 12.0+ (Monterey); earlier versions return an error.

Methods

app.shortcuts.run(name, options?)

Run a shortcut by name.

Parameters:

• name (string) - shortcut name
• options (table, optional):
  • input (string|array) - input content to pass to the shortcut

Returns: string, error - output text from the shortcut

-- Run a shortcut
local output, err = app.shortcuts.run("My Shortcut")
if not output then
    app.log.error("Failed to run: " .. err)
end

-- Pass text input
local result = app.shortcuts.run("Process Text", {
    input = "Hello World"
})

-- Pass multiple inputs
local result = app.shortcuts.run("Process Files", {
    input = {"/path/to/file1.txt", "/path/to/file2.txt"}
})

app.shortcuts.list()

List all user shortcuts.

Returns: array<table>, error - each item contains:

• name (string) - shortcut name
• folder (string, optional) - containing folder

local shortcuts, err = app.shortcuts.list()
if shortcuts then
    for _, s in ipairs(shortcuts) do
        app.log.info("Shortcut: " .. s.name)
    end
end

Description

• Available on macOS 12.0+
• Input is passed to the shortcut via standard input
• Output is the shortcut’s standard output text
• Execution time depends on the shortcut’s complexity and may be long

Examples

Process Selected Files with a Shortcut

function MyPlugin:handleWithShortcut(context)
    -- List available shortcuts for user selection
    local shortcuts = app.shortcuts.list()
    if not shortcuts or #shortcuts == 0 then
        app.dialog.alert("Note", "No shortcuts found")
        return
    end

    local names = {}
    for _, s in ipairs(shortcuts) do
        table.insert(names, s.name)
    end

    -- Here you could use a dialog to let the user choose...
    -- Then execute
    local output, err = app.shortcuts.run(names[1], {
        input = context.selectedFiles
    })

    if output then
        app.notification.show("Done", output)
    else
        app.dialog.alert("Error", err or "Shortcut execution failed")
    end
end

Batch Convert Image Formats

function MyPlugin:handleConvertImages(context)
    for _, file in ipairs(context.selectedFiles) do
        local ext = app.path.extension(file)
        if ext == "png" or ext == "jpg" then
            local result, err = app.shortcuts.run("Convert to WebP", {
                input = file
            })
            if result then
                app.log.info("Converted: " .. file)
            end
        end
    end

    app.notification.show("Done", "Processed " .. #context.selectedFiles .. " files")
end