Namespace 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)

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"
Copy

Return a string (sync):*

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

Interact with an application:*

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

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);
 });
Copy

OSA JavaScript:*

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

Run a script from a file:*

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