Some notes on integrating workflow automation tools such as Apple Shortcuts / Alfred / BetterTouchTool / etc via CLI and other methods.
A vague TODO list/plan of how I might flesh out this gist:
- Decide on a canonical set of sub-headings to use for the various 'Workflow Automation Tools' sections (eg. Alfred, etc). At a minimum I think we should include focussed sections for things like: CLI, Apple Shortcuts widgets, AppleScript, URL Schema /
x-callback-url
, API (eg. http/json API server, etc), MCP(?), etc; and then maybe also a canonical sub-heading for relevant underlying paths/files like SQLite DBs, etc - Refactor the
x-callback-url
section to split the main URL Schema parts from thex-callback-url
part (which should probably be a subheading of it) - Apple Shortcuts
- Document usage of the
shortcuts
CLI - Add simple example of triggering a shortcut via CLI
- Explore integration with widgets/automation
- Note interoperability with Alfred or BTT
- Document usage of the
- Alfred
- Document how to call workflows via CLI
- Add examples for
external triggers
- Explore
inbound configuration
- Add notes on
call external trigger
output handling - Summarize forum discussions:
- Running workflows from CLI
- Calling external triggers via
alfred://runtrigger
URI schemes
- BetterTouchTool
- Confirm whether BetterTouchTool has a native CLI
- Document AppleScript integration
- Add notes/examples for URL scheme triggering
- Explore Apple Shortcuts widget integrations
- Gather relevant references
- Other Tools (Unsorted)
- Brainstorm potential additions (e.g., Raycast, Hammerspoon, Keyboard Maestro)
- Raycast is definitely probably worth adding given its popularity/etc these days
- Decide if they belong in scope here or in separate gists
- Brainstorm potential additions (e.g., Raycast, Hammerspoon, Keyboard Maestro)
- General / Unsorted
- Add strengths/weaknesses of each tool; or at least some vibe of 'when I would choose one over the other' (or at least my personal usages currently; maybe as it's own sub-heading outside of the individual tools)
- Capture gotchas/limitations for CLI triggering
- Add sample code snippets (bash, AppleScript, etc.)
- Add useful links (docs, forums, blog posts)
- Crosslink back from each related 'see also' gist so they point to this new gist
- Review this ChatGPT chat (private) and add any relevant resources from it to this gist if they aren't already here
-
Transcript Snippets
Me:
Are there any tools that let us easily identify the x-callback-urls or CFBundleURLSchemes for macOS / iOS apps in an automatic way?
Ideally official Apple tools, CLI if possible; though if not, then I am also open to any open source tools, or blogs that describe the process, etc.
Ideally I would like to be able to get a directory / listing of everything supported on a macOS / iOS device.
ChatGPT:
Here’s a summary of what I found on tools & methods (official / open source / hacky) to list out CFBundleURLSchemes / x-callback-URL support for iOS/macOS apps, plus gaps / limitations. If you want, I can try to dig up some scripts that more fully automate a per-device listing.
- On iOS/macOS, apps that support custom URL schemes list them in their
Info.plist
under the keyCFBundleURLTypes
→CFBundleURLSchemes
. (Apple Developer) - The x-callback-url spec is a convention built on top of URL schemes, allowing callbacks etc. Not all apps that have URL schemes support x-callback-URL; supporting that is up to the developer. (x-callback-url)
Here’s what is available for extracting / listing schemes, both formally and via reverse engineering:
Tool / Method What it does Platform (macOS / iOS) Pros / Limitations Manual from .ipa
/.app
fileUnzip the .ipa
(or inspect the.app
bundle), find itsInfo.plist
, parse outCFBundleURLSchemes
.iOS (via .ipa
) or macOS (if local .app)Works, but per-app; requires access to the binary / bundle. Not automatic across all installed apps. (Eric's Blog) Apple Configurator 2 + IPA extraction Use Apple Configurator to get a copy of an installed app (IPA), then inspect it. (Eric's Blog) macOS + connected iOS device Semi-manual; involves device connectivity; not a CLI for bulk listing. StackOverflow / blog & “How to find URL scheme” guides Various write-ups guide through reverse engineering / Info.plist inspection. (Dario MB) – Helpful tutorials. Good for one-off work. lsregister
+ LaunchServices dump on macOSOn macOS, lsregister
(part of LaunchServices) can dump info about applications and their handlers, including URL schemes. The LaunchServices database knows which apps “handle” various URL schemes. (book.hacktricks.wiki)macOS only Can get a listing of schemes + which app is the handler. Might not include all “deep link / callback” actions, only scheme registration. Permissions / sandboxing issues may limit what you see for apps not locally installed (or with special protections). utiluti
A command-line tool for macOS that works with default apps, including URL schemes / file type handlers. (GitHub) macOS Good for default handlers; doesn’t necessarily list all schemes across all installed apps, especially ones that aren't default handlers. Blog / script “Determining URL scheme handlers in macOS” (brunerd) Has examples for listing all schemes a user has registered via parsing ~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist
forLSHandlerURLScheme
. (brunerd.com)macOS Good for user’s registered scheme handlers. But not guaranteed to reveal every app’s scheme even if installed (only those that “claim” responsibility or are in the handlers database). xcall
CLI toolLets you invoke x-callback-urls from the command line. It doesn't scan for all schemes; it’s for sending / executing URL-callback requests. (GitHub) macOS Useful for testing / triggering, not for discovery.
- There is no known official Apple CLI that enumerates all URL schemes / x-callback endpoints for all installed apps on iOS devices (especially non-jailbroken ones). Apple’s APIs are restrictive for privacy/security.
- Even for macOS, sandboxed apps or ones with special entitlements might not be exposed fully via LaunchServices or other public APIs.
- For iOS, unless you have the IPA or source, many apps don’t publicly document all their URL schemes or x-callback-url actions.
- “x-callback-url” is a convention; support for the callback parameters (x-success etc) isn’t guaranteed just by defining a scheme.
If you want a more automatic / scripting approach, here are some ideas:
-
On macOS: Use
lsregister -dump
+ grep / parse forURL scheme
entries. That can give you a list of schemes and which app handles them. Combine withmdls
orplutil
to inspectInfo.plist
of installed.app
bundles (in/Applications
,~/Applications
) to get all declared schemes. -
On iOS (device-attached): If you can extract the IPA (via Configurator or other device management tools), then script unzipping all IPAs and parsing their
Info.plist
files. -
Mobile device management (MDM) or enterprise tools: These might allow querying installed apps with more metadata (including URL schemes), depending on permissions.
-
Reverse engineering / static analysis tools: Tools like
classdump
,strings
, etc. Or using tools likefrida
to sniff or probe URL handling, though that gets more ad hoc.
If you like, I can try to put together a small open-source script (bash / Swift / Python) that, when run on a macOS machine, lists all installed apps + their URL schemes / CFBundleURLTypes, and another tool that works with a connected iOS device (if possible). Do you want me to pull that together?
Me:
Sure. But if it doesn't need to be a full script and it can just be a few one liners, that would be ideal; but if it needs to be a script, then do it as a zsh script unless there is a strong reason why we should use something else
ChatGPT:
Nice — below are compact, practical one-liners (plus a small zsh script you can drop in if you want a cleaner output) for macOS and iOS workflows that enumerate
CFBundleURLSchemes
(and therefore the candidates for x-callback-style URLs). I prioritized CLI solutions and included the device-side options (Apple Configurator + libimobiledevice) with references so you can follow up. I also note limitations and caveats at the end.
CFBundleURLSchemes
is where apps declare URL schemes in their Info.plist. (Apple Developer)- On macOS you can query LaunchServices (the LSHandlers plist or
lsregister
) or scan app bundles’Info.plist
. Good writeups + examples: brunerd / HackTricks. (Brunerd) - On iOS the usual approaches are: extract the
.ipa
(Apple Configurator can expose temporary IPAs), or uselibimobiledevice
tools / an iTunes backup to get the app bundle/Info.plist. (farkashtech.com)
- List schemes the user/LaunchServices knows about (fast, user-wide):
plutil -convert json -o - ~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist \ | jq -r '.LSHandlers[]?.LSHandlerURLScheme' \ | sort -u
- What it does: converts the LaunchServices preferences to JSON and extracts all
LSHandlerURLScheme
entries (these are schemes the system knows handlers for). Good for a quick inventory of registered schemes. (Brunerd)
- Dump LaunchServices DB directly (another angle):
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump \ | sed -n '/URL scheme/,$p' | grep -E 'URL scheme|path:|bundle id' -B1 -A1
lsregister -dump
shows what LaunchServices has indexed (useful for debugging/extra info). See HackTricks / LaunchServices docs. (HackTricks)
- Scan all local .app bundles for declared
CFBundleURLSchemes
(per-app authoritative source):
for app in /Applications/*.app ~/Applications/*.app; do plist="$app/Contents/Info.plist" [ -f "$plist" ] || continue plutil -convert json -o - "$plist" \ | jq -r '.CFBundleURLTypes[]?.CFBundleURLSchemes[]? as $s | "\(.CFBundleName // \"$(basename \"$app\")\")\t\($s)"' \ 2>/dev/null done | sort -u
- What it does: reads each app
Info.plist
, prints the app name + scheme. This is the most accurate declared list for apps installed as.app
bundles on the Mac.
Save as
list_mac_url_schemes.zsh
and run:#!/usr/bin/env zsh # list_mac_url_schemes.zsh - list app -> CFBundleURLSchemes as CSV typeset -a dirs=(/Applications "$HOME/Applications" /Applications/Utilities) echo "app_path,bundle_id,app_name,scheme" for d in $dirs; do for app in "$d"/*.app(N); do plist="$app/Contents/Info.plist" [ -f "$plist" ] || continue json=$(plutil -convert json -o - -- "$plist" 2>/dev/null) || continue bundle=$(echo "$json" | jq -r '.CFBundleIdentifier // empty') name=$(echo "$json" | jq -r '.CFBundleName // .CFBundleDisplayName // empty') echo "$json" | jq -r --arg app "$app" --arg bundle "$bundle" --arg name "$name" \ '.CFBundleURLTypes[]?.CFBundleURLSchemes[]? | [$app,$bundle,$name,.] | @csv' 2>/dev/null done done
- Requires
jq
. Output is CSV:app_path,bundle_id,app_name,scheme
.
Important: iOS doesn’t expose a system-wide CLI equivalent to LaunchServices for third-party apps on non-jailbroken devices. The reliable ways require either extracting the app bundle (
.ipa
) or using backup/MDM mechanisms. Two practical options:-
Use Apple Configurator 2: add/download the app while device connected; the temporary
.ipa
appears under the Apple Configurator cache (you can watch that folder). See a walkthrough + a small monitor script. (farkashtech.com) -
Once you have
app.ipa
, extract the Info.plist and read schemes:
unzip -p app.ipa 'Payload/*.app/Info.plist' > /tmp/Info.plist plutil -convert json -o - /tmp/Info.plist | jq -r '.CFBundleURLTypes[]?.CFBundleURLSchemes[]?'
- That yields the declared schemes for that app’s bundle.
libimobiledevice
(andideviceinstaller
/idevicebackup2
) can enumerate installed apps and help create backups that contain app metadata you can inspect. It’s FOSS and widely used for tooling around iOS devices (non-jailbroken). Example flow: list apps, then back up / extract app container or Info.plist via backup tools, then parseCFBundleURLTypes
. (libimobiledevice)
Example commands (install
libimobiledevice
via Homebrew / package manager):# list installed apps (bundle ids) ideviceinstaller -l # (advanced) make a backup and extract Info.plist from the backup image of the app # (exact steps depend on the version of libimobiledevice and iOS; see libimobiledevice docs)
(Practical note:
ideviceinstaller
/ifuse
/idevicebackup2
have different capabilities on different OS/iOS versions — check the docs.) (libimobiledevice)
- x-callback-url ≠ URL scheme: the x-callback spec is a convention (callbacks & parameters). Finding a scheme doesn’t guarantee the app supports x-callback parameters like
x-success
. You must test or find app docs/SDK to confirm. (Apple Developer) - iOS (non-jailbroken): you generally can’t enumerate every installed app’s internals remotely without extracting the IPA or using backup/MDM-level access — Apple intentionally restricts this for security/privacy. Apple Configurator or an MDM provide the practical workaround for non-jailbroken devices. (farkashtech.com)
- LaunchServices / LSHandlers: on macOS the LaunchServices DB shows handlers the system knows about, but it may not list every possible scheme that an app declared internally (scanning the app bundle itself is the authoritative source for declared schemes). (Brunerd)
- Convert the macOS script into a single executable zsh file that outputs a neat CSV/JSON and includes optional
sudo
scanning of system app locations. - Produce a small Apple Configurator watcher script (based on the monitor example) that auto-copies IPAs for you and then runs the extraction pipeline. (I can drop that in zsh form.)
- Build a tiny CLI
scan-schemes
zsh tool that tries LaunchServices → local app Info.plist → optionally extracts IPAs from a given folder and prints consolidated results.
Tell me which of the three and I’ll produce it as a ready-to-run zsh script. (If you want the full CSV zsh script now, tell me and I’ll paste it — it’s quick.)
- On iOS/macOS, apps that support custom URL schemes list them in their
-
This section covers workflow automation tools such as Apple Shortcuts, Alfred, BetterTouchTool, etc; and how they can be integrated and triggered.
See Also:
See Also:
TODO:
- https://support.apple.com/en-au/guide/shortcuts-mac/apd455c82f02/mac
-
Run shortcuts from the command line
-
You can use the Terminal app on your Mac to run a shortcut from the command line. Running shortcuts from the command line is no different from running shortcuts in the Shortcuts app — you can pass documents, images, text and more. Then the shortcut can pass the output to another process or write to a file.
-
Although you can run nearly any shortcut from the command line, the most efficient shortcuts are ones that don’t show alerts or ask for input. When a shortcut asks for input, the command line process pauses, awaiting user input. Instead of using a Select action, configure your shortcut to receive specific content as input, and if no input is received ask the for the content.
-
Running shortcuts from the command line
-
Shortcuts are run using the
shortcuts
command.- eg.
shortcuts run "The Shortcut Name"
- eg.
-
You can pass images to shortcut using the
-i
or--input-path
flag.- eg.
shortcuts run "The Shortcut Name" -i ~/Desktop/*.jpg
- eg.
-
If your shortcut ends with an action that produces text, images or some other file, or if you use the Stop and Output action, you can add the
-o
or--output-path
flag to intelligently write the output to a file. For example, you could output text to a PDF or TXT file by providing a path with the proper file extension.To run the “Combine Images” shortcut combining all the images on the Desktop to a PNG file, you could use the following:
shortcuts run "Combine Images" -i ~/Desktop/*.jpg -o ~/Desktop/combined.png
-
If the shortcut has an action that ends with output or has a Stop and Output action, you can pipe the output of a shortcut to another command using the
|
character. You can define the type of output (for example, forcing the output to be a JPEG instead of text) by using the--output-type
flag with a Uniform Type Indicator.To run the “Combine Images” shortcut combining all the images on the Desktop and passing to another command as an RTFD, you could use the following:
shortcuts run "Combine Images" -i ~/Desktop/*.jpg --output-type com.apple.rtfd | …
-
For a list of Uniform Type Indicators see System-Declared Uniform Type Identifiers.
-
The
shortcuts
command will exit0
on a successful run or1
on error.
-
-
Listing shortcuts on the command line
-
You can list all the shortcuts available using
shortcuts list
. You can also list shortcuts in custom folders. Use the-f
flag and provide a custom folder name. -
Note: You can only use the
-f
flag with custom folders, you cannot use generated folders such as “Quick Actions”, “Menu Bar” and so on. -
To list all your folders instead of the shortcuts, you can use the following:
shortcuts list --folders
-
-
Viewing shortcuts from the command line
-
You can open a shortcut in the editor using
shortcuts view
. This can be helpful in troubleshooting an errant shortcut.
-
-
Signing shortcuts from the command line
You can sign a shortcut that you previously exported using
shortcuts sign
. When you sign a shortcut, Apple receives a copy for validation (to prevent unauthorised tampering when you share it). Shortcut signing has two modes:- Anyone: Anyone can import your shortcut.
- People who know me: Only people who have you in their contacts will be able to import your shortcut. Your contact info will be included in the shortcut file.
To sign a shortcut named “Share me”, use the following:
shortcuts sign --mode people-who-know-me --input "Share me.shortcut" --output "Share me signed.shortcut"
For information on sharing shortcuts, see Share shortcuts on Mac.
-
Though you can use
x-callback-urls
to run and view shortcuts from the command line, you should use theshortcuts
command to be able to provide intelligent input and output. See Intro to URL schemes in Shortcuts on Mac.
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apda9578f70f/9.0/mac/26
-
Shortcut completion on Mac
-
If you expect that an action may create an issue, you can use the Stop Shortcut action or the Stop and Output action inside of an If action to halt the shortcut if a specific condition occurs. Stop actions are similar to a
return
orbreak
statement in Swift.-
Stop Shortcut: Stops the current shortcut. Place this action inside an If action to stop the shortcut when an if condition is true.
-
Stop and Output: Many shortcuts produce output content in the final action. However, some shortcuts do not yield a final output. In those shortcuts, you can add a Stop and Output action as the final action to stop the shortcut and output content that you designate in the action. You can also use this action inside of an If action to stop a shortcut early and provide an explanation for the stop. If a shortcut is one element of a more complicated automation, you can use the Stop and Output action to produce content that is handed off to the next element in the automation. If you run a shortcut from the share menu in iOS or iPadOS, or as a service in macOS, the output is sent to the app. If you run the shortcut from the Shortcuts app or outside of an app (from the Dock or menu bar, for example) and there is no place to send the output, you can choose one of the following:
- Respond: The shortcut displays the content you designate in the Stop and Output action.
- Do Nothing: The shortcut ends. No other actions are run.
- Copy to Clipboard: The content is copied to the Clipboard.
-
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apd621a1ad7a/9.0/mac/26
-
Intro to URL schemes in Shortcuts on Mac
-
You can use URL schemes in Shortcuts. A URL scheme is the part of a link that specifies the type of application your device uses to open a URL.
-
Many apps support URL schemes: FaceTime uses URL schemes to make calls when a URL starting with
facetime://
is opened, just like Safari handles URLs starting withhttp://
. -
You can also open URLs using schemes inside your shortcuts, provided by other apps. To do so, use the Open URL or Open
X-Callback
URL action.
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apda283236d7/9.0/mac/26
-
Open and create a shortcut using a URL scheme on Mac
-
The Shortcuts URL scheme allows you to open the app, create, run or edit a shortcut, and interact with the Gallery in the Shortcuts app. URL schemes can be used anywhere a URL can be used — your own app, in a web browser or in the command line.
-
Open the URL
shortcuts://
to launch the app to the state when it was last used. -
Open the URL
shortcuts://create-shortcut
to jump to the shortcut editor and to create a new shortcut. -
You can launch the app to a particular shortcut in your collection.
Open a URL with the following structure:
shortcuts://open-shortcut?name=[name]
and provide the name of the shortcut in the name parameter.
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apd624386f42/9.0/mac/26
-
Run a shortcut using a URL scheme on Mac
-
The Shortcuts URL scheme supports running a shortcut that’s saved in your shortcuts collection. This functionality may be useful in automation systems that extend beyond Shortcuts itself, so that other apps can run a shortcut in your collection. Or you could use the Shortcuts URL scheme in a task manager for running a shortcut as one step in a project. URL schemes can be used anywhere a URL can be used — your own app, in a web browser or in the command line.
-
Open a URL with the following structure:
shortcuts://run-shortcut?name=[name]&input=[input]&text=[text]
Use the following parameters in the URL:
- name: The name of the shortcut to run.
- input (optional): The initial input into the shortcut. There are two input options: a text string or the word
clipboard
. When theinput
value is a text string, that text is used. When theinput
value isClipboard
, the contents of the clipboard are used. - text: If input is set to text, the value of the text parameter is passed as input to the shortcut. If input is set to clipboard, this parameter is ignored.
By using a text string, you can provide your own URL-encoded text as input to the shortcut. For example, a URL that uses the text “
goetta is great
” as input to a shortcut named Lookup Goetta would look like this:shortcuts://run-shortcut?name=Lookup%20Goetta&input=text&text=goetta%20is%20great
A URL to transfer the most recently copied text into a shortcut called Add to Notes would look like this:
shortcuts://run-shortcut?name=Add%20to%20Notes&input=clipboard
-
Tip: If you’d like to run one shortcut from another shortcut, use the Run Shortcut action instead of a URL scheme. You should only run shortcuts with an URL if you’re integrating from another app outside of Shortcuts.
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apd9c112ca23/9.0/mac/26
-
Open or search the Shortcuts Gallery using a URL scheme on Mac
-
Shortcuts offers two URL scheme options for interacting with the Gallery: one for opening the Gallery and one for searching the Gallery. URL schemes can be used anywhere a URL can be used — your own app, in a web browser or in the command line.
-
Open a URL with the following structure:
shortcuts://gallery
Shortcuts opens, showing you the main page of the Gallery.
-
Open a URL with the following structure:
shortcuts://gallery/search?query=[query]
The
query
parameter determines the URL-encoded keywords to be searched in the Gallery.For example, if you want to send someone a link to explore shortcuts for photos available in the Gallery, you would instruct them to open
shortcuts://gallery/search?query=photos
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apdcd7f20a6f/9.0/mac/26
-
Use
x-callback-url
with Shortcuts on Mac -
Shortcuts supports
x-callback-url
, allowing the calling app to receive a response (a callback), when a particular interaction has completed. You can run shortcuts from anx-callback-url
using the same parameters as discussed in Run a shortcut using a URL scheme on Mac.For example:
shortcuts://x-callback-url/run-shortcut?name=Calculate%20Tip&input=text&text=24.99&x-success=...&x-cancel=...
Per the
X-Callback-URL
standard, the following additional parameters can be provided:x-success
(optional): An URL that opens when the interaction is successful — for example, after a shortcut is imported or has finished running. If a shortcut is run, a parameter namedresult
is appended to the URL and contains the textual output of the shortcut.x-cancel
(optional): An URL that opens when the interaction is cancelled by the user.x-error
(optional): An URL that opens when the interaction fails because an error occurred. A parameter namederrorMessage
is appended to the URL and contains a description of the error.
With
x-success
, you can provide an URL that opens after the shortcut successfully finishes running. This could be used in conjunction with a multi-step checklist of tasks, wherein you open thex-callback-url
to run a shortcut, return to the list and move on to the next task via URL.With
x-cancel
, you can provide a contingency URL to launch if the shortcut stops before it finishes running. Because the shortcut did not complete, no output from the shortcut is provided.With
x-error
, you can provide a contingency URL to launch if the shortcut encounters an error while running and fails to finish. In this case, you can fire up a different URL to handle the issue.
-
- https://support.apple.com/en-au/guide/shortcuts-mac/apd68802640c/9.0/mac/26
-
Use another app’s URL scheme in Shortcuts on Mac
Shortcuts also has the ability to integrate with other apps via their URL schemes. If you want to use an app that has URL schemes but isn’t currently supported with a built-in action, you can construct the URLs manually using the URL action and launch them using the Open URLs action or the Open X-Callback URL action.
Note: Many URL schemes can be hard to implement and debug. The schemes often include a variety of parameters and require text to be URL encoded, which can be difficult to read. That said, exploring URL schemes does provide a deeper range of customisation beyond the built-in apps included in Shortcuts.
Contact the developers of your favourite apps to see if they currently use an URL scheme, or ask them to implement URL schemes so you can automate their app in Shortcuts.
-
- TODO
- https://chatgpt.com/c/68c8d7df-3d50-8323-a86d-392369ef839b
- https://www.alfredapp.com/help/workflows/triggers/external/
- https://www.alfredapp.com/help/workflows/inbound-configuration/
- https://www.alfredapp.com/help/workflows/outputs/call-external-trigger/
- https://www.alfredforum.com/topic/18565-open-workflow-from-command-line/
- https://www.alfredforum.com/topic/11443-how-to-run-workflow-from-command-line/
- https://www.alfredforum.com/topic/21964-calling-external-triggers-with-alfredruntrigger-uri-scheme-inbound-configuration-vs-legacy-way/
- https://updates.folivora.ai/bettertouchtool_release_notes.html#:~:text=BetterTouchTool%205.622%20(September%2C%2015%2C%202025)
-
BetterTouchTool 5.622 (September, 15, 2025)
-
New
bttcli
command line utility that allows fast access BTT's scripting functions- https://docs.folivora.ai/docs/1109_cli.html
-
BetterTouchTool CLI (bttcli) Documentation
-
BetterTouchTool provides a Unix socket server that allows external applications to communicate with BTT through the socket at
/tmp/com.hegenberg.BetterTouchTool.sock
. Thebttcli
tool is a command-line interface that communicates with this socket server.The Command Line / Socket Server support needs to be enabled in the BetterTouchTool Scripting Settings first
-
- https://docs.folivora.ai/docs/1109_cli.html
-
See Also:
- TODO
- https://x-callback-url.com/
-
x-callback-url
-
x-callback-url
is an app inter-app communication protocol allowing apps to communicate over custom URL schemes. -
The goal of the
x-callback-url
specification is to provide a standardized means for iOS developers to expose and document the methods they make available to other apps via custom URL schemes. Usingx-callback-url
, source apps can launch other apps passing data and context information, and also provide parameters instructing the target app to return data and control back to the source app after executing an action. Specific supported actions will be dependent on the individual apps and will not be discussed in the specification. -
x-callback-url
has been adopted by many high profile apps on Apple’s platforms, including Apple’s own Shortcuts. - https://x-callback-url.com/specification/
-
Specification
-
x-callback-url
1.0 DRAFT, R3 -
The
x-callback-url
specification is intended to standardize the use of URLs and registered URL schemes for inter-app communication and messaging on Apple’s platforms. -
Although originally intented for iOS,
x-callback-url
can, and has, been implemented on macOS and other platforms. If you implementx-callback-url
in your app(s) it is highly recommend you support the same custom URL functions on all platforms your app supports. -
URL Structure
[scheme]://[host]/[action]?[x-callback parameters]&[action parameters]
-
- https://x-callback-url.com/examples/
-
Examples
-
Example (One-way communication)
-
Example (Two-way communication)
- https://developer.apple.com/documentation/uikit/uiapplication
-
UIApplication
-
The centralized point of control and coordination for apps running in iOS.
-
Apps can cooperatively handle a resource, such as an email or an image file, through the
open(_:options:completionHandler:)
method.- https://developer.apple.com/documentation/uikit/uiapplication/open(_:options:completionhandler:)
-
open(_:options:completionHandler:)
-
Attempts to asynchronously open the resource at the specified URL.
-
- https://developer.apple.com/documentation/uikit/uiapplication/open(_:options:completionhandler:)
-
Determine whether there is an installed app registered to handle a URL scheme (
canOpenURL(_:)
)- https://developer.apple.com/documentation/uikit/uiapplication/canopenurl(_:)
-
canOpenURL(_:)
-
Returns a Boolean value that indicates whether an app is available to handle a URL scheme.
-
- https://developer.apple.com/documentation/uikit/uiapplication/canopenurl(_:)
-
-
- https://x-callback-url.com/implementation/
-
Implementation
-
- https://x-callback-url.com/apps/
-
Apps
-
Below is a small sampling of apps supporting
x-callback-url
. Links provided are to documentation regarding their available actions.
-
-
- https://dmbuil.github.io/posts/how-to-find-the-url-scheme-for-an-ios-app/
-
How to find the URL Scheme for an iOS App (Mar 11, 2025)
-
A quick guide to find the URL Scheme for an iOS App and other reverse engineering tricks
- TODO: Add summary snippets/extracts of this blog here
-
- https://jc0b.computer/posts/spelunking-for-url-schemes/
-
Spelunking for URL schemes: finding URL schemes supported by macOS apps (2024-05-16)
- TODO: Add summary snippets/extracts of this blog here
-
- https://www.brunerd.com/blog/2022/09/21/determining-url-scheme-handlers-in-macos/
-
Determining URL scheme handlers in macOS (September 21, 2022)
- TODO: Add summary snippets/extracts of this blog here
-
- https://blog.ericturner.it/2022/04/01/finding-x-callback-url-deep-link-of-ios-apps/
-
Finding
x-callback-url
/ Deep Link of iOS Apps (Apr 1, 2022) -
I find often I like doing automations between apps. While you can use the Open App functionality with Shortcuts, trying to open an app from something like a Reminder requires a URL. This guide shows you how to get the iOS App from the App Store for investigation and then search through the file for the URL Scheme.
-
Getting an
.ipa
File (macOS only) -
Opening the
.ipa
File -
Finding the Callback URL
-
The file we need is
Info.plist
. Open it in finder or display it in Terminal withcat Info.plist
, you are looking forCFBundleURLSchemes
-
-
Example 2 – Shortcuts App
-
Some apps have many options, as seen below with Apple’s Shortcuts app. In this case, any one of the URL schemes will work in Safari / Shortcuts such as
shortcuts://
orworkflow://
.
-
-
- https://utf9k.net/questions/macos-invoke-x-callback-url/
-
How can I try out
x-callback-url
commands on macOS? (April 16, 2021) -
There is a CLI tool called
xcall
which seems to be the only way I've seen to actually interact withx-callback-url
outside of other applications. - TODO: Add summary snippets/extracts of this blog here
- https://github.com/martinfinke/xcall
-
xcall
-
Call
X-Callback-URL
s From the macOS Command Line -
Call
X-Callback-URL
s From the Command Line. Outputs thex-success
andx-error
responses tostdout
/stderr
. - martinfinke/xcall#10
-
Does it still work?
-
-
-
- https://www.amerhukic.com/finding-the-custom-url-scheme-of-an-ios-app
-
Finding the custom URL scheme of an iOS app (March 14, 2019)
- TODO: Add summary snippets/extracts of this blog here
-
- https://book.hacktricks.wiki/en/macos-hardening/macos-security-and-privilege-escalation/macos-file-extension-apps.html
-
macOS File Extension & URL scheme app handlers
- TODO: Add summary snippets/extracts of this blog here
- https://newosxbook.com/tools/lsdtrip.html
-
LSDTrip - Take a ride down the
LaunchServices.framework
rabbithole - TODO: Add summary snippets/extracts of this page here
-
-
- https://forums.getdrafts.com/t/list-of-apps-with-x-callback-url-spec/11703
- https://app-talk.com/
-
Let iOS apps talk
-
A user contributable directory of iOS apps with
x-callback-urls
. - https://app-talk.com/#jumpToApps
-
All apps (61)
-
- https://app-talk.com/about/
-
This site is about documenting iOS apps that support URLs to do certain actions. Part of that is a standard called
x-callback-url
-
This site aims to document apps and their URLs in a standardized and easy-to-parse way. It also aims to stay up-to-date by allowing everyone to participate.
-
- https://github.com/pietropizzi/app-talk
-
Let iOS apps talk - A user contributable directory of iOS apps with
x-callback-urls
. -
Motivation
While tinkering with the amazing Workflow app I discovered x-callback-url, a way to let apps to talk to each other through URLs with standardized callback parameters. This looked amazing.
I then wanted to find out which apps already supported this and found that the current app directories are outdated / not exhaustive. As it quite often happens documentation is not always up-to-date.
So I wanted to fix this. And the only way to have a chance to stay up-to-date is to crowd source the documentation. So this repository allows for exactly that.
- https://github.com/pietropizzi/app-talk/tree/master/data/apps
- https://github.com/pietropizzi/app-talk/blob/master/data/app-template.json
- https://github.com/pietropizzi/app-talk/blob/master/CONTRIBUTING.md#how-to-contribute
-
How to contribute
The repository for this site can be found at https://github.com/pietropizzi/app-talk and that is where you will have create a Pull Request with your changes.
The documentation you can see here is all found in
.json
files in /data/apps. Each app has it's own file that has some basic information about the app plus all of its actions.
-
-
-
- https://airtable.com/appI8ZrbVAR9e7XxL/shrydOqT26KkIYWnd/tblKvdyluAeC7EhO9/viwjm68Mui0xTdkqd
-
x-callback-url
-
List of Apps (iOS/macOS) that support the
x-callback-url
spec with links to their official documentation.Verified Apps
- The App have (official) documentation provided by the developer.
- The App is listed on the official x-callback-url website.
Unverified support
These are Apps come from sources like AppTalk, One Tap Less but haven't been verified yet.
Custom
App specific callback specification and methods. Either through Universal Links, API or the Siri Shortcuts App.
-
- https://web.archive.org/web/20230402084649/https://onetapless.com/library
-
x-callback-url
Library -
A collection of apps with
x-callback-url
support and their documentations
-
- https://www.opener.link/
-
Opener for iOS
-
Open links in apps
-
Opener allows you to open links from the web in apps instead! Simply copy a link and launch Opener to view opening options.
- https://www.opener.link/apps.html
-
Opener for iOS
-
Supported Apps: 245 Total
-
Supported Browsers: 41 Total
-
- https://www.opener.link/api.html
-
Opener API
-
Opener implements actions using the
x-callback-url
API spec with theopener://
scheme.
-
- https://objectionable-c.com/posts/opener-10/
-
Your Links, Your Way — Ten Years of Opener (Jun 1, 2025)
-
Today Opener turns 10 years old. It’s safe to say Opener is the side project that I’m most proud of, and has had the most success on the App Store. I wanted to take some time to reflect on the past 10 years building it. This blog post won’t be too technical, it’s mostly a collection of little stories and thoughts.
-
- https://objectionable-c.com/posts/shrink-static-files/
-
Trim the Fat: Static file tricks to slim down your app (Jul 25, 2025)
-
For large JSON files this whitespace can be significant. For example: in Opener’s rule set JSON whitespace accounts for 45% of the original file size. We can safely strip out this whitespace as a build step to reduce JSON file size while preserving the original data. Just like plists, there are other formats like .ahap that are just JSON under the hood that we can also tidy up.
-
Using these strategies I’ve made a couple of scripts you can use to reduce your app’s size, available here.
- https://github.com/timonus/appscripts
-
appscripts
-
A collection of useful build step scripts for iOS apps
-
To reduce your app’s size these scripts can be invoked as a build ste
-
- https://github.com/timonus/appscripts
- This blog post talks about compressing JSON as well as XML
.plist
files to their binary format to reduce space; and in it's examples it seems to talk about Opener; so may provide pointers if someone wanted to try and extract the modern.json
rules from that app or similar.
-
- https://web.archive.org/web/20220824022632/https://github.com/timonus/OpenerManifest
-
Opener Manifest
-
Opener is an app for iOS that allows people to open web links in native apps instead. It does so by transforming web links within an engine powered by a rule set. This repo is the public version of that rule set.
-
Apache-2.0 license
- https://web.archive.org/web/20220120074850/https://github.com/timonus/OpenerManifest/blob/master/openerManifest-v5.json#start-of-content
- https://gist.github.com/katagaki/104aa07f7b61185253bffc5ad2babbc6#file-openermanifest-v5-20220120-json
-
katagaki/openerManifest-v5.20220120.json
-
Opener manifest (
openerManifest-v5.json
) archived from 20 January 2022 from https://github.com/timonus/OpenerManifest/blob/master/openerManifest-v5.json - https://gist.github.com/0xdevalias/b5c9514516d938b15e7dc00d4f6e557a#file-openermanifest-v5-20220120-json
-
0xdevalias/openerManifest-v5.20220120.json
-
Forked from katagaki/openerManifest-v5.20220120.json
-
Opener manifest (
openerManifest-v5.json
) archived from 20 January 2022 from https://github.com/timonus/OpenerManifest/blob/master/openerManifest-v5.json
-
-
- https://gist.github.com/katagaki/104aa07f7b61185253bffc5ad2babbc6#file-openermanifest-v5-20220120-json
- https://github.com/search?q=OpenerManifest&type=repositories
- https://github.com/whtsky/OpenerManifest
- https://github.com/whtsky/OpenerManifest/blob/master/openerManifest-v1.json
- Latest Commit: Jul 21, 2015 (
a9233e3a817cae652b610d2daf1f9933d5479b92
)
- Latest Commit: Jul 21, 2015 (
- https://github.com/whtsky/OpenerManifest/blob/master/openerManifest-v1.json
- https://github.com/zamoshchin/OpenerManifest
-
This branch is 1295 commits ahead of
whtsky/OpenerManifest:master
. -
Apache-2.0 license
- https://github.com/zamoshchin/OpenerManifest/blob/master/openerManifest-v5.json
- Latest Commit: Sep 1, 2022 (
cc4c96d97a88973bced9c4e81cbbaccd3aafb02e
)
- Latest Commit: Sep 1, 2022 (
-
- https://github.com/whtsky/OpenerManifest
-
-
- https://app-talk.com/
- TODO: Investigate these links further + capture as appropriate
- https://github.com/scriptingosx/utiluti#url-schemes
-
utiluti
-
A macOS command-line to work with default apps
-
macOS command line utility to work with default apps.
-
You can use
utiluti
to inspect and modify default apps for url schemes and file types/uniform type identifiers (UTI). - https://github.com/scriptingosx/utiluti#url-schemes
-
URL schemes
-
URL schemes are the part of the URL before the colon
:
which identify which app or protocol to use. E.g.http
,mailto
,ssh
, etc.
-
- https://github.com/scriptingosx/utiluti#file-typeuniform-type-identifiers-uti
-
File Type/Uniform Type Identifiers (UTI)
-
Uniform type identifiers (UTI) are how macOS maps file and mime types.
utiluti
uses UTIs.
-
- https://github.com/scriptingosx/utiluti#getting-an-apps-declarations-and-other-information
-
Getting an App's declarations and other information
-
utiluti
can list the UTIs and url schemes an app has declared in theirInfo.plist
-
- https://github.com/scriptingosx/utiluti#default-app-for-specific-files
-
Default app for specific files
-
macOS allows for a file to be assigned to an app different from the general default app for that file type.
utiluti
has thefile
verb to inspect or set the default app for a specific file.
-
- https://github.com/scriptingosx/utiluti#setting-multiple-defaults
-
Setting multiple defaults
-
The
manage
verb reads multiple default app assignments from files or from user defaults/configuration profiles.
-
- https://github.com/scriptingosx/utiluti#from-defaults-and-managed-preferences
-
From defaults and managed preferences
-
For managed deployments, the settings can be read from a configuration profile.
-
-
- https://github.com/scriptingosx/utiluti#url-schemes
- https://macmost.com/mac-settings-links
-
Mac System Settings Links
By using the
x-apple.systempreferences
URL/URI scheme, you can launch the System Settings app and have it go straight to a section. This can come in handy to create Shortcuts or shell scripts that give you quick access to settings. For instance, these can be used in the Terminal to open parts of System Settings with a command like this:open "x-apple.systempreferences:com.apple.Siri"
They can also be used in Shortcuts with the Open URLs action. Just add
x-apple.systempreferences:
before the URL. See after the table for more details.This list was last updated on November 18, 2024 using macOS Sequoia 15.2.
-
Looking to do this on iOS or iPadOS? It works the same way, but the URLs are completely different. Here is a list of some of those links.
- https://github.com/FifiTheBulldog/ios-settings-urls
-
ios-settings-urls
-
A collection of iOS Settings URLs
-
For a long time, I’ve relied on MacStories’ research for Settings URLs, which have no official documentation from Apple. However, as users on r/shortcuts began to request URLs that were not in the MacStories archive, I did some digging and found about 50 more. Since then, this list has continued to grow to its present form, presented here. Many of the URLs are from MacStories, but some of them are from other users' efforts or my own trial and error. I also corrected a few MacStories ones that no longer work for me.
- https://github.com/FifiTheBulldog/ios-settings-urls#the-settings-url-scheme
- https://github.com/FifiTheBulldog/ios-settings-urls/blob/master/settings-urls.md
-
Settings URLs
-
- https://github.com/FifiTheBulldog/ios-settings-urls/blob/master/deprecated.md
-
Deprecated URLs
-
These URLs may have worked at one point, but have not worked when I've tried them on the latest version of iOS. These may work on older versions of iOS, however.
-
- https://github.com/FifiTheBulldog/ios-settings-urls/blob/master/preference-manifest-dump.txt
- https://github.com/FifiTheBulldog/ios-settings-urls/blob/master/dyld-shared-cache-dump.txt
-
- https://github.com/FifiTheBulldog/ios-settings-urls
-
- https://github.com/bvanpeski/SystemPreferences
-
System Preferences
-
Navigating System Prefences/Settings on macOS
-
Collection of methods for activating parts of System Preferences / System Settings on macOS.
- https://github.com/bvanpeski/SystemPreferences/blob/main/macos_preferencepanes-Ventura.md
-
How to open every macOS System Settings Section (macOS 13+)
-
Here is a complete list of System Settings Sections (as of macOS Sonoma 14.2) and how to open them with a bash command.
macOS Ventura and newer operating systems use a new extension framework but still support some older prefpane calls. Who knows how long those will continue to work, but I've listed them here alongside their more modern counterparts to help identify calls that might work across both Monterey and newer versions of macOS if you have a mixed fleet. Those items are noted by the
legacy
tag. - https://www.macosadventures.com/2022/12/05/how-to-open-every-section-of-macos-ventura-system-settings/
-
How to open every section of macOS Ventura System Settings (2022-12-05)
-
How do I identify the sections of Ventura’s new System Settings?
Apple has made identifying the different sections of System Settings significantly easier in macOS Ventura. In fact, the majority of them are stored in a plist right inside of the app itself! Check it out at
/System/Applications/System Settings.app/Contents/Resources/Sidebar.plist
-
There are still a handful of items in System Settings that you can link to that are not sidebar items, and thus not in that plist. One method for digging those out of the app itself is by using the
strings
command to pull out any potential strings out of System Settings that may belong to those deeper submenus beyond the sidebar.for pref in $(strings "/System/Applications/System Settings.app/Contents/MacOS/System Settings" | awk '/^com.apple./ {print $1 }'); do echo "$pref"; done
-
-
- https://github.com/bvanpeski/SystemPreferences/blob/main/macos_preferencepanes-Monterey.md
-
How to open every macOS System Preferences Pane
-
Here is a complete list of System Preferences Panes (as of macOS Monterey 12.2.1) and how to open them with a bash command. Not all panes support a URLScheme to open, but for those that do not you can use Applescript.
- https://www.macosadventures.com/2022/02/06/scripting-system-preferences-panes/
-
Scripting System Preferences Panes (2022-02-06)
-
This url schemes listed here are for macOS Monterey. You may have limited success with older operating systems depending on how much System Preferences has changed between operating system versions and if those panes previously supported UrlScheme or not.
-
-
-
- 0xdevalias/dotfiles#32
-
[bin] Create CLI helpers for triggering automation tools (Shortcuts, Alfred, BetterTouchTool, etc)
-
Add a unified CLI helper script (maybe also with lightweight shims/aliases) to trigger actions across workflow automation tools like Apple Shortcuts, Alfred, and BetterTouchTool.
This would provide a consistent way to invoke automations from the terminal, while keeping tool-specific integrations (e.g.
shortcuts run
,bttcli
, etc) easily accessible, while wrapping more complex integrations (e.g. Alfred external triggers) in a nice CLI tool.The goal is both discoverability and convenience — a single entrypoint for calling into each tool, plus optional aliases to make common actions more straightforward.
-
- https://github.com/0xdevalias
- https://gist.github.com/0xdevalias
- Event / Workflow Automation Systems (0xdevalias' gist)
- Decompile Apple Shortcuts into raw XML 'source code' (0xdevalias' gist)
- BetterTouchTool Generic Device Trigger PoC for Razer Ouroboros gaming mouse (0xdevalias' gist)
- Reverse Engineering on macOS (0xdevalias' gist)
- Reverse Engineering macOS Passwords Pane Internals: Searching for Hidden
x-apple.systempreferences
URL Anchors throughPasswords.prefPane
,PasswordsSettingsExtension.appex
, PrivateFrameworks (PasswordManagerUI.framework
,Settings.framework
), dyld Cache, etc (0xdevalias' gist)