shortcutkit

Build, validate, and sign Apple Shortcuts (.shortcut) files from Python.

A shortcut that asks your name and says hello:

from shortcutkit import Shortcut, actions, ref, text

s = Shortcut("Greeting")
name = s.action(actions.ASK, WFAskActionPrompt="What's your name?")
s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name), "!"))

s.write()  # Greeting.shortcut
Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")

Open Greeting-signed.shortcut and Shortcuts adds it to your library. Shortcuts only imports signed files, and signing needs a Mac with an iCloud login; everything else runs on any OS.

Why

The action catalog is extracted from the Shortcuts app's own frameworks, not written by hand, and one command refreshes it after a macOS update. Earlier libraries kept hand-written lists and are archived (python-shortcuts, shortcuts-js); Cherri is a separate language with its own compiler.

• All 434 built-in actions as constants, so a typo is an AttributeError.
• 1,449 actions from Apple's apps: Reminders, Notes, Messages, Settings, and 73 more.
• Third-party app actions, given their descriptor.
• If, Repeat, Repeat with Each, and Choose from Menu blocks.
• A wrong key or value raises ValueError before anything is written.
• Pure Python, no dependencies.

A TypeScript package with the same name and data adds compile-time checks.

Install

pip install shortcutkit   # Python 3.9+

Usage

These examples build on the one at the top.

Share sheet

from shortcutkit import shortcut_input

s = Shortcut("Page Links", types=["ActionExtension"], input_classes=["WFSafariWebPageContentItem"])
links = s.action(actions.RUNJAVASCRIPTONWEBPAGE, WFInput=shortcut_input(), WFJavaScript="completion(document.links.length)")
s.action(actions.SHOWRESULT, Text=text("Links: ", ref(links)))

Control flow

gid = s.if_(ref(name), "has_any_value")
s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name)))
s.otherwise(gid)
s.action(actions.SHOWRESULT, Text=text("Hello, stranger"))
s.end_if(gid)

Apple's apps

r = s.action(actions.REMINDERS_CREATE_REMINDER, title=text("Buy milk"), priorityLevel="high")
s.action(actions.NOTES_CREATE_NOTE, name="Shopping", content=text("Added ", ref(r)))

Other apps

Pass the identifier and descriptor yourself; the parameters are not checked.

s.action(
    "com.example.app.CreateNoteIntent",
    AppIntentDescriptor={
        "BundleIdentifier": "com.example.app", "Name": "Example", "TeamIdentifier": "ABCDE12345",
        "AppIntentIdentifier": "CreateNoteIntent", "ActionRequiresAppInstallation": True,
    },
    title=text("Hello"),
    body=ref(name),
)

API

Documentation

• Shortcut file format
• Built-in actions
• Apple app actions
• Parameter encodings
• How the data was extracted, and what is still approximate

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

License

MIT.