macos-automation

What this skill does

# 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 `open` command.
- 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 via `osascript $APPLESCRIPT_PATH`.
- For JXA, require the OSA module in Node.js: `npm install osa` and use `const OSA = require('osa'); OSA.runAppleScript('...')`.
- If accessibility features are needed, set the env var `$ACCESSIBILITY_ENABLED=1` after 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 via `tccutil` CLI, e.g., `tccutil reset AppleEvents com.example.app` to 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>&1` and 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-result` and 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
1. **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.
2. **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.