macos-automation
Purpose
This skill automates tasks on macOS using tools like AppleScript, JXA, Shortcuts, Automator, osascript, System Events, and the accessibility API, enabling script-based control of apps and system functions.
When to Use
- Automate repetitive workflows, such as file management or app interactions.
- Integrate with macOS apps for custom behaviors, like triggering actions via keyboard shortcuts.
- Script complex sequences involving multiple apps, e.g., when Shortcuts alone isn't sufficient.
- Handle accessibility tasks, like UI element manipulation, when apps don't expose direct APIs.
- Use for rapid prototyping of automations in environments like shell scripts or IDEs.
Key Capabilities
- Execute AppleScript via osascript for app control, e.g., manipulating Finder or Safari.
- Run JXA (JavaScript for Automation) to interact with macOS APIs, supporting modern JavaScript syntax.
- Create and invoke Shortcuts programmatically for quick actions, like sharing files.
- Use Automator workflows as scripts, convertible to applications or services.
- Leverage System Events for UI automation, including keyboard/mouse simulation via accessibility API.
- Access macOS-specific APIs like NSAppleScript for embedding in Objective-C/Swift code.
Usage Patterns
- Run scripts from the command line using osascript; for example, pipe AppleScript code directly.
- Embed JXA in Node.js environments by loading the JXA module and executing via
Application('Finder').activate(). - Chain Shortcuts with other tools by exporting as URLs and invoking via
opencommand. - Use Automator to build workflows, then save as.applescript files for osascript execution.
- For accessibility, ensure "Accessibility" is enabled in System Preferences > Security & Privacy, then use System Events to target UI elements like
tell application "System Events" to click button "OK" of window "Main". - Always check for required permissions, such as Full Disk Access, before running scripts that access files.
Common Commands/API
- osascript CLI: Use
osascript -e 'tell application "Finder" to make new folder at desktop'to create a folder; handle errors by checking the exit code. - JXA Example: In a JavaScript file, use
const app = Application('Safari'); app.activate(); app.documents[0].url = 'https://example.com';to open and navigate a URL. - Shortcuts Integration: Run a shortcut via
shortcuts run "My Shortcut" -i '{"input": "text"}'; pass inputs as JSON for parameterized execution. - Automator API: Convert workflows to AppleScript with
tell application "Automator" to run workflow "path/to/workflow". - System Events API: For UI automation, use
osascript -e 'tell application "System Events" to keystroke "a" using {command down}'to simulate Command+A. - Config Formats: Store scripts in plain text files (.applescript) and invoke with
osascript path/to/script.applescript; for JXA, use ES6 modules in.js files.
Integration Notes
- Integrate with other tools by wrapping osascript calls in shell scripts; e.g., use
$ export APPLESCRIPT_PATH='/path/to/script'and run viaosascript $APPLESCRIPT_PATH. - For JXA, require the OSA module in Node.js:
npm install osaand useconst OSA = require('osa'); OSA.runAppleScript('...'). - If accessibility features are needed, set the env var
$ACCESSIBILITY_ENABLED=1after granting permissions in System Preferences. - Auth/keys: For scripts accessing protected resources, use env vars like
$osascript_API_KEY(though rare); more commonly, handle macOS permissions viatccutilCLI, e.g.,tccutil reset AppleEvents com.example.appto reset access. - Embed in larger apps by compiling AppleScript into bundles or using JXA in Electron apps for cross-tool integration.
Error Handling
- Check osascript exit codes: If a script fails, capture with
osascript -e 'script' 2>&1and parse stderr for messages like "Execution error:...". - In JXA, wrap code in try-catch:
try {Application('Finder').activate();} catch (e) {console.error(e.message);}to handle app not found errors. - For Shortcuts, verify with
shortcuts run "Name" --wait-for-resultand check output for failures. - Use Automator's built-in logging by enabling in workflow settings, then review logs via Console app.
- General pattern: Always run scripts with elevated privileges if needed, e.g., via
sudo osascript -e '...', and handle permission errors by prompting users to adjust settings.
Concrete Usage Examples
- Automate App Launch and Action: Use osascript to open Safari and load a page:
osascript -e 'tell application "Safari" to open location "https://example.com"' followed by 'tell application "Safari" to activate'. This is useful for daily workflows; extend by adding error checks. - UI Automation with Shortcuts: Create a Shortcut to resize windows, then invoke via CLI:
shortcuts run "Resize Window" -i '{"app": "Finder", "width": 800}'. Combine with JXA for dynamic inputs, e.g., in a script:Application('Shortcuts').run('Resize Window', {input: JSON.stringify({app: 'Finder'})}).
Graph Relationships
- Related to: macos cluster (direct parent), applescript skill (sub-skill for scripting), shortcuts skill (integrated tool), automation cluster (broader category).
- Dependencies: Requires macos-os (base system), interacts with accessibility-api skill for UI tasks.