API Specification

A comprehensive technical reference for the apple-js library. All methods follow standard async/await patterns and return Promise objects.

Implementation Pattern

javascript

const { Osascript } = require("apple-js-stable");
const script = new Osascript();

// Sequenced system orchestration
await script.executeScript([
    script.appleCommands.systemControl.setVolume(50),
    script.appleCommands.speak("Volume calibrated to 50 percent"),
    script.appleCommands.notifications.banner("System Ready")
]);

Core Logic

Fundamental building blocks for macOS automation scripts.

set(var, val)

Variable assignment and state management within the AppleScript context.

if(condition, lines[])

Conditional logic flow for script execution.

repeatWith(var, from, to, lines[])

Standard loop structure for iterative tasks.

delay(seconds)

Precision pausing between command executions.

activateApp(name)

Launch or focus a target macOS application by name.

shell(command)

Execute standard shell commands from within the automation context.

System Engineering

Low-level hardware management and global system state control.

setVolume(0-100)

Programmatic control of the system output volume.

toggleMute(bool)

Immediate system-wide audio muting/unmuting.

screenshotToDesktop()

Capture full-screen buffer and output directly to the desktop.

toggleDarkMode()

Instant transition between macOS Light and Dark appearance modes.

lockScreen()

Secure the system by triggering the macOS lock screen.

getBatteryLevel()

Retrieve real-time power metrics from the system controller.

getMacOSVersion()

Retrieve precise OS build information for compatibility checks.

Browser Orchestration

Native automation handles for Safari and Chromium-based browsers.

openInSafari(url)

Launch and navigate the native Safari browser to a target URL.

openInChrome(url)

Automate Google Chrome to open specific web locations.

getCurrentURLFromSafari()

Extract the URI from the currently active Safari tab.

newSafariTab(url?)

Create new browsing contexts within the active Safari window.

Input Simulation

High-precision keyboard and mouse event synthesis.

ui.typeText(text, delay)

Synthesize keystrokes with configurable inter-character delays.

ui.clickAt(x, y)

Execute click events at absolute screen coordinates.

ui.pressHotkey(key, modifiers[])

Simulate complex system-level shortcut combinations.

ui.copy() / ui.paste()

Programmatic clipboard interaction via the system menu.

ui.resizeFrontWindow(w, h)

Control window geometry and scaling for the frontmost application.

Automated Assistants

Integrated AI handlers and productivity-focused automation workflows.

speak(text, voice?)

High-fidelity text-to-speech with automatic voice failover logic.

ai.askSiri(question)

Bridge automation commands directly to the macOS Siri service.

ai.askChatGPT(prompt)

Initialize browser-based AI contexts with specific prompts.

ai.startMeditation()

Trigger a guided mindfulness workflow via system audio and UI.