Link Search Menu Expand Document

The Bunch AppleScript Dictionary

Bunch provides an AppleScript dictionary that you can use to open, close, and toggle Bunches, process raw text, or access snippets.

List all Bunches

The following commands return AppleScript lists:

-- list all Bunches in current Bunch Folder
tell application "Bunch" to list bunches

-- list currently open Bunches
tell application "Bunch" to list open bunches

You can test if a particular Bunch is open by searching for its name in list open bunches (e.g. if (list open bunches) contains). You can also get a list of closed bunches by getting the full list (list bunches) and removing items in list open bunches. It’s not the easiest approach, I know, but I haven’t had a need for these options yet, so I haven’t added methods for them.

Open, close, and toggle Bunches

tell application "Bunch" to open bunch "Comms"

tell application "Bunch"
    close bunch "Default"
    toggle bunch "Comms"
end tell

Acting on tagged Bunches

You can also act on tagged Bunches

-- list bunches containing tag string
tell application "Bunch" to list bunches tagged "tag1+tag2"

-- perform actions on all Bunches matching tag (or tag combo)
tell application "Bunch"
    open tag "Tag1"
    close tag "Tag2+Tag3"
    toggle tag "Tag2,Tag3"
end tell

Process raw Bunch text

You can also process raw Bunch text:

tell application "Bunch"
    process text "(dnd on)"
end tell

Tip: Use \n in the string to add newlines, useful for adding dashed parameters/variables when calling scripts or snippets.

Tip: raw text processing is also useful in scripts where you want to read in the contents of a Bunch, modify them in some way, then execute the result. It won’t mark that Bunch as “open” when it executes, but it’s one way to add dynamic processing.

Snippets, fragments, and variables

You can access snippets directly with options to target fragments and pass variables.

run snippet text ¬
     fragment text ¬
     with variables text


Parameter Required Type Description
direct parameter required text snippet path, absolute or relative to configured Bunch folder
fragment optional text fragment specifier
with variables optional text query string formatted list of key/values

The with variables parameter accepts a string of text formatted like a URL query string, with key=value pairs separated by ampersands (&). If your value needs to include an actual ampersand, url encode it as %26 in the query string.

tell application "Bunch"
    run snippet "useful.snippets" fragment "Spotify" with variables "url=spotify:​playlist:4AEt6vXGJYmyOEE8zzgvjQ&autoplay=false"
end tell


You can retrieve several of Bunch’s preferences using AppleScript, which avoids the need to use defaults in shell scripts.

tell application "Bunch"
   get preference "Bunch Folder"
end tell

All values are returned as text. Boolean values (which is everything other than “Bunch Folder” and “Debug Level”) will return text containing either “0” (false) or “1” (true). Debug Level returns text containing a number between 0 (errors only) and 4 (debug messages).

When returning a preference, Bunch just looks for keywords. As long as the text given to get preference includes one of the following words, it will return the associated preference:

Keyword Preference
“folder” or “directory” Bunch Folder
“toggle” Toggle Bunches
“single” Single Bunch Mode
“debug” Debug Level (0-4)
“preserve” Preserve Bunches

Refresh Browsers

If your Bunches make use of the display command to create single site browsers, you can reload their contents via AppleScript. This takes effect on all browsers opened by a Bunch, or you can affect all open browsers. You can’t currently target a specific browser window.

To refresh every open browser:

tell application "Bunch"
    refresh browsers
end tell

To refresh only browsers opened by a specific bunch:

tell application "Bunch"
    refresh browsers for bunch "Bunch Name"

The bunch name is case insensitive and the best match will be targeted.

New Bunch with Open Apps

The “New Bunch with Open Apps” command is available to AppleScript as [copy/save] new bunch with running apps. This takes an optional named parameter to define the title and filename of the new Bunch. If this is left off, the Bunch receives no title frontmatter and the file is named “New Bunch.bunch”. If a file with the given name exists, a number will be appended to it and incremented until the filename is unique.

You can also add an ignoring parameter, which accepts a list of application names to exclude from the Bunch. These names must match the app names exactly, including capitalization.

To save a new Bunch with all running apps as “Working.bunch”:

tell application "Bunch"
    save bunch with running apps named "Working"
end tell

To copy all apps to the clipboard, ready to paste into a new Bunch:

tell application "Bunch"
    copy bunch with running apps

To save a new Bunch named “Working,” excluding iTerm and Firefox:

tell application "Bunch"
    save bunch with running apps named "Working" ignoring {"iTerm2", "Firefox"}