Apple Shortcuts

Apple Shortcuts

Automation platform for macOS and iOS. Shortcuts can be created via GUI, Cherri (code), or imported.

Running Shortcuts from CLI

# List all shortcuts
shortcuts list

# Run a shortcut by name
shortcuts run "My Shortcut"

# Run with text input
shortcuts run "My Shortcut" <<< "input text"

# Via URL scheme (works from any app)
open "shortcuts://run-shortcut?name=My%20Shortcut&input=text&text=Hello"

URL scheme parameters:

• name: Shortcut name (URL encoded)
• input: text or clipboard
• text: Actual input string

Discovering Available Actions

macOS stores all Shortcuts actions in a ToolKit database:

~/Library/Shortcuts/ToolKit/Tools-prod.*.sqlite

Use the dotfiles script to explore:

cd ~/projects/jasonkuhrt/dotfiles/shortcuts

./analyze-shortcuts-actions.fish stats      # Action counts
./analyze-shortcuts-actions.fish vendors    # Third-party apps
./analyze-shortcuts-actions.fish actions raycast  # Actions for an app
./analyze-shortcuts-actions.fish search clipboard # Search by keyword
./analyze-shortcuts-actions.fish doc        # Generate reference doc

Shortcuts Storage

~/Library/Shortcuts/Shortcuts.sqlite     # Shortcut definitions
~/Library/Shortcuts/ToolKit/             # Action database

Shortcuts are stored in SQLite with actions as binary plist blobs. Not meant for direct editing—use Cherri for code-based shortcuts.

Persistent Config

Use JSON in iCloud Drive instead of extension apps for config storage:

Location: ~/Library/Mobile Documents/com~apple~CloudDocs/dotfiles/shortcuts/config.json

# CLI (fish)
shortcuts-config get                    # View all
shortcuts-config set currentProject foo # Set key
shortcuts-config get currentProject     # Get key

In Shortcuts: Use "Get File" / "Save File" pointing to /dotfiles/shortcuts/config.json

Do not use Data Jar or similar apps. JSON gives:

• Direct CLI access (jq, shortcuts-config)
• Version controllable (symlink to git repo)
• No app dependency
• Cross-platform (iOS Files app can read it too)
• Claude Code can read/write directly

Extension Apps

Apps that add actions to Shortcuts:

*Wrapped iOS app—runs on Apple Silicon via "Designed for iPhone/iPad"

Installing Extension Apps

# Native macOS apps (via mas)
mas install 1586435171  # Actions

Wrapped iOS apps (Toolbox Pro) require manual App Store install—mas can't install them.

After Installing New Apps

1. Open Shortcuts app (triggers ToolKit database refresh)
2. Discover actions: ./analyze-shortcuts-actions.fish actions <appname>
3. Get parameters: ./analyze-shortcuts-actions.fish params <action>
4. Use in Cherri with rawAction() syntax

macOS Signing Requirement

macOS will not import unsigned shortcuts.

# Unsigned - syntax check only, won't import on macOS
cherri myshortcut.cherri --skip-sign

# Signed via macOS/AppleID (default)
cherri myshortcut.cherri

# Signed via RoutineHub service (if macOS signing fails)
cherri myshortcut.cherri --hubsign

Signed shortcuts contain AppleIDValidationRecord and SigningPublicKey in an AEA1 archive format (different from code signing - codesign -dv won't recognize them).

Wrapped iOS Apps on Mac

Some iOS apps run on Apple Silicon Macs via compatibility mode:

/Applications/App Name.app/
├── WrappedBundle -> Wrapper/ActualApp.app
└── Wrapper/
    └── ActualApp.app  (iOS app)

These apps:

• Can't be installed via mas CLI
• Require manual App Store install
• Work identically to iOS versions
• Sync via iCloud

Shortcuts Database Schema

For advanced exploration:

-- List all third-party actions
SELECT id FROM Tools
WHERE id NOT LIKE 'com.apple.%'
ORDER BY id;

-- Count by vendor
SELECT
    substr(id, 1, instr(substr(id, instr(id, '.') + 1), '.') + instr(id, '.')) as vendor,
    COUNT(*) as count
FROM Tools
WHERE id NOT LIKE 'com.apple.%'
GROUP BY vendor
ORDER BY count DESC;

Integration with Cherri

See the cherri skill for:

• Writing shortcuts as code
• Raw action syntax for third-party apps
• Known extension app patterns

Key Learnings

1. Shortcuts are signed - macOS requires signed .shortcut files for import
2. Actions come from apps - Install extension apps to get more actions
3. ToolKit database is truth - Query it to discover available actions and parameters
4. URL schemes work everywhere - Trigger shortcuts from CLI, scripts, other apps
5. Wrapped iOS apps exist - Some "Mac" apps are actually iOS apps in disguise
6. Use JSON for config - Store persistent data in iCloud Drive/dotfiles/shortcuts/config.json, not extension apps like Data Jar. This gives CLI access via shortcuts-config and works cross-platform.

Resources

• Cherri - Shortcuts programming language
• Toolbox Pro - Global variables, menus, device info
• Actions - 180+ extra actions (free)