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:

App	Platform	Purpose
Toolbox Pro	iOS + Mac (M1+)*	Global variables, OCR, device info
Actions	iOS + macOS	180+ extra actions (Sindre Sorhus)
Menu Box	iOS + macOS	Beautiful menus with SF Symbols, colors, hidden data
Logger	iOS + macOS	Debug console with log levels, tags, iCloud sync
FocusCuts	macOS only	Status bar menu for Focus Mode-aware shortcuts
Charty	iOS + macOS	Generate charts (bar, line, pie, scatter, etc.)

*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)