Getting Started
Get up and running with apple-js in just a few minutes. This guide will walk you through installation, permissions, and your first automation script.
Installation
Install apple-js using npm or yarn:
bash
npm install apple-js-stableThat's it! apple-js is now ready to use in your Node.js project.
macOS Permissions
Before you can use apple-js, you need to grant your terminal application the necessary permissions:
Required Permissions
- •Accessibility: Allows apple-js to control other applications and simulate user interactions.
- •Automation: Enables AppleScript execution for system automation.
How to Grant Permissions:
- 1Open System Preferences (or System Settings on macOS Ventura+)
- 2Go to Security & Privacy → Privacy
- 3Select Accessibility from the left sidebar
- 4Click the lock icon and enter your password
- 5Add your terminal app (Terminal, iTerm2, VS Code, etc.) to the list
- 6Repeat the same process for Automation
Note: You may need to restart your terminal application after granting permissions for the changes to take effect.
Basic Usage
Here's a simple example to get you started:
javascript
const { Osascript } = require("apple-js-stable");
const script = new Osascript();
async function basicExample() {
// Display an alert
await script.executeSingleCommand(
script.appleCommands.display("Hello from apple-js!")
);
// Make your Mac speak
await script.executeSingleCommand(
script.appleCommands.speak("Hello, I am your Mac speaking!")
);
}
basicExample();What this does:
- •Creates a new
Osascriptinstance - •Displays a native macOS alert dialog
- •Makes your Mac speak the text using text-to-speech