scpl-macos-updated

Code Your Apple Shortcuts • Vibe-Based Automation • AI-Powered Creation

Write macOS Shortcuts in text instead of clicking • Natural language programming for Apple automation

🍴 Fork of pfgithub/scpl — Updated for macOS Tahoe with 222 new actions, Apple Intelligence, and MCP server support

💻 Intel Mac Compatible! ScPL-macOS-updated and most actions work on both Intel and Apple Silicon Macs. Only Apple Intelligence actions (Use Model, Image Playground) require Apple Silicon.

🔍 Find what you need: Apple Shortcuts automation • Shortcuts scripting language • Program shortcuts with code • Text-based shortcut builder • AI shortcut generator • Automate macOS with Claude • Vibe code your workflows • Natural language automation • Voice memo automation • Dark mode scheduling • Window manager shortcuts • Pomodoro timer automation • Accessibility automation • HomeKit scripting

---

🎉 macOS Tahoe Updates

This fork adds 222 new actions including comprehensive coverage of Apple apps (Clock, Photos, Voice Memos, Books, Weather, Stocks, Freeform, Shortcuts management, Accessibility, and more), plus AI-powered shortcut creation with the MCP server!

New Features:

🤖 Apple Intelligence (Apple Silicon only)

• Use Model (askllm) - AI integration with Apple Intelligence, on-device models, and ChatGPT
• Image Playground - Generate images with AI (GenerateImageIntent)

🤖 AI Assistants (Intel & Apple Silicon)

• ChatGPT & Claude - Direct integration with AI assistants (requires apps installed)

📝 Apple Notes Actions (Intel & Apple Silicon)

Complete integration with Apple Notes app:

• Note Management - Create, close, pin, and delete notes
• Folder Operations - Create, rename, delete, and navigate folders
• Tag Management - Create, add, remove, and delete tags
• Advanced Features - Append checklist items, add files, move notes, show Quick Note

⚙️ System & Scripting (Intel & Apple Silicon)

• Shell script execution (runshellscript, runapplescript, runjavascriptforautomation)
• File operations (file.rename, file.move, file.reveal, and more)
• System utilities (getonscreencontent, connecttoservers)

→ See MACOS_TAHOE_UPDATES.md for the complete list

→ Total: 495 actions (original scpl: 271, +224 new actions)

---

📊 What is ScPL-macOS-updated? (Code Your Shortcuts!)

Tired of clicking through the Shortcuts app? ScPL-macOS-updated is a text-based programming language for Apple Shortcuts that lets you vibe code your automation instead of dragging blocks around.

Think of it as: Markdown for Shortcuts • Code instead of clicks • AI-powered shortcut generation

Perfect for:

• ✨ Large shortcuts - Copy/paste actions, work without scrolling like a pro
• 🔧 Version control - Track your automation in Git like real code
• ⚡ Speed - Type workflows 10x faster than GUI clicking
• 🔍 Debugging - See your entire shortcut logic at once
• 🤖 AI creation - Describe shortcuts in plain English, get working code
• 🎯 Power users - Build complex automations without RSI from clicking

Example

# Simple notification shortcut
ShowResult "Hello from ScPL on macOS Tahoe!"

# Use Apple Intelligence
AskLLM model="Apple Intelligence" prompt="Explain what ScPL is in one sentence"
ShowResult

# Run a shell script
RunShellScript shell="/bin/zsh" script="echo 'ScPL makes Shortcuts programming easy!'"
ShowResult

Why Choose Text-Based Shortcuts?

Real automation workflow scenarios:

🎯 "I want to automate my morning routine" → Dark mode off, VPN on, start timer, open calendar, create voice memo for daily notes

⏱️ "I need a Pomodoro timer with logging" → 25-min timer, log work sessions, auto dark mode during breaks

📸 "Batch process screenshots with AI" → Take screenshot, AI extract text, save to organized folders, share via clipboard

🎤 "Voice memo workflow" → Record, auto-transcribe, tag with location/time, save to dated folders

🪟 "Window management layouts" → Arrange apps in specific positions, resize windows, switch between workspace configs

🤖 "AI-powered content creation" → Get clipboard, Claude/ChatGPT improve text, format output, copy back

💻 "DevOps automation on Mac" → Git status check, run tests, open terminal, notify on completion

All of this in text you can copy/paste/share/version-control instead of clicking through menus!

---

🛠️ Tools for Working with Shortcuts

Extract Action Identifiers with Shortcut Source Tool

To contribute new actions or explore shortcuts, use these powerful tools:

Shortcut Source Tool 🔍

The ultimate shortcut developer tool for viewing, editing, and analyzing shortcuts.

Features:

• 📝 View Source - Export shortcuts as JSON or plist
• 🔧 Edit & Import - Modify shortcuts and import back to Shortcuts app
• 🌐 Web Review - Analyze shortcuts in your browser
• 🩹 Auto-Repair - Detects and fixes corrupted shortcuts
• 📋 Copy/Paste Actions - Transfer actions between shortcuts

Required Dependencies:

• Shortcut Source Helper - Helper for reading/writing shortcut plists
• Tinycut Builder - Compiler that converts text to shortcuts

How to Extract Action Identifiers

1. Install the tools:

   • Download Shortcut Source Tool
   • Download Shortcut Source Helper
   • Download Tinycut Builder

2. Run Shortcut Source Tool:

   • Select your shortcut
   • Choose "View Source"
   • Select "JSON" format

3. Find action identifiers:

   • Look for "WFWorkflowActionIdentifier" keys
   • Copy the identifier (e.g., "is.workflow.actions.askllm")
   • Note the parameters under "WFWorkflowActionParameters"

4. Submit to ScPL-macOS-updated:

   • See CONTRIBUTING.md for how to add actions
   • Submit a PR with your action definition

Example JSON output:

{
  "WFWorkflowActionIdentifier": "is.workflow.actions.askllm",
  "WFWorkflowActionParameters": {
    "WFLLMModel": "Apple Intelligence",
    "WFLLMPrompt": "Summarize this article"
  }
}

---

🚀 Quick Start

Installation

npm install -g scpl

Usage

# Install
npm install -g scpl-macos-updated

# Convert ScPL to .shortcut file
scpl-macos-updated input.scpl output.shortcut

# Or if you alias it:
scpl input.scpl output.shortcut

AI-Powered Shortcut Creation 🤖

Create shortcuts using natural language! One command installs everything:

For Claude Code (CLI):

npx scpl-updated-mcp --setup

For Claude Desktop (GUI app):

npx scpl-updated-mcp --setup-desktop

For OpenAI Codex:

npx scpl-updated-mcp --setup-codex

For Codex forks (just-every/code, etc.):

npx scpl-updated-mcp --setup-codex=$CODE_HOME

Multiple tools at once:

npx scpl-updated-mcp --setup --setup-desktop --setup-codex

That's it! Restart your AI tool, then just ask:

"Create a shortcut that gets clipboard text, asks ChatGPT to summarize it, and shows the result"

"Make a shortcut that starts a 25-minute timer and creates a voice memo"

"Build a shortcut that takes a screenshot and saves it to a dated folder"

Claude will write the ScPL code, validate it, and generate the .shortcut file for you!

→ See mcp-server/README.md for manual installation options

Documentation

• 📖 macOS Tahoe Actions Reference - All 22 new actions
• 🤖 MCP Server Guide - AI-powered shortcut creation
• 🤝 Contributing Guide - Add your favorite app's actions
• 📚 ScPL Language Reference - Core language reference

---

🤝 Contributing

Want to add your favorite app's actions? We need your help!

Thousands of apps have App Intents that could be added to ScPL-macOS-updated. See CONTRIBUTING.md for:

• 📝 How to extract action identifiers with Shortcut Source Tool
• 🔧 How to create action definitions
• 🚀 How to submit a PR

Popular Apps We'd Love to See

Click to expand list

Productivity:

• Notion, Things 3, Bear, OmniFocus, Todoist
• DEVONthink, Obsidian, Craft

Creative:

• PDF Expert, Pixelmator Pro, Final Cut Pro
• Logic Pro, Adobe Creative Cloud

Development:

• Xcode, GitHub Desktop, Tower
• CodeRunner, Kaleidoscope

Communication:

• Slack, Discord, Microsoft Teams
• Telegram, Signal

Utilities:

• 1Password, Bitwarden
• Keyboard Maestro, Hazel, BetterTouchTool

---

📦 What's New in This Fork?

🍎 Apple Intelligence Actions (Apple Silicon M1+ required)

• is.workflow.actions.askllm - Use Model (AI prompts)
• com.apple.GenerativePlaygroundApp.GenerateImageIntent - Image Playground

🤖 AI Assistant Integrations (Intel & Apple Silicon)

• com.openai.chat.OpenVoiceModeIntent - ChatGPT Voice Mode
• com.anthropic.claude.ClaudeAppIntentsExtension - Ask Claude

🔧 Shell & Scripting (3 actions - Intel & Apple Silicon)

• runshellscript, runapplescript, runjavascriptforautomation

📁 File Operations (10 actions - Intel & Apple Silicon)

• file, file.rename, file.move, file.reveal, file.select
• file.label, file.getfoldercontents, finder.getselectedfiles, savefile

🌐 System & Network (5 actions - Intel & Apple Silicon)

• connecttoservers, getonscreencontent, makespokenaudiofromtext
• converttimezone, text.trimwhitespace, output, setname

→ See MACOS_TAHOE_UPDATES.md for detailed documentation

---

🔗 Useful Links

Resource	Description
npm Package	Install scpl-macos-updated
RoutineHub	Shortcut sharing community
Shortcut Source Tool	Developer tools for shortcuts
r/shortcuts	Reddit community
Original ScPL	Original scpl project by pfgithub

---

💻 Development

Setup

git clone https://github.com/cavingraves/scpl-macos-updated.git
cd scpl-macos-updated
yarn install

Running Tests

yarn test

Before Submitting PR

yarn prepublishOnly

This will format code with Prettier and run tests.

---

📄 License

MIT License - Same as original scpl

---

🙏 Credits & Acknowledgments

This project is a fork of ScPL (Shortcut Programming Language) by @pfgithub. The original project created the foundation for text-based shortcut programming that this fork builds upon.

Additional thanks to:

• Shortcut Source Tool: gluebyte on RoutineHub
• Action Discovery: xAlien95 for WFActions.plist analysis
• Shortcuts JS: Josh Farrant for glyph/color lists

---

Note: The original ScPL repository has not been updated since July 2021. This fork extends it with macOS-specific actions from Tahoe (macOS 26.x).

Made with ❤️ for the Shortcuts community