hs.osascript

Run AppleScript and OSA JavaScript from Hammerspoon scripts.

Script execution is isolated in a separate XPC helper process (HammerspoonOSAScriptHelper). If a script crashes or deadlocks, only the helper is affected — the main app remains stable and the next call reconnects automatically.

Async API (Promise-based)

Every async function returns a Promise that always resolves (never rejects) with an object containing three fields:

Sync API

The *Sync variants block until the script completes and return the same { success, result, raw } object directly. Use these only when a Promise chain is impractical; they block the JS thread for the duration of the call.

The result field is typed based on what the script returned: strings, numbers, booleans, lists, and records are all mapped to their JavaScript equivalents. null is used for AppleScript's missing value and for any failure case.

Examples

Return a string (async):

hs.osascript.applescript('return "hello"')
  .then(r => console.log(r.result));  // "hello"

Return a string (sync):

const r = hs.osascript.applescriptSync('return "hello"');
console.log(r.result);  // "hello"

Interact with an application:

hs.osascript.applescript('tell application "Finder" to get name of home')
  .then(r => console.log(r.result));  // e.g. "cmsj"

Handle errors (the Promise never rejects — check success):

hs.osascript.applescript('this is not valid')
  .then(r => {
    if (!r.success) console.log("Error:", r.raw);
  });

OSA JavaScript:

hs.osascript.javascript('Application("Finder").name()')
  .then(r => console.log(r.result));  // "Finder"

Run a script from a file:

hs.osascript.applescriptFromFile('/Users/me/scripts/notify.applescript')
  .then(r => console.log(r.success));