Link Search Menu Expand Document

Bunch has its own URL scheme (x-bunch:) that you can call from other apps and scripts.

Tip: You can use simple shell scripts with apps like BetterTouchTool and Keyboard Maestro to assign bunches to hotkeys. If you have a cool programmable keypad, just imagine the possibilities…

Just create an action that opens a URL and use something like x-bunch://toggle/BunchName to create a hotkey or button that toggles a Bunch. You can create a whole control panel on a Stream Deck with these, for example.


See the x-success parameter to control what happens after a URL method is executed.


The full version of the open method is x-bunch://open?bunch=[BUNCH NAME]. The url can be shortened, though, to just the Bunch name: x-bunch://[BUNCH NAME].


(String) The name of the bunch to open, without the .bunch extension


# Full URL
open 'x-bunch://open?bunch=Comms'

# Shortcut URL
open 'x-bunch://Comms'

The Bunch name in the URL handler is case insensitive, so “bunch name” works just as well as “Bunch Name.” Bunch does need to already be running in order to execute a bunch via the URL handler. You can always launch Bunch with open -a Bunch from a script, but you’ll need to give it enough time to initialize.

Tip: If you have a task in a task manager that requires a certain set of apps, create a Bunch and then add a link to the task’s notes: x-bunch://open/WorkBunch


You can also close a Bunch with x-bunch://close?bunch=[BUNCH NAME], or just x-bunch://close/[BUNCH NAME].


(String) The name of the bunch to close, without the .bunch extension


# Full URL
open 'x-bunch://close?bunch=Comms'

# Shortcut URL
open 'x-bunch://close/Comms'


You can also toggle the Bunch — opening if it’s closed, closing if it’s open — using x-bunch://toggle?bunch=[BUNCH NAME]. Like the other methods, this also works as x-bunch://toggle/[BUNCH NAME]. This works even if “Toggle Bunches” isn’t enabled.

If using the “Toggle Bunches” option, Bunches opened/closed via the URL handler will automatically set the launched state of the Bunch in the Dock menu. The open and close commands will not toggle Bunches; the commands will execute regardless of current Bunch state.


(String) The name of the bunch to toggle, without the .bunch extension


# Full URL
open 'x-bunch://toggle?bunch=Comms'

# Shortcut URL
open 'x-bunch://toggle/Comms'


You can pass Bunch commands and directives directly through the URL handler. With this you can specify a path to a Bunch file outside of your Bunches folder, or even pass a url-encoded string containing Bunch directives.


Only one of file or txt should be specified

(String) Either an absolute path or a path relative to the configured Bunches folder. If this is provided, any txt parameter will be ignored
(String) URL encoded text text contents to process as if read from a file


# Open a Bunch file with `file` param:
open 'x-bunch://raw?file=~/MiscBunch.bunch'

# Pass Bunch contents directly with `txt` param:
open 'x-bunch://raw?txt=%21MeisterTask'


You can set and toggle certain preferences with the setPref method.


(String) Absolute path to Bunches folder
(Boolean: 0 or 1) Set Toggle Bunches mode
(Boolean: 0 or 1) Set Single Bunch Mode


# Enable Toggle Bunches mode
open 'x-bunch://setPref?toggleBunches=1'

# Change the Bunches folder
open 'x-bunch://setPref?configDir=~/Dropbox/Sync/Bunches'


You can directly load a snippet and define variables with the snippet method. This allows you to load files containing variables and to use the snippet fragment feature to load just a portion of a snippet.


(String) The path to the snippet file. Assumes this is a relative path from your Bunch folder unless an absolute path is provided. If the snippet file is in the root of your Bunch folder, you can provide just the filename
fragment (Optional)
(String) To load just a section of the snippet (as defined by #[section title] lines), pass the name of the fragment here.
Additional variables (Optional)
Any additional query parameters added to the url string will be passed as key=value replacements to the snippet


# Load a snippet file called "useful.snippets", 
# targeting the "Music" section, and passing a 
# value to the "playlist" variable, call:
open 'x-bunch://snippet?file=useful.snippets&fragment=Music&playlist=spotify:playlist:3cSpIL4Q0H3uqdBMbT6c9x'

Additional parameters

Calling an app or URL after running a method

All url methods accept an x-success parameter which can define a bundle ID or url to open after executing the method. By default this happens after a 5-second delay, but you can modify that with an x-delay parameter (number of seconds as integer).

(String) If this is a valid bundle identifier, e.g. com.brettterpstra.marked2, that application will be launched
If this is a valid URL, that URL will be opened. This can be used with url handlers of other applications, e.g. x-marked://open/
(Integer) If specified, the number of seconds Bunch will wait before calling the x-success value. If x-success is a bundle ID, that app will be launched immediately but not activated until after the delay


# Open a bunch and then open Marked 2 after a 15-second delay
open 'x-bunch://open?bunch=Comms&x-success=com.brettterpstra.marked2&x-delay=15'

# Open iThoughts using its URL handler (default 5-second delay)
open 'x-bunch://open/Comms&x-success=ithoughts://'