Skip to main content

BetterTouchTool Action JSON Definition Reference

This document provides a first, incomplete, reference for all BetterTouchTool actions and how to define them via JSON. Actions are configured using the BTTPredefinedActionType field with the corresponding action ID.

** NOTE: WORK IN PROGRESS ** This page is mostly AI generated and might contain hallucinated properties. I'm currently working through it.

Important Notes​

JSON Format​

  • JSON objects will be automatically recognized on import - you don't need to escape them as strings
  • Fields that accept JSON objects (like BTTGenericActionConfig, BTTAdditionalActionData, etc.) can be provided as regular JSON objects instead of escaped strings

Common Fields​

  • BTTAdditionalActionData: Many actions support this field for extended configuration options. It contains a JSON object with action-specific properties
  • BTTGenericActionConfig: Used for simple configurations, can be a string or JSON object depending on the action
  • BTTGenericActionConfig2: Secondary configuration field when additional data is needed

Table of Contents​

  1. Mouse & Trackpad Actions
  2. Keyboard Actions
  3. Window Management Actions
  4. System Actions
  5. Application Control
  6. Media Controls
  7. Display & Brightness
  8. Spaces & Mission Control
  9. Screenshot Actions
  10. Clipboard Actions
  11. Text & Typing Actions
  12. Script Execution
  13. BetterTouchTool Control
  14. Touch Bar Actions
  15. Notch Bar Actions
  16. Stream Deck Actions
  17. Floating Menu Actions
  18. Control Flow Actions
  19. Variable Actions
  20. Device Control
  21. UI Automation
  22. Custom Actions
  23. AI Actions (h@llo.ai)
  24. Action Categories

Mouse & Trackpad Actions​

Left Click​

Performs a standard left mouse click at the current cursor position. It will include the currently pressed modifier keys.

Parameters:

  • BTTPredefinedActionType: 3

Example:

{
  "BTTPredefinedActionType": 3
}

Left Click - Without Modifier Keys​

Performs a left mouse click at the current location. It will NOT include any modifier keys.

Parameters:

  • BTTPredefinedActionType: 421

Example:

{
  "BTTPredefinedActionType": 421
}

Right Click​

Performs a right mouse click at the current cursor position. It will include the currently pressed modifier keys.

Parameters:

  • BTTPredefinedActionType: 4

Example:

{
  "BTTPredefinedActionType": 4
}

Middle Click​

Performs a middle mouse click at the current location. It will include the currently pressed modifier keys.

Parameters:

  • BTTPredefinedActionType: 1

Example:

{
  "BTTPredefinedActionType": 1
}

Double Left Click​

Performs a double left mouse click at the current location. It will include the current modifier keys.

Parameters:

  • BTTPredefinedActionType: 54

Example:

{
  "BTTPredefinedActionType": 54
}

Ctrl + Left Click​

Presses the ctrl modifier key and then performs a left click.

Parameters:

  • BTTPredefinedActionType: 87

Example:

{
  "BTTPredefinedActionType": 87
}

Opt + Left Click​

Presses the option modifier key and then performs a left click.

Parameters:

  • BTTPredefinedActionType: 88

Example:

{
  "BTTPredefinedActionType": 88
}

CMD + Left Click​

Presses the command modifier key and then performs a left click.

Parameters:

  • BTTPredefinedActionType: 2

Example:

{
  "BTTPredefinedActionType": 2
}

CMD + Double Left Click​

Presses the command modifier key and then performs a double left click. This can e.g. be used to open a file in a new tab in Finder.

Parameters:

  • BTTPredefinedActionType: 149

Example:

{
  "BTTPredefinedActionType": 149
}

CMD + Shift + Left Click​

Presses the command and shift modifier keys and then performs a left click.

Parameters:

  • BTTPredefinedActionType: 111

Example:

{
  "BTTPredefinedActionType": 111
}

Custom Click (Custom Mouse Buttons & Modifiers)​

Performs custom mouse clicks with various options including button type, modifiers, and click behavior.

Parameters:

  • BTTPredefinedActionType: 119
  • BTTClickType: Which mouse button/action to simulate. Possible values:
    • "left"
    • "right"
    • "middle"
    • "double_left"
    • "triple_left"
    • "button3" through "button8"
  • BTTModifiers: Array of modifier keys to be held during the click. Possible items:
    • "shift"
    • "control", "left_control", "right_control"
    • "option", "left_option", "right_option"
    • "command", "left_command", "right_command"
    • "function"
  • BTTIncludePressedModifiers: Boolean - if true, includes physically pressed modifier keys in addition to specified ones
  • BTTClickDownUpConfig: Defines how the click is performed:
    • "downAndUp" - normal click (mouse-down + mouse-up)
    • "downOnly" - press and hold only
    • "upOnly" - release only
  • BTTCustomClickConfig: JSON object containing click configuration (alternative format)
    • BTTClickCount: Number of clicks (e.g., 1 for single click, 2 for double click)
    • BTTClickButton: Mouse button (0=left, 1=right, 2=middle)
  • BTTCustomClickUpDownConfig: Additional up/down configuration (optional)
  • BTTAdditionalActionData: JSON object (optional)
    • BTTCustomClickIncludePressedModifiers: boolean - include currently pressed modifiers

Example 1 - Left Click + Shift + Command:

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "left",
  "BTTModifiers": ["shift", "command"],
  "BTTIncludePressedModifiers": false,
  "BTTClickDownUpConfig": "downAndUp"
}

Example 2 - Right Click with physically pressed keys:

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "right",
  "BTTModifiers": [],
  "BTTIncludePressedModifiers": true,
  "BTTClickDownUpConfig": "downAndUp"
}

Example 3 - Middle Click, Down-Only, with Shift and Left Control:

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "middle",
  "BTTModifiers": ["shift", "left_control"],
  "BTTIncludePressedModifiers": false,
  "BTTClickDownUpConfig": "downOnly"
}

Example 4 - Alternative format using BTTCustomClickConfig:

{
  "BTTPredefinedActionType": 119,
  "BTTCustomClickConfig": {
    "BTTClickCount": 2,
    "BTTClickButton": 0
  },
  "BTTAdditionalActionData": {
    "BTTCustomClickIncludePressedModifiers": true
  }
}

Move Mouse To Position​

Moves the mouse cursor to a specific position on screen.

Parameters:

  • BTTPredefinedActionType: 153
  • BTTMoveMouseToPosition: Position coordinates as "x,y" (legacy)
  • BTTMoveMouseRelative: 1 for relative movement, 0 for absolute (legacy)
  • BTTAdditionalActionData: JSON object with all mouse movement configuration
    • BTTMouseMoveX: X coordinate position
    • BTTMouseMoveY: Y coordinate position
    • BTTMouseMoveUnitX: X unit type (0=px absolute, 1=% of window width, 2=% of screen width)
    • BTTMouseMoveUnitY: Y unit type (0=px absolute, 1=% of window height, 2=% of screen height)
    • BTTMouseMoveAnchor: Reference point for position (see below for values)
    • BTTMouseMoveDuration: Animation duration in seconds (default: 0.2)
    • BTTMouseMoveWithoutPressedModifierKeys: boolean - ignore currently pressed modifiers
    • BTTMouseMoveScreenNameOrUUID: Target screen identifier (for named screen anchors)
    • BTTMouseMoveDragType: Drag type for drag actions (left/right/middle button)
    • BTTMouseMoveContinueDrag: boolean - continue existing drag

Anchor values:

  • 0: Default - Global position (origin top left corner of main screen)
  • 1-4: Relative to corners of active window (1=top left, 2=top right, 3=bottom left, 4=bottom right)
  • 5: Relative to center of active window
  • 6: Relative to current mouse cursor position
  • 7-10: Relative to text cursor position (7=top left, 8=top right, 9=bottom left, 10=bottom right)
  • 11-15: Relative to focused element (11=top left, 12=top right, 13=bottom left, 14=bottom right, 15=center)
  • 17: Relative to window default button center
  • 18: Relative to window cancel button center
  • 20: Relative to center of text cursor
  • 21: Relative to saved mouse cursor position (variable: saved_mouse_position)
  • 22: Relative to found image location (variable: image_location)
  • 1001-1003: Relative to corners of main screen (1001=top right, 1002=bottom left, 1003=bottom right)
  • 1004-1007: Relative to corners of screen with mouse
  • 1008-1011: Relative to corners of screen with name

Example:

{
  "BTTPredefinedActionType": 153,
  "BTTAdditionalActionData": {
    "BTTMouseMoveX": 100,
    "BTTMouseMoveY": 50,
    "BTTMouseMoveUnitX": 1,
    "BTTMouseMoveUnitY": 1,
    "BTTMouseMoveAnchor": 5,
    "BTTMouseMoveDuration": 0.3
  }
}

Save Current Mouse Position​

Saves the current mouse cursor position for later restoration.

Parameters:

  • BTTPredefinedActionType: 154

Example:

{
  "BTTPredefinedActionType": 154
}

Restore Saved Mouse Position​

Restores the mouse cursor to a previously saved position.

Parameters:

  • BTTPredefinedActionType: 155

Example:

{
  "BTTPredefinedActionType": 155
}

Start Drag​

Initiates a drag operation at the current mouse position.

Parameters:

  • BTTPredefinedActionType: 65

Example:

{
  "BTTPredefinedActionType": 65
}

Stop Drag​

Ends the current drag operation.

Parameters:

  • BTTPredefinedActionType: 66

Example:

{
  "BTTPredefinedActionType": 66
}

Toggle Mouse Speed​

Toggles between different mouse speed settings.

Parameters:

  • BTTPredefinedActionType: 126

Example:

{
  "BTTPredefinedActionType": 126
}

Toggle Cursor Size​

Toggles the cursor between normal and large size.

Parameters:

  • BTTPredefinedActionType: 123

Example:

{
  "BTTPredefinedActionType": 123
}

Set Cursor Size​

Sets the cursor to a specific size.

Parameters:

  • BTTPredefinedActionType: 411
  • BTTGenericActionConfig: Cursor size value

Example:

{
  "BTTPredefinedActionType": 411,
  "BTTGenericActionConfig": "2.0"
}

Scroll​

Sends scroll events.

Parameters:

  • BTTPredefinedActionType: 272
  • BTTScrollBy: Scroll amount and direction

Example:

{
  "BTTPredefinedActionType": 272,
  "BTTScrollBy": "5,0"
}

Shift + Click​

Presses the shift modifier key and then performs a left click.

Parameters:

  • BTTPredefinedActionType: 89

Example:

{
  "BTTPredefinedActionType": 89
}

Start Drag By Double-Click​

Starts a mouse drag operation initiated by a double-click.

Parameters:

  • BTTPredefinedActionType: 296

Example:

{
  "BTTPredefinedActionType": 296
}

Toggle Magic Mouse Touchpad Mode​

Toggles Magic Mouse touchpad mode on or off.

Parameters:

  • BTTPredefinedActionType: 68

Example:

{
  "BTTPredefinedActionType": 68
}

Change Mouse Speed And Acceleration​

Changes mouse tracking speed and acceleration settings.

Parameters:

  • BTTPredefinedActionType: 559
  • BTTAdditionalActionData: JSON object with speed configuration
    • BTTActionMouseSpeed: number - Mouse tracking speed
    • BTTActionMouseAcceleration: number - Mouse acceleration value
    • BTTActionMouseName: string - Name of the specific mouse device
    • BTTActionMouseVendorID: number - USB vendor ID of the mouse
    • BTTActionMouseProductID: number - USB product ID of the mouse
    • BTTActionMouseDropdownSelection: string - Selected device from dropdown

Example:

{
  "BTTPredefinedActionType": 559,
  "BTTAdditionalActionData": {
    "BTTActionMouseSpeed": 3.0,
    "BTTActionMouseAcceleration": 1.5,
    "BTTActionMouseName": "Magic Mouse"
  }
}

Pick Color On Screen And Write To Clipboard​

Opens a color picker to select a color from anywhere on screen and writes the result to the clipboard.

Parameters:

  • BTTPredefinedActionType: 546

Example:

{
  "BTTPredefinedActionType": 546
}

All Modifier Keys UP​

Releases all modifier keys (Fn, Shift, Ctrl, Option, Command). Useful in action sequences to ensure a clean modifier state.

Parameters:

  • BTTPredefinedActionType: 547

Example:

{
  "BTTPredefinedActionType": 547
}

Keyboard Actions​

Type String​

Types a predefined string of text.

Parameters:

  • BTTPredefinedActionType: 193
  • BTTStringToType: The string to type
  • BTTMoveCursorLeftBy: Number of characters to move cursor left after typing (optional)

Example:

{
  "BTTPredefinedActionType": 193,
  "BTTStringToType": "Hello World",
  "BTTMoveCursorLeftBy": 0
}

Paste String​

Pastes a predefined string of text (faster than typing).

Parameters:

  • BTTPredefinedActionType: 118
  • BTTStringToType: The string to paste
  • BTTMoveCursorLeftBy: Number of characters to move cursor left after pasting (optional)

Example:

{
  "BTTPredefinedActionType": 118,
  "BTTStringToType": "This text will be pasted",
  "BTTMoveCursorLeftBy": 0
}

Send Keyboard Shortcut​

Sends a keyboard shortcut to the system - just as if you had pressed it on your keyboard.

Parameters:

  • BTTPredefinedActionType: 264
  • BTTShortcutToSend: Key codes as comma-separated string. Format: modifier key codes (sorted highest to lowest), then standard key code
  • BTTShortcutModifierKeys: Modifier keys as integer (alternative to including in BTTShortcutToSend)
  • BTTShortcutUpDown: Optional - "onlyDown" to send only key down event, "onlyUp" to send only key up event

Example:

{
  "BTTPredefinedActionType": 264,
  "BTTShortcutToSend": "63,59,58,56,55,49"
}

To only send the key down event:

{
  "BTTPredefinedActionType": 264,
  "BTTShortcutToSend": "63,59,58,56,55,49",
  "BTTShortcutUpDown": "onlyDown"
}

Supported modifier key codes:

Key CodeModifier Key
63function / fn
62right ctrl
61right option / opt
60right shift
59ctrl
58option / opt
56shift
55cmd
54right command

Supported Standard key codes:

Key SymbolKey CodeKey SymbolKey Code
029Numpad 082
118Numpad 183
219Numpad 284
320Numpad 385
421Numpad 486
523Numpad 587
622Numpad 688
726Numpad 789
828Numpad 891
925Numpad 992
A0Numpad *67
B11Numpad +69
C8Numpad -78
D2Numpad .65
E14Numpad /75
F3Numpad =81
G5Numpad clear71
H4: or ;41
I34< or ,43
J38= or +24
K40> or .`47
L37? or /44
M46! or 118
N45" or '`'39
O31# or 320
P35$ or 421
Q12% or 523
R15& or 726
S1' or "39
T17( or 925
U32) or 029
V9* or 828
W13+ or =24
X7, or <43
Y16- or _27
Z6. or >47
[ or {33/ or ?44
`\ or`42] or }
^ or 622_ or -27
{ or [33`or `
} or ]30`~ or ``50

Send Shortcut to Specific App​

Sends a keyboard shortcut to a specific application.

Parameters:

  • BTTPredefinedActionType: 128
  • BTTShortcutToSend: Key codes as comma-separated string (same format as Send Keyboard Shortcut)
  • BTTShortcutApp: Bundle identifier or path of the target app, or "active app" to target the currently active/frontmost app, or "app under mouse cursor" to target the app under the mouse cursor
  • BTTShortcutSwitchToAppFirst: 1 to switch to app first, 0 otherwise
  • BTTShortcutAppUnderCursor: Set to "app under mouse cursor" for app-under-cursor mode, or "active app" for active-app mode (optional)

Example (send to specific app):

{
  "BTTPredefinedActionType": 128,
  "BTTShortcutToSend": "55,1",
  "BTTShortcutApp": "com.apple.finder",
  "BTTShortcutSwitchToAppFirst": 1
}

Example (send to active/frontmost app):

{
  "BTTPredefinedActionType": 128,
  "BTTShortcutToSend": "55,1",
  "BTTShortcutApp": "active app",
  "BTTShortcutAppUnderCursor": "active app"
}

Function Keys (F1-F24)​

Simulates pressing function keys.

Parameters vary by key:

  • BTTPredefinedActionType:
    • F1: 33
    • F2: 34
    • F3: 35
    • F4: 36
    • F5: 37
    • F6: 38
    • F7: 39
    • F8: 40
    • F9: 41
    • F10: 42
    • F11: 43
    • F12: 44
    • F13: 130
    • F14: 131
    • F15: 132
    • F16: 133
    • F17: 134
    • F18: 135
    • F19: 303
    • F20: 304
    • F21: 305
    • F22: 306
    • F23: 307
    • F24: 308

Example:

{
  "BTTPredefinedActionType": 43
}

Modifier Key Actions​

Simulates pressing and releasing modifier keys.

Parameters vary by modifier:

  • BTTPredefinedActionType:
    • Shift Down: 178
    • Shift Up: 179
    • Fn Down: 180
    • Fn Up: 181
    • Control Down: 182
    • Control Up: 183
    • Option Down: 184
    • Option Up: 185
    • Command Down: 186
    • Command Up: 187
    • Right Shift Down: 437
    • Right Shift Up: 438
    • Right Control Down: 439
    • Right Control Up: 440
    • Right Option Down: 441
    • Right Option Up: 442
    • Right Command Down: 443
    • Right Command Up: 444

Example:

{
  "BTTPredefinedActionType": 186
}

ESC Key​

Simulates pressing the Escape key.

Parameters:

  • BTTPredefinedActionType: 189

Example:

{
  "BTTPredefinedActionType": 189
}

Toggle Caps Lock​

Toggles the Caps Lock state on/off.

Parameters:

  • BTTPredefinedActionType: 194

Example:

{
  "BTTPredefinedActionType": 194
}

Page Navigation Keys​

Simulates page navigation keys.

Parameters:

  • BTTPredefinedActionType:
    • Page Up: 60
    • Page Down: 61
    • Home: 62
    • End: 63
    • Forward Delete: 64

Example:

{
  "BTTPredefinedActionType": 60
}

Arrow Keys​

Simulates arrow key presses.

Parameters:

  • BTTPredefinedActionType:
    • Page Forward: 51
    • Page Backward: 52

Example:

{
  "BTTPredefinedActionType": 51
}

Remap Key​

Remaps one key to another.

Parameters:

  • BTTPredefinedActionType: 483
  • BTTActionKeyRemapKeyboard: Keyboard identifier
  • BTTActionKeyRemapFromKey: Key to remap from
  • BTTActionKeyRemapToKey: Key to remap to

Example:

{
  "BTTPredefinedActionType": 483,
  "BTTActionKeyRemapKeyboard": "all",
  "BTTActionKeyRemapFromKey": 50,
  "BTTActionKeyRemapToKey": 51
}

Reset All Key Remappings​

Resets all low-level keyboard key remappings to their defaults.

Parameters:

  • BTTPredefinedActionType: 482

Example:

{
  "BTTPredefinedActionType": 482
}

Act as Hyper Key​

Makes the trigger key act as a Hyper Key (simultaneous Ctrl+Shift+Opt+Cmd).

Parameters:

  • BTTPredefinedActionType: 293
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionHyperkeyExcludeShift: boolean - Exclude Shift from the Hyper Key combo (only Ctrl+Opt+Cmd)

Example:

{
  "BTTPredefinedActionType": 293,
  "BTTAdditionalActionData": {
    "BTTActionHyperkeyExcludeShift": false
  }
}

Reset Current Key Sequence​

Resets / stops the currently active key sequence recognition.

Parameters:

  • BTTPredefinedActionType: 422

Example:

{
  "BTTPredefinedActionType": 422
}

Press Context Menu Key​

Simulates pressing the context menu key to show the context menu for the current selection.

Parameters:

  • BTTPredefinedActionType: 532

Example:

{
  "BTTPredefinedActionType": 532
}

Window Management Actions​

Maximize Window​

Maximizes the current window to full screen (not fullscreen mode).

Parameters:

  • BTTPredefinedActionType: 21

Example:

{
  "BTTPredefinedActionType": 21
}

Maximize Window Left​

Maximizes window to the left half of the screen.

Parameters:

  • BTTPredefinedActionType: 19

Example:

{
  "BTTPredefinedActionType": 19
}

Maximize Window Right​

Maximizes window to the right half of the screen.

Parameters:

  • BTTPredefinedActionType: 20

Example:

{
  "BTTPredefinedActionType": 20
}

Resize Window to Quarters​

Resizes window to specific quarter of the screen.

Parameters:

  • BTTPredefinedActionType:
    • Top Left Quarter: 90
    • Top Right Quarter: 92
    • Bottom Left Quarter: 91
    • Bottom Right Quarter: 93

Example:

{
  "BTTPredefinedActionType": 90
}

Resize Window to Thirds​

Resizes window to specific third of the screen.

Parameters:

  • BTTPredefinedActionType:
    • Left Third: 108
    • Middle Third: 109
    • Right Third: 110
    • Left Two Thirds: 174
    • Right Two Thirds: 175

Example:

{
  "BTTPredefinedActionType": 108
}

Resize Window to Halves​

Resizes window to top or bottom half of the screen.

Parameters:

  • BTTPredefinedActionType:
    • Top Half: 96
    • Bottom Half: 95

Example:

{
  "BTTPredefinedActionType": 96
}

Center Window​

Centers the current window on screen.

Parameters:

  • BTTPredefinedActionType: 97

Example:

{
  "BTTPredefinedActionType": 97
}

Center Window on Next Monitor​

Centers the window on the next monitor.

Parameters:

  • BTTPredefinedActionType: 98

Example:

{
  "BTTPredefinedActionType": 98
}

Move Window to Next Monitor​

Moves the current window to the next monitor.

Parameters:

  • BTTPredefinedActionType: 47

Example:

{
  "BTTPredefinedActionType": 47
}

Maximize Window on Next Monitor​

Maximizes the window on the next monitor.

Parameters:

  • BTTPredefinedActionType: 48

Example:

{
  "BTTPredefinedActionType": 48
}

Restore Old Window Size​

Restores window to its previous size before maximizing.

Parameters:

  • BTTPredefinedActionType: 84

Example:

{
  "BTTPredefinedActionType": 84
}

Close Window Under Cursor​

Closes the window under the mouse cursor.

Parameters:

  • BTTPredefinedActionType: 102

Example:

{
  "BTTPredefinedActionType": 102
}

Minimize Window Under Cursor​

Minimizes the window under the mouse cursor.

Parameters:

  • BTTPredefinedActionType: 106

Example:

{
  "BTTPredefinedActionType": 106
}

Zoom Window Under Cursor​

Zooms (green button) the window under cursor.

Parameters:

  • BTTPredefinedActionType: 107

Example:

{
  "BTTPredefinedActionType": 107
}

Bring Window Under Cursor to Front​

Brings the window under the cursor to the front.

Parameters:

  • BTTPredefinedActionType: 204

Example:

{
  "BTTPredefinedActionType": 204
}

Move Window Left/Right​

Moves window by a small amount left or right.

Parameters:

  • BTTPredefinedActionType:
    • Move Left: 17
    • Move Right: 18

Example:

{
  "BTTPredefinedActionType": 17
}

Start/Stop Moving Windows​

Enables window moving mode with modifier keys.

Parameters:

  • BTTPredefinedActionType:
    • Start Moving: 69
    • Stop Moving: 70
    • Toggle Moving: 74

Example:

{
  "BTTPredefinedActionType": 69
}

Start/Stop Resizing Windows​

Enables window resizing mode with modifier keys.

Parameters:

  • BTTPredefinedActionType:
    • Start Resizing: 71
    • Stop Resizing: 72
    • Toggle Resizing: 73

Example:

{
  "BTTPredefinedActionType": 71
}

Custom Move/Resize​

Moves and resizes window with custom parameters.

Parameters:

  • BTTPredefinedActionType: 251
  • BTTActionMoveResizeConfig: JSON object with configuration (deprecated - use BTTAdditionalActionData)
    • BTTWindowResizeX: X position of window
    • BTTWindowResizeY: Y position of window
    • BTTWindowResizeWidth: Width of window
    • BTTWindowResizeHeight: Height of window
  • BTTActionMoveResizeName: Name/description (optional)
  • BTTAdditionalActionData: JSON object with advanced configuration
    • BTTActionCustomMoveResizeUseRelativeValues: boolean - Use relative positioning from current position
    • BTTActionCustomMoveResizeMaintainAspectRatio: boolean - Keep window aspect ratio when resizing
    • BTTActionCustomMoveResizeX: string - X position (supports variables like @variable_name)
    • BTTActionCustomMoveResizeY: string - Y position (supports variables)
    • BTTActionCustomMoveResizeWidth: string - Width (supports variables)
    • BTTActionCustomMoveResizeHeight: string - Height (supports variables)

Example:

{
  "BTTPredefinedActionType": 251,
  "BTTAdditionalActionData": {
    "BTTActionCustomMoveResizeX": "100",
    "BTTActionCustomMoveResizeY": "100",
    "BTTActionCustomMoveResizeWidth": "800",
    "BTTActionCustomMoveResizeHeight": "600",
    "BTTActionCustomMoveResizeUseRelativeValues": false,
    "BTTActionCustomMoveResizeMaintainAspectRatio": true
  }
}

Move Window to Specific Size and Position​

Moves window to exact coordinates and size.

Parameters:

  • BTTPredefinedActionType: 446
  • BTTGenericActionConfig: "x,y,width,height"

Example:

{
  "BTTPredefinedActionType": 446,
  "BTTGenericActionConfig": "100,100,1024,768"
}

Window Layout Management​

Save and restore window layouts.

Parameters:

  • BTTPredefinedActionType:
    • Save Current Layout: 269
    • Restore Saved Layout: 268
    • Restore Last Saved Layout: 270
    • Save Layout with Name: 269 (with BTTWindowLayoutName)
    • Restore Layout with Name: 513 (with BTTWindowLayoutName)
    • Restore Layout with Name & Launch Apps: 580 (with BTTWindowLayoutName)
  • BTTWindowLayoutName: Layout name (for named layouts)
  • BTTWindowLayout: Layout data (for restore)

Example:

{
  "BTTPredefinedActionType": 269,
  "BTTWindowLayoutName": "Work Layout"
}

Save/Restore Focused Window Size And Position​

Saves or restores the size and position of the currently focused window.

Parameters:

  • BTTPredefinedActionType:
    • Save: 539
    • Restore: 540

Example:

{
  "BTTPredefinedActionType": 539
}

Close Window, If Last Window Quit App​

Closes the current window. If it is the last window of the application, quits the app entirely.

Parameters:

  • BTTPredefinedActionType: 560
  • BTTAdditionalActionData: JSON object with configuration
    • BTTCloseWindowOrQuitAppAskBeforeQuit: boolean - Ask for confirmation before quitting the app

Example:

{
  "BTTPredefinedActionType": 560,
  "BTTAdditionalActionData": {
    "BTTCloseWindowOrQuitAppAskBeforeQuit": true
  }
}

Pin/Unpin Window to Float on Top​

Makes window float above all others or removes float status.

Parameters:

  • BTTPredefinedActionType:
    • Toggle Pin: 337
    • Pin: 402
    • Unpin: 401
    • Remove All Float: 338
  • BTTAdditionalActionData: JSON object with pin configuration
    • BTTActionPinOnTopWindowMode: number - Which window to pin (0=focused window, 1=by window ID, 2=by window index, 3=by window title)
    • BTTActionPinOnTopWindowID: number - Window ID (when mode=1)
    • BTTActionPinOnTopWindowIndex: number - Window index (when mode=2)
    • BTTActionPinOnTopWindowTitle: string - Window title substring (when mode=3)
    • BTTActionPinOnTopWindowBelongsToApp: string - Bundle ID of the app the window belongs to
    • BTTActionPinOnTopMode: number - Titlebar style/mode
    • BTTActionPinOnTopMargin: number - Margin around the pinned window
    • BTTActionPinOnTopBackground: string - Background color (RGBA string)
    • BTTActionPinOnTopOpacity: number - Window opacity (0-1)
    • BTTActionPinOnTopOnlyChangeFocusOnClick: boolean - Only change focus when clicking on the window

Example:

{
  "BTTPredefinedActionType": 337,
  "BTTAdditionalActionData": {
    "BTTActionPinOnTopWindowMode": 0,
    "BTTActionPinOnTopOpacity": 0.9,
    "BTTActionPinOnTopOnlyChangeFocusOnClick": true
  }
}

Window Switcher​

Shows a window switcher for the current app or all apps.

Parameters:

  • BTTPredefinedActionType:
    • Current App: 99
    • All Apps: 100
    • Backwards: 378
    • Activate Hovered: 476
  • BTTAdditionalActionData: JSON object with window switcher configuration
    • BTTWindowSwitcherShowPopover: number - Popover display mode (0=screenshot+shortcuts, 1=screenshot only, 2=shortcuts only, 3=no popover, 4=preview of actual window, 5=preview+shortcuts)
    • BTTWindowSwitcherShowThumbnail: number - Thumbnail mode (0=app icon, 1=window thumbnail)
    • BTTWindowSwitcherDisableMouseHover: boolean - Disable selection by mouse hover
    • BTTWindowSwitcherSelectNextOnRepeat: boolean - On repeated trigger, select next window in list
    • BTTWindowSwitcherTriggerOnRelease: boolean - Activate selected after releasing modifier keys (requires SelectNextOnRepeat)
    • BTTWindowSwitcherAppearance: number - Appearance (0=automatic, 1=light, 2=dark)
    • BTTWindowSwitcherFontSize: number - Font size in points (default: 12)
    • BTTWindowSwitcherItemHeight: number - Item height in pixels
    • BTTWindowSwitcherWidth: number - Width in pixels (default: 600)
    • BTTWindowSwitcherHeight: number - Height in pixels (default: 600)
    • BTTWindowSwitcherMousePos: number - Position mode (0=mouse centered left, 1=mouse left to first item, 2=mouse left to second item, 3=centered on screen with mouse, 4=centered on screen with focused window, 5=custom position)
    • BTTWindowSwitcherSort: number - Sort order (0=last used grouped by desktop, 2=alphabetically app+window name, 3=alphabetically app+window name, 4=last used all desktops mixed)
    • BTTWindowSwitcherInitialFocus: number - Initial focus (0=search field, 1=window list)
    • BTTWindowSwitcherFocus: number - Selected item (0=currently active window, 1=second window in list)
    • BTTWindowSwitcherExcludeSpecific: boolean - Enable exclude specific apps/windows
    • BTTWindowSwitcherExclude: string - Exclusion filter text
    • BTTWindowSwitcherExcludeWindowsFromOtherSpaces: boolean - Exclude windows from other spaces
    • BTTWindowSwitcherExcludeHiddenAndMinimizedWindows: boolean - Exclude hidden and minimized windows
    • BTTWindowSwitcherExcludeAllButHiddenAndMinimizedWindows: boolean - Show only hidden and minimized windows
    • BTTWindowSwitcherExcludeVisibleWindows: boolean - Exclude visible windows
    • BTTWindowSwitcherOverrideDefaultShortcuts: boolean - Override default keyboard shortcuts
    • BTTWindowSwitcherAction1 through BTTWindowSwitcherAction15: number - Custom keyboard shortcut action bindings

Example:

{
  "BTTPredefinedActionType": 99,
  "BTTAdditionalActionData": {
    "BTTWindowSwitcherWidth": 800,
    "BTTWindowSwitcherHeight": 600,
    "BTTWindowSwitcherAppearance": 2,
    "BTTWindowSwitcherSort": 0,
    "BTTWindowSwitcherSelectNextOnRepeat": true,
    "BTTWindowSwitcherTriggerOnRelease": true,
    "BTTWindowSwitcherShowPopover": 4,
    "BTTWindowSwitcherInitialFocus": 1
  }
}

Arrange Windows Side by Side​

Arranges multiple windows side by side.

Parameters:

  • BTTPredefinedActionType:
    • Two Windows: 317
    • Two Windows (Last Used Right): 318
    • Three Windows: 319
    • Three Windows (Last Used Right): 320
    • Four Windows: 322
    • Four Windows (Last Used Right): 321

Example:

{
  "BTTPredefinedActionType": 317
}

System Actions​

Sleep Display​

Puts the display to sleep.

Parameters:

  • BTTPredefinedActionType: 13

Example:

{
  "BTTPredefinedActionType": 13
}

Sleep Computer​

Puts the computer to sleep.

Parameters:

  • BTTPredefinedActionType: 14

Example:

{
  "BTTPredefinedActionType": 14
}

Logout​

Logs out the current user.

Parameters:

  • BTTPredefinedActionType: 15

Example:

{
  "BTTPredefinedActionType": 15
}

Lock Screen​

Locks the screen.

Parameters:

  • BTTPredefinedActionType: 158

Example:

{
  "BTTPredefinedActionType": 158
}

Unlock Screen​

Unlocks the screen (requires password to be set).

Parameters:

  • BTTPredefinedActionType: 159
  • BTTGenericActionConfig: Password (stored securely)

Example:

{
  "BTTPredefinedActionType": 159,
  "BTTGenericActionConfig": "encrypted_password_data"
}

Start Screen Saver​

Starts the configured screen saver.

Parameters:

  • BTTPredefinedActionType: 202

Example:

{
  "BTTPredefinedActionType": 202
}

Empty Trash​

Empties the trash.

Parameters:

  • BTTPredefinedActionType: 156

Example:

{
  "BTTPredefinedActionType": 156
}

Toggle Do Not Disturb​

Toggles Do Not Disturb mode on/off.

Parameters:

  • BTTPredefinedActionType: 200

Example:

{
  "BTTPredefinedActionType": 200
}

Toggle Dark Mode​

Toggles between light and dark mode.

Parameters:

  • BTTPredefinedActionType: 197

Example:

{
  "BTTPredefinedActionType": 197
}

Toggle Night Shift​

Toggles Night Shift on/off.

Parameters:

  • BTTPredefinedActionType: 201

Example:

{
  "BTTPredefinedActionType": 201
}

Toggle True Tone​

Toggles True Tone display on/off.

Parameters:

  • BTTPredefinedActionType: 257

Example:

{
  "BTTPredefinedActionType": 257
}

Show Desktop​

Shows the desktop by hiding all windows.

Parameters:

  • BTTPredefinedActionType: 45

Example:

{
  "BTTPredefinedActionType": 45
}

Hide All Windows​

Hides all windows of all applications.

Parameters:

  • BTTPredefinedActionType: 50

Example:

{
  "BTTPredefinedActionType": 50
}

Hide All But Active Window​

Hides all windows except the currently active one.

Parameters:

  • BTTPredefinedActionType: 53

Example:

{
  "BTTPredefinedActionType": 53
}

Show All Windows​

Shows all hidden windows.

Parameters:

  • BTTPredefinedActionType: 488

Example:

{
  "BTTPredefinedActionType": 488
}

Show/Hide Hidden Files​

Toggles visibility of hidden files in Finder.

Parameters:

  • BTTPredefinedActionType: 16

Example:

{
  "BTTPredefinedActionType": 16
}

Notification Center​

Shows the Notification Center.

Parameters:

  • BTTPredefinedActionType: 122

Example:

{
  "BTTPredefinedActionType": 122
}

Control Center​

Shows the Control Center.

Parameters:

  • BTTPredefinedActionType: 290

Example:

{
  "BTTPredefinedActionType": 290
}

Close All Notifications​

Closes all visible notifications.

Parameters:

  • BTTPredefinedActionType: 289

Example:

{
  "BTTPredefinedActionType": 289
}

Show Character Viewer​

Shows the macOS Character Viewer.

Parameters:

  • BTTPredefinedActionType: 167

Example:

{
  "BTTPredefinedActionType": 167
}

Start Siri​

Activates Siri.

Parameters:

  • BTTPredefinedActionType: 173

Example:

{
  "BTTPredefinedActionType": 173
}

Eject​

Ejects removable media.

Parameters:

  • BTTPredefinedActionType: 30

Example:

{
  "BTTPredefinedActionType": 30
}

Refresh Status Bar Items​

Refreshes all status bar items.

Parameters:

  • BTTPredefinedActionType: 302

Example:

{
  "BTTPredefinedActionType": 302
}

Search Selected Text With Google​

Searches for the currently selected text using Google.

Parameters:

  • BTTPredefinedActionType: 58

Example:

{
  "BTTPredefinedActionType": 58
}

Switch to Login Screen​

Switches to the macOS login screen without logging out.

Parameters:

  • BTTPredefinedActionType: 9

Example:

{
  "BTTPredefinedActionType": 9
}

Application Control​

Launch Application​

Launches a specific application.

Parameters:

  • BTTPredefinedActionType: 49
  • BTTLaunchPath: Path to application or bundle identifier

Example:

{
  "BTTPredefinedActionType": 49,
  "BTTLaunchPath": "/Applications/Safari.app"
}

Show/Hide Specific Application​

Shows or hides a specific application.

Parameters:

  • BTTPredefinedActionType: 177
  • BTTAppToShowOrHide: Bundle identifier or path
  • BTTShowHideAppConfig: Configuration options (optional)
  • BTTGenericActionConfig2: JSON object with behavior configuration (optional)
    • Additional show/hide behavior settings

Example:

{
  "BTTPredefinedActionType": 177,
  "BTTAppToShowOrHide": "com.apple.finder",
  "BTTGenericActionConfig2": {
    "showIfHidden": true,
    "hideIfVisible": true
  }
}

Quit Specific Application​

Quits a specific application. Supports standard quit and force quit.

Parameters:

  • BTTPredefinedActionType: 592
  • BTTAppToQuit: Bundle identifier or path of the app to quit
  • BTTQuitAppConfig: JSON string with quit configuration (optional)
    • BTTQuitAppForceQuit: boolean - if true, force quits the app without allowing it to save changes

Example:

{
  "BTTPredefinedActionType": 592,
  "BTTAppToQuit": "com.apple.Safari"
}

Example with force quit:

{
  "BTTPredefinedActionType": 592,
  "BTTAppToQuit": "com.apple.Safari",
  "BTTQuitAppConfig": "{\"BTTQuitAppForceQuit\":true}"
}

Quit App Under Cursor​

Quits the application that owns the window under cursor.

Parameters:

  • BTTPredefinedActionType: 247

Example:

{
  "BTTPredefinedActionType": 247
}

Hide App Under Cursor​

Hides the application under cursor.

Parameters:

  • BTTPredefinedActionType: 294

Example:

{
  "BTTPredefinedActionType": 294
}

Application Switcher​

Shows the application switcher.

Parameters:

  • BTTPredefinedActionType: 46
  • BTTPredefinedActionType: 142 (Backward)

Example:

{
  "BTTPredefinedActionType": 46
}

Activate Previous App​

Switches to the previously active application.

Parameters:

  • BTTPredefinedActionType: 367

Example:

{
  "BTTPredefinedActionType": 367
}

Activate Previous Window​

Activates the previous window.

Parameters:

  • BTTPredefinedActionType: 383
  • BTTPredefinedActionType: 491 (Excluding Minimized)

Example:

{
  "BTTPredefinedActionType": 383
}

Save Active Window​

Saves reference to currently active window.

Parameters:

  • BTTPredefinedActionType: 368

Example:

{
  "BTTPredefinedActionType": 368
}

Go Back to Saved Active Window​

Returns to previously saved active window.

Parameters:

  • BTTPredefinedActionType: 369

Example:

{
  "BTTPredefinedActionType": 369
}

Activate Specific Window​

Activates a window by title or other criteria.

Parameters:

  • BTTPredefinedActionType: 364
  • BTTGenericActionConfig: Window title or identifier
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionActivateSpecificWindowIndex: number - Activate window by index (0-based)
    • BTTActionActivateSpecificWindowOnlyFullScreen: boolean - Only target fullscreen windows

Example:

{
  "BTTPredefinedActionType": 364,
  "BTTGenericActionConfig": "Document.txt"
}

Expose And Sort​

Shows Expose and sorts windows automatically.

Parameters:

  • BTTPredefinedActionType: 103

Example:

{
  "BTTPredefinedActionType": 103
}

Show Menu Bar in Context Menu​

Shows the application's menu bar as a context menu at the current mouse position.

Parameters:

  • BTTPredefinedActionType: 125

Example:

{
  "BTTPredefinedActionType": 125
}

Show Shortcuts in Context Menu​

Shows macOS Shortcuts app shortcuts in a context menu.

Parameters:

  • BTTPredefinedActionType: 298

Example:

{
  "BTTPredefinedActionType": 298
}

Activate Hovered App in Dock​

Activates the application whose Dock icon is currently hovered.

Parameters:

  • BTTPredefinedActionType: 150

Example:

{
  "BTTPredefinedActionType": 150
}

Open Finder​

Opens a new Finder window.

Parameters:

  • BTTPredefinedActionType: 10

Example:

{
  "BTTPredefinedActionType": 10
}

Create New File in Finder​

Creates a new file in the current Finder location.

Parameters:

  • BTTPredefinedActionType: 85

Example:

{
  "BTTPredefinedActionType": 85
}

Open Finder Selection with Specific App​

Opens selected files in Finder with a specific application.

Parameters:

  • BTTPredefinedActionType: 157
  • BTTLaunchPath: Path to application

Example:

{
  "BTTPredefinedActionType": 157,
  "BTTLaunchPath": "/Applications/TextEdit.app"
}

Open Selected Folder with App​

Opens selected folder with specific app.

Parameters:

  • BTTPredefinedActionType: 176
  • BTTLaunchPath: Path to application

Example:

{
  "BTTPredefinedActionType": 176,
  "BTTLaunchPath": "/Applications/Visual Studio Code.app"
}

Media Controls​

Play/Pause​

Toggles media playback.

Parameters:

  • BTTPredefinedActionType: 23

Example:

{
  "BTTPredefinedActionType": 23
}

Next Track​

Skips to the next track.

Parameters:

  • BTTPredefinedActionType: 27

Example:

{
  "BTTPredefinedActionType": 27
}

Previous Track​

Goes to the previous track.

Parameters:

  • BTTPredefinedActionType: 26

Example:

{
  "BTTPredefinedActionType": 26
}

Volume Up​

Increases system volume.

Parameters:

  • BTTPredefinedActionType: 24

Example:

{
  "BTTPredefinedActionType": 24
}

Volume Down​

Decreases system volume.

Parameters:

  • BTTPredefinedActionType: 25

Example:

{
  "BTTPredefinedActionType": 25
}

Volume Up (Small Step)​

Increases volume by a small amount.

Parameters:

  • BTTPredefinedActionType: 198

Example:

{
  "BTTPredefinedActionType": 198
}

Volume Down (Small Step)​

Decreases volume by a small amount.

Parameters:

  • BTTPredefinedActionType: 199

Example:

{
  "BTTPredefinedActionType": 199
}

Mute​

Toggles system mute on/off.

Parameters:

  • BTTPredefinedActionType: 22

Example:

{
  "BTTPredefinedActionType": 22
}

Set Volume​

Sets volume to specific level.

Parameters:

  • BTTPredefinedActionType: 373
  • BTTGenericActionConfig: Volume level (0-100)

Example:

{
  "BTTPredefinedActionType": 373,
  "BTTGenericActionConfig": "50"
}

Set Audio Output Device​

Changes the system audio output device.

Parameters:

  • BTTPredefinedActionType: 583
  • BTTAdditionalActionData: JSON object with audio device configuration
    • BTTAudioDeviceName: string - Audio device name
    • BTTAudioDeviceUID: string - Audio device unique identifier

Example:

{
  "BTTPredefinedActionType": 583,
  "BTTAdditionalActionData": {
    "BTTAudioDeviceName": "MacBook Pro Speakers",
    "BTTAudioDeviceUID": "BuiltInSpeakerDevice"
  }
}

Set Audio Input Device​

Changes the system audio input device.

Parameters:

  • BTTPredefinedActionType: 584
  • BTTAdditionalActionData: JSON object with audio device configuration
    • BTTAudioDeviceName: string - Audio device name
    • BTTAudioDeviceUID: string - Audio device unique identifier

Example:

{
  "BTTPredefinedActionType": 584,
  "BTTAdditionalActionData": {
    "BTTAudioDeviceName": "MacBook Pro Microphone",
    "BTTAudioDeviceUID": "BuiltInMicrophoneDevice"
  }
}

Play Sound File​

Plays a sound file.

Parameters:

  • BTTPredefinedActionType: 582
  • BTTGenericActionConfig: Path to sound file
  • BTTAdditionalActionData: JSON object with configuration
    • BTTPlaySoundCustomPath: string - Custom path to sound file

Example:

{
  "BTTPredefinedActionType": 582,
  "BTTGenericActionConfig": "/System/Library/Sounds/Glass.aiff"
}

Display & Brightness​

Brightness Up​

Increases display brightness.

Parameters:

  • BTTPredefinedActionType: 28

Example:

{
  "BTTPredefinedActionType": 28
}

Brightness Down​

Decreases display brightness.

Parameters:

  • BTTPredefinedActionType: 29

Example:

{
  "BTTPredefinedActionType": 29
}

Brightness Up (Small Step)​

Increases brightness by a small amount.

Parameters:

  • BTTPredefinedActionType: 259

Example:

{
  "BTTPredefinedActionType": 259
}

Brightness Down (Small Step)​

Decreases brightness by a small amount.

Parameters:

  • BTTPredefinedActionType: 260

Example:

{
  "BTTPredefinedActionType": 260
}

External Monitor Brightness Up​

Increases external monitor brightness.

Parameters:

  • BTTPredefinedActionType: 120

Example:

{
  "BTTPredefinedActionType": 120
}

External Monitor Brightness Down​

Decreases external monitor brightness.

Parameters:

  • BTTPredefinedActionType: 121

Example:

{
  "BTTPredefinedActionType": 121
}

External Brightness Up (Small Step)​

Increases external brightness by small amount.

Parameters:

  • BTTPredefinedActionType: 261

Example:

{
  "BTTPredefinedActionType": 261
}

External Brightness Down (Small Step)​

Decreases external brightness by small amount.

Parameters:

  • BTTPredefinedActionType: 262

Example:

{
  "BTTPredefinedActionType": 262
}

Set Brightness​

Sets display brightness to specific level.

Parameters:

  • BTTPredefinedActionType: 370
  • BTTGenericActionConfig: Brightness level (0-100)

Example:

{
  "BTTPredefinedActionType": 370,
  "BTTGenericActionConfig": "75"
}

Keyboard Illumination Up​

Increases keyboard backlight brightness.

Parameters:

  • BTTPredefinedActionType: 31

Example:

{
  "BTTPredefinedActionType": 31
}

Keyboard Illumination Down​

Decreases keyboard backlight brightness.

Parameters:

  • BTTPredefinedActionType: 32

Example:

{
  "BTTPredefinedActionType": 32
}

Set Keyboard Brightness​

Sets keyboard brightness to specific level.

Parameters:

  • BTTPredefinedActionType: 477
  • BTTGenericActionConfig: Brightness level (0-100)

Example:

{
  "BTTPredefinedActionType": 477,
  "BTTGenericActionConfig": "50"
}

Toggle Mirroring​

Toggles display mirroring on/off.

Parameters:

  • BTTPredefinedActionType: 266

Example:

{
  "BTTPredefinedActionType": 266
}

AirPlay Mirroring​

Opens AirPlay mirroring options.

Parameters:

  • BTTPredefinedActionType: 127

Example:

{
  "BTTPredefinedActionType": 127
}

Toggle Super Brightness​

Toggles super brightness mode for current display.

Parameters:

  • BTTPredefinedActionType: 326
  • BTTAdditionalActionData: JSON object (optional)
    • BTTSuperBrightnessIncrease: number - Extra brightness level (0-100, default: 100)
    • BTTSuperBrightnessBrightness: number - brightness level (default: 4)
    • BTTSuperBrightnessSaturation: float - saturation (default: 0.7)
    • BTTSuperBrightnessContrast: number - contrast (default: 9)
    • BTTSuperBrightnessVideoMode: boolean - video mode (default: false)
    • BTTSuperBrightnessOpacity: float - opacity (default: 0.5)

Example:

{
  "BTTPredefinedActionType": 326,
  "BTTAdditionalActionData": {
    "BTTSuperBrightnessBrightness": 5,
    "BTTSuperBrightnessSaturation": 0.8,
    "BTTSuperBrightnessContrast": 10
  }
}

Enable Super Brightness​

Enables super brightness for current display.

Parameters:

  • BTTPredefinedActionType: 324
  • BTTAdditionalActionData: JSON object (optional)
    • BTTSuperBrightnessIncrease: number - Extra brightness level (0-100, default: 100)
    • BTTSuperBrightnessBrightness: number - brightness level (default: 4)
    • BTTSuperBrightnessSaturation: float - saturation (default: 0.7)
    • BTTSuperBrightnessContrast: number - contrast (default: 9)
    • BTTSuperBrightnessVideoMode: boolean - video mode (default: false)
    • BTTSuperBrightnessOpacity: float - opacity (default: 0.5)

Example:

{
  "BTTPredefinedActionType": 324,
  "BTTAdditionalActionData": {
    "BTTSuperBrightnessBrightness": 5,
    "BTTSuperBrightnessSaturation": 0.8,
    "BTTSuperBrightnessContrast": 10
  }
}

Disable Super Brightness​

Disables super brightness for current display.

Parameters:

  • BTTPredefinedActionType: 325
  • BTTAdditionalActionData: JSON object (optional)
    • BTTSuperBrightnessBrightness: number - brightness level (default: 4)
    • BTTSuperBrightnessSaturation: float - saturation (default: 0.7)
    • BTTSuperBrightnessContrast: number - contrast (default: 9)
    • BTTSuperBrightnessVideoMode: boolean - video mode (default: false)
    • BTTSuperBrightnessOpacity: float - opacity (default: 0.5)

Example:

{
  "BTTPredefinedActionType": 325,
  "BTTAdditionalActionData": {
    "BTTSuperBrightnessBrightness": 5,
    "BTTSuperBrightnessSaturation": 0.8,
    "BTTSuperBrightnessContrast": 10
  }
}

Move All Windows to Mouse Display​

Moves all windows to the display where mouse is.

Parameters:

  • BTTPredefinedActionType: 267

Example:

{
  "BTTPredefinedActionType": 267
}

Rotate Display Clockwise​

Rotates the display 90 degrees clockwise.

Parameters:

  • BTTPredefinedActionType: 314

Example:

{
  "BTTPredefinedActionType": 314
}

Rotate Display Counter-Clockwise​

Rotates the display 90 degrees counter-clockwise.

Parameters:

  • BTTPredefinedActionType: 315

Example:

{
  "BTTPredefinedActionType": 315
}

Spaces & Mission Control​

Mission Control​

Shows Mission Control.

Parameters:

  • BTTPredefinedActionType: 7

Example:

{
  "BTTPredefinedActionType": 7
}

Mission Control & Show Desktop Preview​

Shows Mission Control with desktop preview.

Parameters:

  • BTTPredefinedActionType: 165

Example:

{
  "BTTPredefinedActionType": 165
}

Application Exposé​

Shows all windows of current application.

Parameters:

  • BTTPredefinedActionType: 6

Example:

{
  "BTTPredefinedActionType": 6
}

Switch to Desktop (1-19)​

Switches to a specific desktop/space.

Parameters:

  • BTTPredefinedActionType:
    • Desktop 1: 207
    • Desktop 2: 208
    • Desktop 3: 209
    • Desktop 4: 210
    • Desktop 5: 211
    • Desktop 6: 212
    • Desktop 7: 213
    • Desktop 8: 214
    • Desktop 9: 215
    • Desktop 10-19: 226-235

Example:

{
  "BTTPredefinedActionType": 207
}

Move Window to Desktop (1-19)​

Moves current window to specific desktop.

Parameters:

  • BTTPredefinedActionType:
    • Desktop 1: 216
    • Desktop 2: 217
    • Desktop 3: 218
    • Desktop 4: 219
    • Desktop 5: 220
    • Desktop 6: 222
    • Desktop 7: 223
    • Desktop 8: 224
    • Desktop 9: 225
    • Desktop 10-19: 236-245

Example:

{
  "BTTPredefinedActionType": 216
}

Switch Space Left/Right​

Switches to the space on the left or right.

Parameters:

  • BTTPredefinedActionType:
    • Left: 113
    • Right: 114
    • Left (No Animation): 527
    • Right (No Animation): 528

Example:

{
  "BTTPredefinedActionType": 113
}

Move Window to Left/Right Space​

Moves window to adjacent space.

Parameters:

  • BTTPredefinedActionType:
    • Left Space: 151
    • Right Space: 152

Example:

{
  "BTTPredefinedActionType": 151
}

Add New Space​

Creates a new desktop space.

Parameters:

  • BTTPredefinedActionType: 196

Example:

{
  "BTTPredefinedActionType": 196
}

Launchpad​

Shows Launchpad.

Parameters:

  • BTTPredefinedActionType: 115

Example:

{
  "BTTPredefinedActionType": 115
}

Dashboard​

Shows Dashboard (deprecated in newer macOS).

Parameters:

  • BTTPredefinedActionType: 8

Example:

{
  "BTTPredefinedActionType": 8
}

Navigates to a specific space or fullscreen app using either its index or its unique ID.

Parameters:

  • BTTPredefinedActionType: 550
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionGoToSpaceByIndex: number or string - The space index (supports BTT variables)
    • BTTActionGoToSpaceByID: number or string - The space ID (supports BTT variables)

Example:

{
  "BTTPredefinedActionType": 550,
  "BTTAdditionalActionData": {
    "BTTActionGoToSpaceByIndex": 3
  }
}

Screenshot Actions​

Take Screenshot​

Takes a screenshot with configurable options.

Parameters:

  • BTTPredefinedActionType: 169
  • BTTScreenshotOptions: Screenshot configuration as integer or string
  • BTTScreenshotDateFormat: Date format for filename (optional)

Example:

{
  "BTTPredefinedActionType": 169,
  "BTTScreenshotOptions": "0"
}

Screenshot Window​

Takes a screenshot of a specific window.

Parameters:

  • BTTPredefinedActionType: 170

Example:

{
  "BTTPredefinedActionType": 170
}

Screenshot and Edit​

Takes a screenshot and opens it for editing.

Parameters:

  • BTTPredefinedActionType: 171

Example:

{
  "BTTPredefinedActionType": 171
}

Screenshot to Clipboard​

Takes a screenshot directly to clipboard.

Parameters:

  • BTTPredefinedActionType: 316

Example:

{
  "BTTPredefinedActionType": 316
}

Screenshot to Clipboard (New)​

Enhanced screenshot to clipboard with more options.

Parameters:

  • BTTPredefinedActionType: 500
  • BTTGenericActionConfig: Configuration options

Example:

{
  "BTTPredefinedActionType": 500,
  "BTTGenericActionConfig": "{\"BTTScreenshotType\":1}"
}

Take Screenshot or Video​

Opens screenshot/recording toolbar.

Parameters:

  • BTTPredefinedActionType: 263

Example:

{
  "BTTPredefinedActionType": 263
}

Take Screenshot (Configurable)​

Takes a screenshot with advanced configuration options.

Parameters:

  • BTTPredefinedActionType: 495
  • BTTAdditionalActionData: JSON object with screenshot configuration
    • BTTActionScreenCaptureConfigurableMode: number - Capture mode (0=selection, 1=window, 2=fullscreen)
    • BTTActionScreenCaptureConfigurableShowSelection: boolean - Show selection UI
    • BTTActionScreenCaptureConfigurableRecordVideo: boolean - Record video instead of screenshot
    • BTTActionScreenCaptureConfigurableShowDesktopIcons: boolean - Include desktop icons
    • BTTActionScreenCaptureConfigurableCopyToClipboard: boolean - Copy to clipboard
    • BTTActionScreenCaptureConfigurableOpenWith: string - App bundle ID to open screenshot with
    • BTTActionScreenCaptureConfigurableVariableName: string - Variable name to store file path

Example:

{
  "BTTPredefinedActionType": 495,
  "BTTAdditionalActionData": {
    "BTTActionScreenCaptureConfigurableMode": 0,
    "BTTActionScreenCaptureConfigurableShowSelection": true,
    "BTTActionScreenCaptureConfigurableCopyToClipboard": true,
    "BTTActionScreenCaptureConfigurableVariableName": "screenshot_path"
  }
}

Measure Area on Screen​

Shows tool to measure distances on screen.

Parameters:

  • BTTPredefinedActionType: 501

Example:

{
  "BTTPredefinedActionType": 501
}

Clipboard Actions​

Toggle Clipboard Manager​

Shows/hides the clipboard manager.

Parameters:

  • BTTPredefinedActionType: 203
  • BTTAdditionalActionData: JSON object (optional)
    • BTTActionClipboardManagerAutoSaveName: string - auto-save identifier
    • BTTActionClipboardManagerDontHide: boolean - keep manager visible

Example:

{
  "BTTPredefinedActionType": 203,
  "BTTAdditionalActionData": {
    "BTTActionClipboardManagerAutoSaveName": "work-clipboard",
    "BTTActionClipboardManagerDontHide": true
  }
}

Show Clipboard Manager​

Shows the clipboard manager window.

Parameters:

  • BTTPredefinedActionType: 480
  • BTTAdditionalActionData: JSON object (optional)
    • BTTActionClipboardManagerAutoSaveName: string - auto-save identifier
    • BTTActionClipboardManagerDontHide: boolean - keep manager visible

Example:

{
  "BTTPredefinedActionType": 480,
  "BTTAdditionalActionData": {
    "BTTActionClipboardManagerAutoSaveName": "work-clipboard",
    "BTTActionClipboardManagerDontHide": true
  }
}

Hide Clipboard Manager​

Hides the clipboard manager window.

Parameters:

  • BTTPredefinedActionType: 481

Example:

{
  "BTTPredefinedActionType": 481
}

Save Clipboard Contents​

Temporarily saves current clipboard contents.

Parameters:

  • BTTPredefinedActionType: 508

Example:

{
  "BTTPredefinedActionType": 508
}

Restore Clipboard Contents​

Restores previously saved clipboard contents.

Parameters:

  • BTTPredefinedActionType: 509

Example:

{
  "BTTPredefinedActionType": 509
}

Set Clipboard Contents​

Sets clipboard to specific text or formatted content.

Parameters:

  • BTTPredefinedActionType: 529
  • BTTAdditionalActionData: JSON object with clipboard configuration
    • BTTActionSetClipboardContentsString: string - Plain text to set
    • BTTActionSetClipboardContentsAttributedString: string - Rich text/attributed string
    • BTTActionSetClipboardContentsFormat: number - Content format (0=plain text, 1=rich text)

Example:

{
  "BTTPredefinedActionType": 529,
  "BTTAdditionalActionData": {
    "BTTActionSetClipboardContentsString": "Text to copy",
    "BTTActionSetClipboardContentsFormat": 0
  }
}

Upload Clipboard to Imgur​

Uploads clipboard image to Imgur and copies URL.

Parameters:

  • BTTPredefinedActionType: 297

Example:

{
  "BTTPredefinedActionType": 297
}

Copy Selected Text with JavaScript​

Copies selected text transformed by JavaScript.

Parameters:

  • BTTPredefinedActionType: 287
  • BTTRealJavaScriptString: JavaScript code

Example:

{
  "BTTPredefinedActionType": 287,
  "BTTRealJavaScriptString": "return selectedText.toUpperCase();"
}

Transform Clipboard with JavaScript​

Transforms clipboard contents using a JavaScript transformer function.

Parameters:

  • BTTPredefinedActionType: 448
  • BTTAdditionalActionData: JSON object with configuration
    • BTTClipboardTransformerName: string - Name for the transformer (stored in launchPath)
    • BTTClipboardTransformerJS: string - JavaScript transformer function (receives clipboardContentString, returns transformed string)
    • BTTClipboardTransformerExampleInput: string - Example input for testing
    • BTTClipboardTransformerExampleResult: string - Example result (read-only, for testing)
    • BTTActionPasteFormat: string - Transform output format (e.g., "public.utf8-plain-text", "public.rtf", "public.html")
    • BTTActionPasteInputFormat: string - Transform input format
    • BTTActionCustomTextTransformer: string - Use an existing custom text transformer by name

Example:

{
  "BTTPredefinedActionType": 448,
  "BTTAdditionalActionData": {
    "BTTClipboardTransformerName": "Uppercase",
    "BTTClipboardTransformerJS": "async (clipboardContentString) => {\nreturn clipboardContentString.toUpperCase()\n}",
    "BTTActionPasteFormat": "public.utf8-plain-text"
  }
}

Transform Clipboard with ChatGPT​

Transforms clipboard using ChatGPT.

Parameters:

  • BTTPredefinedActionType: 449
  • BTTChatGPTPrompt: Prompt for transformation (stored in launchPath)
  • BTTAdditionalActionData: JSON object with configuration
    • BTTChatGPTModelSelection: Model to use ("gpt-4o-mini", "custom") - default: "gpt-4o-mini"
    • BTTChatGPTModel: Custom model identifier (when using "custom" selection)
    • BTTChatGPTTransformerSystemPrompt: System prompt for the AI
    • BTTChatGPTTransformerUserPrompt: User prompt template - default: "Make everything uppercase, don't add any comment:"
    • BTTChatGPTTransformerExampleInput: Example input for testing - default: "Some Test Text"
    • BTTChatGPTNumberOfHistoryItems: Number of previous requests to include - default: 0
    • BTTChatGPTTransformerShowMiniHUD: boolean - show mini HUD while waiting - default: true
    • BTTChatGPTTransformerAskWhatToDo: boolean - always ask what to do when executing
    • BTTChatGPTTransformerCustomURL: Custom API endpoint URL
    • BTTChatGPTKeepSelectedText: boolean - keep text selected after transformation - default: true
    • BTTChatGPTAppendSelectedText: boolean - append selected text to user prompt - default: true
    • BTTChatGPTImageFilePath: Path to image file to attach
    • BTTChatGPTImageType: Image source type (0=clipboard, 1=file)
    • BTTChatGPTAppendImage: boolean - attach image to request
    • BTTChatGPTUseStreaming: boolean - stream response instead of waiting - default: false for clipboard
    • BTTChatGPTCopyResponseToClipboard: boolean - copy result to clipboard
    • BTTChatGPTCopyResponseToVariable: boolean - save result to variable
    • BTTChatGPTCopyResponseToVariableName: Variable name to store result
    • BTTActionPasteFormat: Paste format options
    • BTTActionPasteInputFormat: Input format for processing
    • BTTChatGPTAPIKey: OpenAI API key (stored securely)
    • BTTChatGPTTransformerExtraParameters: string - Extra JSON parameters to pass to the API

Example:

{
  "BTTPredefinedActionType": 449,
  "BTTChatGPTPrompt": "Translate this to Spanish",
  "BTTAdditionalActionData": {
    "BTTChatGPTModelSelection": "gpt-4o-mini",
    "BTTChatGPTTransformerSystemPrompt": "You are a professional translator.",
    "BTTChatGPTTransformerUserPrompt": "Translate the following text to Spanish:",
    "BTTChatGPTCopyResponseToClipboard": true,
    "BTTChatGPTUseStreaming": true,
    "BTTChatGPTTransformerShowMiniHUD": true
  }
}

Paste Specific Clipboard Item​

Pastes item from clipboard history.

Parameters:

  • BTTPredefinedActionType: 489
  • BTTActionPasteFirstOrLast: "first" or "last" or index

Example:

{
  "BTTPredefinedActionType": 489,
  "BTTActionPasteFirstOrLast": "first"
}

Delete Items from Clipboard Manager​

Deletes selected items from clipboard history.

Parameters:

  • BTTPredefinedActionType: 487

Example:

{
  "BTTPredefinedActionType": 487
}

Delete Specific Item from Clipboard​

Deletes specific item from clipboard manager.

Parameters:

  • BTTPredefinedActionType: 512
  • BTTGenericActionConfig: Item identifier

Example:

{
  "BTTPredefinedActionType": 512,
  "BTTGenericActionConfig": "0"
}

Paste and Remove Item​

Pastes and removes item from clipboard manager.

Parameters:

  • BTTPredefinedActionType: 484
  • BTTActionPasteAndRemoveGroupName: Group name (optional)
  • BTTActionPasteFirstOrLast: "first" or "last"
  • BTTActionPasteOption: Paste options (optional)
  • BTTActionPasteTransformer: Transformation to apply (optional)

Example:

{
  "BTTPredefinedActionType": 484,
  "BTTActionPasteFirstOrLast": "first"
}

Custom Paste​

Pastes with custom options like plain text.

Parameters:

  • BTTPredefinedActionType: 250
  • BTTActionItemsToPaste: Items to paste
  • BTTActionPasteOptions: Paste options
  • BTTActionPasteTransformer: Transform option
  • BTTActionPasteDeleteAfter: Delete after paste flag

Example:

{
  "BTTPredefinedActionType": 250,
  "BTTActionPasteOptions": "{\"BTTPastePlainText\":true}"
}

Check Clipboard Change​

Checks if clipboard has changed.

Parameters:

  • BTTPredefinedActionType: 328

Example:

{
  "BTTPredefinedActionType": 328
}

Wait for Clipboard Change​

Waits until clipboard content changes.

Parameters:

  • BTTPredefinedActionType: 499
  • BTTGenericActionConfig: Timeout in seconds (deprecated - use BTTAdditionalActionData)
  • BTTAdditionalActionData: JSON object with wait configuration
    • BTTActionWaitForClipboardTimeout: number - Wait timeout in seconds (default: 5)

Example:

{
  "BTTPredefinedActionType": 499,
  "BTTAdditionalActionData": {
    "BTTActionWaitForClipboardTimeout": 10
  }
}

Enable/Disable Clipboard Manager Watcher​

Controls clipboard monitoring.

Parameters:

  • BTTPredefinedActionType:
    • Enable: 434
    • Disable: 433

Example:

{
  "BTTPredefinedActionType": 434
}

Copy to Snippet Group​

Copies to a specific snippet group.

Parameters:

  • BTTPredefinedActionType: 485
  • BTTGenericActionConfig: Group name

Example:

{
  "BTTPredefinedActionType": 485,
  "BTTGenericActionConfig": "Code Snippets"
}

Copy/Paste Text Style​

Copies or pastes text formatting.

Parameters:

  • BTTPredefinedActionType:
    • Copy Style: 496
    • Paste Style: 497

Example:

{
  "BTTPredefinedActionType": 496
}

Change Formatting of Selected Text​

Changes formatting of selected text with extensive customization options.

Parameters:

  • BTTPredefinedActionType: 494
  • BTTAdditionalActionData: JSON object with formatting configuration
    • BTTActionChangeTextFormattingSetFontSize: boolean - Set specific font size
    • BTTActionChangeTextFormattingFontSizeFix: number - Fixed font size to set (when SetFontSize is true)
    • BTTActionChangeTextFormattingChangeFontSize: boolean - Change font size relatively
    • BTTActionChangeTextFormattingFontSizeChange: number - Font size change amount (positive/negative)
    • BTTActionChangeTextFormattingChangeFontColor: boolean - Change font color
    • BTTActionChangeTextFormattingFontColor: string - Font color (hex format, e.g., "#FF0000")
    • BTTActionChangeTextFormattingChangeBackgroundColor: boolean - Change background color
    • BTTActionChangeTextFormattingBackgroundColor: string - Background color (hex format)
    • BTTActionChangeTextFormattingUseTemplateString: boolean - Use template string for advanced formatting
    • BTTActionChangeTextFormattingTemplateString: string - Template string with placeholders
    • BTTActionChangeTextFormattingIgnoreFontSize: boolean - Preserve original font size
    • BTTActionChangeTextFormattingIgnoreFont: boolean - Preserve original font
    • BTTActionChangeTextFormattingIgnoreAlignment: boolean - Preserve original alignment

Example (Set fixed font size):

{
  "BTTPredefinedActionType": 494,
  "BTTAdditionalActionData": {
    "BTTActionChangeTextFormattingSetFontSize": true,
    "BTTActionChangeTextFormattingFontSizeFix": 16
  }
}

Example (Change font size relatively):

{
  "BTTPredefinedActionType": 494,
  "BTTAdditionalActionData": {
    "BTTActionChangeTextFormattingChangeFontSize": true,
    "BTTActionChangeTextFormattingFontSizeChange": 2
  }
}

Example (Change colors):

{
  "BTTPredefinedActionType": 494,
  "BTTAdditionalActionData": {
    "BTTActionChangeTextFormattingChangeFontColor": true,
    "BTTActionChangeTextFormattingFontColor": "#FF0000",
    "BTTActionChangeTextFormattingChangeBackgroundColor": true,
    "BTTActionChangeTextFormattingBackgroundColor": "#FFFF00"
  }
}

Example (Use template string):

{
  "BTTPredefinedActionType": 494,
  "BTTAdditionalActionData": {
    "BTTActionChangeTextFormattingUseTemplateString": true,
    "BTTActionChangeTextFormattingTemplateString": "**{{text}}**",
    "BTTActionChangeTextFormattingIgnoreFont": true
  }
}

Change Formatting of Clipboard Contents​

Changes formatting of clipboard contents with extensive customization options.

Parameters:

  • BTTPredefinedActionType: 495
  • BTTAdditionalActionData: JSON object with formatting configuration
    • BTTActionChangeTextFormattingSetFontSize: boolean - Set specific font size
    • BTTActionChangeTextFormattingFontSizeFix: number - Fixed font size to set (when SetFontSize is true)
    • BTTActionChangeTextFormattingChangeFontSize: boolean - Change font size relatively
    • BTTActionChangeTextFormattingFontSizeChange: number - Font size change amount (positive/negative)
    • BTTActionChangeTextFormattingChangeFontColor: boolean - Change font color
    • BTTActionChangeTextFormattingFontColor: string - Font color (hex format, e.g., "#FF0000")
    • BTTActionChangeTextFormattingChangeBackgroundColor: boolean - Change background color
    • BTTActionChangeTextFormattingBackgroundColor: string - Background color (hex format)
    • BTTActionChangeTextFormattingUseTemplateString: boolean - Use template string for advanced formatting
    • BTTActionChangeTextFormattingTemplateString: string - Template string with placeholders
    • BTTActionChangeTextFormattingIgnoreFontSize: boolean - Preserve original font size
    • BTTActionChangeTextFormattingIgnoreFont: boolean - Preserve original font
    • BTTActionChangeTextFormattingIgnoreAlignment: boolean - Preserve original alignment

Example (Multiple formatting changes):

{
  "BTTPredefinedActionType": 495,
  "BTTAdditionalActionData": {
    "BTTActionChangeTextFormattingSetFontSize": true,
    "BTTActionChangeTextFormattingFontSizeFix": 14,
    "BTTActionChangeTextFormattingChangeFontColor": true,
    "BTTActionChangeTextFormattingFontColor": "#0000FF",
    "BTTActionChangeTextFormattingIgnoreAlignment": true
  }
}

Text & Typing Actions​

Save Selected Text to Variable​

Saves currently selected text to a variable.

Parameters:

  • BTTPredefinedActionType: 256
  • BTTVariableName: Variable name

Example:

{
  "BTTPredefinedActionType": 256,
  "BTTVariableName": "selectedText"
}

Transform Selected Text with JavaScript​

Transforms selected text using JavaScript.

Parameters:

  • BTTPredefinedActionType: 284
  • BTTRealJavaScriptString: JavaScript code

Example:

{
  "BTTPredefinedActionType": 284,
  "BTTRealJavaScriptString": "return selectedText.toLowerCase();"
}

Transform Selected Text with ChatGPT​

Transforms selected text using ChatGPT.

Parameters:

  • BTTPredefinedActionType: 384
  • BTTChatGPTPrompt: Transformation prompt (stored in launchPath)
  • BTTAdditionalActionData: JSON object with configuration - same keys as Transform Clipboard with ChatGPT
    • BTTChatGPTModelSelection: Model to use ("gpt-4o-mini", "custom") - default: "gpt-4o-mini"
    • BTTChatGPTModel: Custom model identifier (when using "custom" selection)
    • BTTChatGPTTransformerSystemPrompt: System prompt for the AI
    • BTTChatGPTTransformerUserPrompt: User prompt template
    • BTTChatGPTTransformerExampleInput: Example input for testing
    • BTTChatGPTNumberOfClipboardItemsToInclude: number - Include clipboard history items
    • BTTChatGPTClipboardItemSeparator: string - Separator for clipboard items
    • BTTChatGPTReplaceSelection: boolean - Replace selected text with result
    • BTTChatGPTInsertAsTyping: boolean - Type out the response instead of pasting
    • BTTChatGPTUsePrimaryLanguageModel: boolean - Use primary language model
    • BTTChatGPTScreenshotOption: number - Screenshot option (0=none, 1=interactive, 2=focused window)
    • BTTChatGPTAddTimeDate: boolean - Include timestamp in prompt
    • BTTChatGPTTokenCountOption: number - Token counting mode
    • BTTChatGPTAddNotchBarContent: boolean - Include notch bar content
    • BTTChatGPTAddMenuBarContent: boolean - Include menu bar content
    • BTTChatGPTAddHistoryModeDescription: boolean - Include history mode description
    • BTTChatGPTOpenAIKey: string - OpenAI API key (stored securely)
    • BTTChatGPTSystemPrompt: string - System prompt (alternative to BTTChatGPTTransformerSystemPrompt)
    • BTTChatGPTUserPrompt: string - User prompt (alternative to BTTChatGPTTransformerUserPrompt)
    • BTTChatGPTModelToUse: string - Model to use (alternative to BTTChatGPTModel)
    • BTTChatGPTNumberOfRecentChatMessages: number - Include recent chat messages
    • BTTChatGPTCustomURL: string - Custom URL (alternative to BTTChatGPTTransformerCustomURL)
    • BTTChatGPTPassPreviousMessages: boolean - Pass previous messages in conversation
    • BTTChatGPTNumberOfHistoryItems: Number of previous requests to include
    • BTTChatGPTTransformerShowMiniHUD: boolean - show mini HUD while waiting
    • BTTChatGPTTransformerAskWhatToDo: boolean - always ask what to do
    • BTTChatGPTTransformerCustomURL: Custom API endpoint URL
    • BTTChatGPTKeepSelectedText: boolean - keep text selected
    • BTTChatGPTAppendSelectedText: boolean - append selected text to prompt
    • BTTChatGPTImageFilePath: Path to image file to attach
    • BTTChatGPTImageType: Image source type (0=clipboard, 1=file)
    • BTTChatGPTAppendImage: boolean - attach image to request
    • BTTChatGPTUseStreaming: boolean - stream response - default: true
    • BTTChatGPTCopyResponseToClipboard: boolean - copy result to clipboard
    • BTTChatGPTCopyResponseToVariable: boolean - save result to variable
    • BTTChatGPTCopyResponseToVariableName: Variable name to store result
    • BTTActionPasteFormat: Paste format options
    • BTTActionPasteInputFormat: Input format for processing
    • BTTChatGPTAPIKey: OpenAI API key (stored securely)
    • BTTChatGPTTransformerExtraParameters: string - Extra JSON parameters to pass to the API (e.g., temperature, max_tokens)

Example:

{
  "BTTPredefinedActionType": 384,
  "BTTChatGPTPrompt": "Fix grammar and spelling",
  "BTTAdditionalActionData": {
    "BTTChatGPTModelSelection": "gpt-4o-mini",
    "BTTChatGPTTransformerSystemPrompt": "You are a professional editor.",
    "BTTChatGPTCopyResponseToClipboard": true,
    "BTTChatGPTUseStreaming": true,
    "BTTChatGPTReplaceSelection": true,
    "BTTChatGPTScreenshotOption": 0
  }
}

ChatGPT Selection to Clipboard & Variable​

Processes selection with ChatGPT, saves to clipboard and variable.

Parameters:

  • BTTPredefinedActionType: 471
  • BTTChatGPTPrompt: Processing prompt (stored in launchPath)
  • BTTVariableName: Variable to save result (deprecated - use BTTChatGPTCopyResponseToVariableName)
  • BTTAdditionalActionData: JSON object with configuration - same keys as other ChatGPT actions
    • BTTChatGPTModelSelection: Model to use ("gpt-4o-mini", "custom")
    • BTTChatGPTModel: Custom model identifier
    • BTTChatGPTTransformerSystemPrompt: System prompt
    • BTTChatGPTTransformerUserPrompt: User prompt template
    • BTTChatGPTTransformerExampleInput: Example input
    • BTTChatGPTNumberOfHistoryItems: History items to include
    • BTTChatGPTTransformerShowMiniHUD: boolean - show mini HUD
    • BTTChatGPTTransformerAskWhatToDo: boolean - ask what to do
    • BTTChatGPTTransformerCustomURL: Custom API URL
    • BTTChatGPTKeepSelectedText: boolean - keep selected
    • BTTChatGPTAppendSelectedText: boolean - append selected text
    • BTTChatGPTImageFilePath: Image file path
    • BTTChatGPTImageType: Image source (0=clipboard, 1=file)
    • BTTChatGPTAppendImage: boolean - attach image
    • BTTChatGPTUseStreaming: boolean - stream response
    • BTTChatGPTCopyResponseToClipboard: boolean - copy to clipboard - default: true
    • BTTChatGPTCopyResponseToVariable: boolean - save to variable - default: true
    • BTTChatGPTCopyResponseToVariableName: Variable name - default: "BTTChatGPTResponse"
    • BTTActionPasteFormat: Paste format
    • BTTActionPasteInputFormat: Input format
    • BTTChatGPTAPIKey: API key (secure)
    • BTTChatGPTTransformerExtraParameters: string - Extra JSON parameters to pass to the API

Example:

{
  "BTTPredefinedActionType": 471,
  "BTTChatGPTPrompt": "Summarize this text",
  "BTTAdditionalActionData": {
    "BTTChatGPTModelSelection": "gpt-4o-mini",
    "BTTChatGPTCopyResponseToClipboard": true,
    "BTTChatGPTCopyResponseToVariable": true,
    "BTTChatGPTCopyResponseToVariableName": "summary",
    "BTTChatGPTUseStreaming": true
  }
}

Reset ChatGPT Conversation​

Resets the current ChatGPT conversation context.

Parameters:

  • BTTPredefinedActionType: 385

Example:

{
  "BTTPredefinedActionType": 385
}

Cancel ChatGPT Request​

Cancels ongoing ChatGPT request.

Parameters:

  • BTTPredefinedActionType: 470

Example:

{
  "BTTPredefinedActionType": 470
}

OCR Area on Screen​

Performs OCR on selected screen area.

Parameters:

  • BTTPredefinedActionType: 498
  • BTTOCRLanguages: Language codes (optional)

Example:

{
  "BTTPredefinedActionType": 498,
  "BTTOCRLanguages": "en,de"
}

Find Text on Screen​

Searches for text on screen and clicks it.

Parameters:

  • BTTPredefinedActionType: 426
  • BTTGenericActionConfig: Text to find (deprecated - use BTTAdditionalActionData)
  • BTTAdditionalActionData: JSON object with find text configuration
    • BTTActionFindTextAction: number - Action on find (0=nothing, 1=move mouse, 2=click, 3=double click)
    • BTTActionFindTextScreenArea: string - Screen area to search (coordinates)
    • BTTActionFindTextIsRegex: boolean - Use regular expression matching
    • BTTActionFindTextUseOCR: boolean - Use OCR for text detection
    • BTTActionFindTextString: string - Text to find
    • BTTActionFindTextCaseSensitive: boolean - Case sensitive search
    • BTTActionFindTextScreen: number - Screen to search (0=all, 1=main, 2=mouse screen)
    • BTTActionFindTextEnableVisualFeedback: boolean - Show visual feedback on matches
    • BTTActionFindTextVariableIdentifier: string - Variable name to store result
    • BTTActionFindTextMatchMultiple: boolean - Find all matches
    • BTTActionFindTextWaitFor: number - Wait duration in seconds
    • BTTActionFindTextWaitMode: number - Wait behavior (0=fail if not found, 1=wait up to duration)
    • BTTActionFindTextSelectElementContainingText: boolean - Select container element
    • BTTActionFindTextMaxDistanceElements: number - Max distance between elements
    • BTTActionFindTextHideMouseCursor: boolean - Hide cursor during search
    • BTTFindTextContinueActionExecution: boolean - Continue action execution even if text is not found
    • BTTFindTextRequiredOccurences: number - Required number of occurrences to consider a match

After execution, the following BTT variables are set:

  • last_find_text_on_screen_result: JSON string with recognizedText and boundingRects arrays (empty string if no match)
  • last_find_text_on_screen_success: 1 if text was found, 0 otherwise

Example:

{
  "BTTPredefinedActionType": 426,
  "BTTAdditionalActionData": {
    "BTTActionFindTextString": "Submit",
    "BTTActionFindTextAction": 2,
    "BTTActionFindTextUseOCR": true,
    "BTTActionFindTextEnableVisualFeedback": true,
    "BTTActionFindTextWaitFor": 5
  }
}

Wait for Text on Screen​

Waits until specific text appears on screen.

Parameters:

  • BTTPredefinedActionType: 427
  • BTTGenericActionConfig: Text to wait for
  • BTTGenericActionConfig2: Timeout in seconds

Example:

{
  "BTTPredefinedActionType": 427,
  "BTTGenericActionConfig": "Loading complete",
  "BTTGenericActionConfig2": "10"
}

Force Check Selection Change​

Forces check for text selection change.

Parameters:

  • BTTPredefinedActionType: 493

Example:

{
  "BTTPredefinedActionType": 493
}

Script Execution​

Run AppleScript (Blocking)​

Runs AppleScript and waits for completion.

Parameters:

  • BTTPredefinedActionType: 172
  • BTTAdditionalActionData: Object with:
    • BTTAppleScriptString: AppleScript code
    • BTTScriptType: 0
    • BTTAppleScriptRunInBackground: false
    • BTTAppleScriptUsePath: false (set true to use file path instead)
    • BTTScriptLocation: 0

Example:

{
  "BTTPredefinedActionType": 172,
  "BTTAdditionalActionData": {
    "BTTScriptType": 0,
    "BTTAppleScriptUsePath": false,
    "BTTScriptLocation": 0,
    "BTTAppleScriptRunInBackground": false,
    "BTTAppleScriptString": "tell application \"Finder\" to activate"
  }
}

Run AppleScript (Background)​

Runs AppleScript in background without blocking.

Parameters:

  • BTTPredefinedActionType: 195
  • BTTAdditionalActionData: Object with:
    • BTTAppleScriptString: AppleScript code
    • BTTScriptType: 0
    • BTTAppleScriptRunInBackground: true
    • BTTAppleScriptUsePath: false (set true to use file path instead)
    • BTTScriptLocation: 0

Example:

{
  "BTTPredefinedActionType": 195,
  "BTTAdditionalActionData": {
    "BTTScriptType": 0,
    "BTTAppleScriptUsePath": false,
    "BTTScriptLocation": 0,
    "BTTAppleScriptRunInBackground": true,
    "BTTAppleScriptString": "display notification \"Task Complete\""
  }
}

Run JavaScript (Background)​

Executes JavaScript code in background.

Parameters:

  • BTTPredefinedActionType: 252
  • BTTAdditionalActionData: Object with:
    • BTTAppleScriptString: JavaScript code
    • BTTScriptType: 1
    • BTTAppleScriptRunInBackground: true
    • BTTAppleScriptUsePath: false
    • BTTScriptLocation: 0

Example:

{
  "BTTPredefinedActionType": 252,
  "BTTAdditionalActionData": {
    "BTTScriptType": 1,
    "BTTAppleScriptUsePath": false,
    "BTTScriptLocation": 0,
    "BTTAppleScriptRunInBackground": true,
    "BTTAppleScriptString": "returnToBTT('Hello from JS');"
  }
}

Run JavaScript (Main Thread)​

Executes JavaScript code on main thread.

Parameters:

  • BTTPredefinedActionType: 253
  • BTTAdditionalActionData: Object with:
    • BTTAppleScriptString: JavaScript code
    • BTTScriptType: 1
    • BTTAppleScriptRunInBackground: false
    • BTTAppleScriptUsePath: false
    • BTTScriptLocation: 0

Run Core JavaScript​

Executes Core JavaScript code (BTT's built-in JS engine with async/await support).

Parameters:

  • BTTPredefinedActionType: 281
  • BTTAdditionalActionData: Object with:
    • BTTAppleScriptString: JavaScript code
    • BTTScriptType: 3
    • BTTAppleScriptRunInBackground: true
    • BTTAppleScriptUsePath: false
    • BTTScriptLocation: 0

Example:

{
  "BTTPredefinedActionType": 281,
  "BTTAdditionalActionData": {
    "BTTScriptType": 3,
    "BTTAppleScriptUsePath": false,
    "BTTScriptLocation": 0,
    "BTTAppleScriptRunInBackground": true,
    "BTTAppleScriptString": "let result = await callBTT('trigger_named', {trigger_name: 'MyTrigger'}); returnToBTT(result);"
  }
}

Terminal Command (Blocking)​

Runs terminal command and waits for completion.

Parameters:

  • BTTPredefinedActionType: 246
  • BTTTerminalCommand: Command to execute

Example:

{
  "BTTPredefinedActionType": 246,
  "BTTTerminalCommand": "ls -la"
}

Terminal Command (Background)​

Runs terminal command in background.

Parameters:

  • BTTPredefinedActionType: 137
  • BTTTerminalCommand: Command to execute

Example:

{
  "BTTPredefinedActionType": 137,
  "BTTTerminalCommand": "open /Applications/Safari.app"
}

Shell Script Task​

Runs shell script with more options.

Parameters:

  • BTTPredefinedActionType: 206
  • BTTShellTaskActionScript: Script content
  • BTTShellTaskActionConfig: Shell configuration (optional)

Example:

{
  "BTTPredefinedActionType": 206,
  "BTTShellTaskActionScript": "#!/bin/bash\necho 'Hello World'",
  "BTTShellTaskActionConfig": "/bin/bash"
}

Automator Workflow​

Runs an Automator workflow.

Parameters:

  • BTTPredefinedActionType: 138
  • BTTLaunchPath: Path to workflow

Example:

{
  "BTTPredefinedActionType": 138,
  "BTTLaunchPath": "/path/to/workflow.workflow"
}

Run Apple Shortcut​

Runs a Shortcuts app shortcut.

Parameters:

  • BTTPredefinedActionType: 295
  • BTTAdditionalActionData: JSON object with configuration
    • BTTFormAppleShortcutName: string - Name of the Apple Shortcut to run
    • BTTShortcutInput: string - Input value to pass to the shortcut

Example:

{
  "BTTPredefinedActionType": 295,
  "BTTAdditionalActionData": {
    "BTTFormAppleShortcutName": "My Shortcut",
    "BTTShortcutInput": "Hello"
  }
}

Trigger Apple Shortcut from System Settings​

Triggers system-level shortcut.

Parameters:

  • BTTPredefinedActionType: 519
  • BTTGenericActionConfig: Shortcut identifier

Example:

{
  "BTTPredefinedActionType": 519,
  "BTTGenericActionConfig": "com.apple.shortcuts.12345"
}

BetterTouchTool Control​

Open BTT Preferences​

Opens BetterTouchTool preferences window.

Parameters:

  • BTTPredefinedActionType: 105

Example:

{
  "BTTPredefinedActionType": 105
}

Open Specific BTT Settings​

Opens specific section in BTT preferences.

Parameters:

  • BTTPredefinedActionType: 374
  • BTTGenericActionConfig: Settings section identifier

Example:

{
  "BTTPredefinedActionType": 374,
  "BTTGenericActionConfig": "gestures"
}

Restart BetterTouchTool​

Restarts BetterTouchTool.

Parameters:

  • BTTPredefinedActionType: 55

Example:

{
  "BTTPredefinedActionType": 55
}

Quit BetterTouchTool​

Quits BetterTouchTool.

Parameters:

  • BTTPredefinedActionType: 56

Example:

{
  "BTTPredefinedActionType": 56
}

Toggle BetterTouchTool​

Enables/disables BetterTouchTool.

Parameters:

  • BTTPredefinedActionType: 101

Example:

{
  "BTTPredefinedActionType": 101
}

Disable Gesture Recognition​

Temporarily disables gesture recognition.

Parameters:

  • BTTPredefinedActionType: 144
  • BTTDisableGestureRecognitionFor: Duration (optional)

Example:

{
  "BTTPredefinedActionType": 144
}

Disable Triggers for X Seconds​

Disables all triggers temporarily.

Parameters:

  • BTTPredefinedActionType: 502
  • BTTDisableTriggerForXSeconds: Duration in seconds
  • BTTDisableTriggerForUUID: Specific trigger UUID (optional)

Example:

{
  "BTTPredefinedActionType": 502,
  "BTTDisableTriggerForXSeconds": "10"
}

Switch to Preset​

Switches to a specific preset.

Parameters:

  • BTTPredefinedActionType: 139
  • BTTPresetSwitchConfig: Preset configuration
  • BTTMasterPresetName: Master preset name (optional)

Example:

{
  "BTTPredefinedActionType": 139,
  "BTTPresetSwitchConfig": "Default"
}

Toggle Preset​

Enables/disables a specific preset.

Parameters:

  • BTTPredefinedActionType: 258
  • BTTPresetSwitchConfig: Preset configuration
  • BTTMasterPresetName: Master preset name (optional)

Example:

{
  "BTTPredefinedActionType": 258,
  "BTTPresetSwitchConfig": "Gaming"
}

Trigger Named Trigger​

Executes a named trigger by name.

Parameters:

  • BTTPredefinedActionType: 248
  • BTTNamedTriggerToTrigger: Trigger name

Example:

{
  "BTTPredefinedActionType": 248,
  "BTTNamedTriggerToTrigger": "My Custom Action"
}

Trigger Actions for Item with UUID​

Triggers actions of specific item by UUID.

Parameters:

  • BTTPredefinedActionType: 400
  • BTTGenericActionConfig: Item UUID

Example:

{
  "BTTPredefinedActionType": 400,
  "BTTGenericActionConfig": "12345-67890-abcdef"
}

Show BTT Menu Bar Status Item Menu​

Shows BTT's menu bar menu.

Parameters:

  • BTTPredefinedActionType: 425

Example:

{
  "BTTPredefinedActionType": 425
}

Disable Configured Trigger​

Disables a specific trigger identified by its UUID.

Parameters:

  • BTTPredefinedActionType: 552
  • BTTGenericActionConfig: UUID of the trigger to disable

Example:

{
  "BTTPredefinedActionType": 552,
  "BTTGenericActionConfig": "12345678-1234-1234-1234-123456789012"
}

Enable Configured Trigger​

Enables a previously disabled trigger identified by its UUID.

Parameters:

  • BTTPredefinedActionType: 553
  • BTTGenericActionConfig: UUID of the trigger to enable

Example:

{
  "BTTPredefinedActionType": 553,
  "BTTGenericActionConfig": "12345678-1234-1234-1234-123456789012"
}

Save Menu Bar Status Item Layout / Ordering​

Saves the current arrangement and ordering of menu bar status items so it can be restored later.

Parameters:

  • BTTPredefinedActionType: 543
  • BTTGenericActionConfig: Optional identifier for the saved layout

Example:

{
  "BTTPredefinedActionType": 543,
  "BTTGenericActionConfig": "my_menubar_layout"
}

Restore Saved Menu Bar Status Item Layout / Ordering​

Restores a previously saved menu bar status item arrangement.

Parameters:

  • BTTPredefinedActionType: 544
  • BTTGenericActionConfig: Identifier of the saved layout to restore

Example:

{
  "BTTPredefinedActionType": 544,
  "BTTGenericActionConfig": "my_menubar_layout"
}

Change Menu Bar Status Item Spacing​

Changes the spacing and padding between menu bar status items.

Parameters:

  • BTTPredefinedActionType: 545
  • BTTAdditionalActionData: JSON object with spacing configuration
    • BTTActionChangeMenubarStatusItemSpacingSpacing: number - Spacing between items in pixels
    • BTTActionChangeMenubarStatusItemSpacingPadding: number - Padding around items in pixels
    • BTTActionChangeMenubarStatusItemSpacingAutorestart: boolean - Whether to auto-restart affected apps

Example:

{
  "BTTPredefinedActionType": 545,
  "BTTAdditionalActionData": {
    "BTTActionChangeMenubarStatusItemSpacingSpacing": 8,
    "BTTActionChangeMenubarStatusItemSpacingPadding": 4,
    "BTTActionChangeMenubarStatusItemSpacingAutorestart": false
  }
}

Show Simple JSON Format Menu​

Shows a customizable menu built from a simple JSON format. Can use JavaScript to generate menu content dynamically.

Parameters:

  • BTTPredefinedActionType: 551
  • BTTAdditionalActionData: JSON object with menu configuration
    • BTTActionShowWithSimpleJSONFormatScriptSettings: object - Script settings
    • BTTScriptFunctionToCall: string - JavaScript function to call
    • BTTJavaScriptUseIsolatedContext: boolean - Use isolated JavaScript context

Example:

{
  "BTTPredefinedActionType": 551,
  "BTTAdditionalActionData": {
    "BTTActionShowWithSimpleJSONFormatScriptSettings": {},
    "BTTScriptFunctionToCall": "generateMenu"
  }
}

Touch Bar Actions​

Toggle Touch Bar​

Shows/hides the Touch Bar.

Parameters:

  • BTTPredefinedActionType: 188

Example:

{
  "BTTPredefinedActionType": 188
}

Show Touch Bar​

Shows the Touch Bar.

Parameters:

  • BTTPredefinedActionType: 282

Example:

{
  "BTTPredefinedActionType": 282
}

Hide Touch Bar​

Hides the Touch Bar.

Parameters:

  • BTTPredefinedActionType: 283

Example:

{
  "BTTPredefinedActionType": 283
}

Toggle Global Touch Bar​

Toggles global Touch Bar visibility.

Parameters:

  • BTTPredefinedActionType: 190

Example:

{
  "BTTPredefinedActionType": 190
}

Open Touch Bar Group​

Opens a specific Touch Bar group.

Parameters:

  • BTTPredefinedActionType: 205
  • BTTOpenGroupWithName: Group name

Example:

{
  "BTTPredefinedActionType": 205,
  "BTTOpenGroupWithName": "Media Controls"
}

Close Current Touch Bar Group​

Closes the currently open Touch Bar group.

Parameters:

  • BTTPredefinedActionType: 191

Example:

{
  "BTTPredefinedActionType": 191
}

Notch Bar Actions​

Toggle Notch Bar Hidden​

Shows/hides the Notch Bar.

Parameters:

  • BTTPredefinedActionType: 301

Example:

{
  "BTTPredefinedActionType": 301
}

Show Notch Bar​

Shows the Notch Bar.

Parameters:

  • BTTPredefinedActionType: 312

Example:

{
  "BTTPredefinedActionType": 312
}

Hide Notch Bar​

Hides the Notch Bar.

Parameters:

  • BTTPredefinedActionType: 311

Example:

{
  "BTTPredefinedActionType": 311
}

Disable Notch Bar​

Completely disables the Notch Bar.

Parameters:

  • BTTPredefinedActionType: 299

Example:

{
  "BTTPredefinedActionType": 299
}

Disable Notch Bar for X Seconds​

Temporarily disables Notch Bar.

Parameters:

  • BTTPredefinedActionType: 299
  • BTTGenericActionConfig: Duration in seconds

Example:

{
  "BTTPredefinedActionType": 299,
  "BTTGenericActionConfig": "30"
}

Toggle Notch Bar Mode​

Toggles between Notch Bar modes.

Parameters:

  • BTTPredefinedActionType: 300

Example:

{
  "BTTPredefinedActionType": 300
}

Open Notch Bar Group​

Opens specific Notch Bar group.

Parameters:

  • BTTPredefinedActionType: 310
  • BTTOpenGroupWithName: Group name

Example:

{
  "BTTPredefinedActionType": 310,
  "BTTOpenGroupWithName": "System Info"
}

Close Current Notch Bar Group​

Closes current Notch Bar group.

Parameters:

  • BTTPredefinedActionType: 309

Example:

{
  "BTTPredefinedActionType": 309
}

Stream Deck Actions​

Open Stream Deck Group​

Opens a Stream Deck button group.

Parameters:

  • BTTPredefinedActionType: 341
  • BTTOpenGroupWithName: Group name

Example:

{
  "BTTPredefinedActionType": 341,
  "BTTOpenGroupWithName": "Productivity"
}

Close Current Stream Deck Group​

Closes current Stream Deck group.

Parameters:

  • BTTPredefinedActionType: 340

Example:

{
  "BTTPredefinedActionType": 340
}

Stream Deck Brightness Control​

Controls Stream Deck brightness.

Parameters:

  • BTTPredefinedActionType:
    • Change Brightness: 343
    • Set Brightness: 344
  • BTTGenericActionConfig: Brightness value (0-100 for set, +/- for change)

Example:

{
  "BTTPredefinedActionType": 344,
  "BTTGenericActionConfig": "75"
}

Stream Deck Power Control​

Controls Stream Deck power state.

Parameters:

  • BTTPredefinedActionType:
    • Turn Off: 347
    • Turn On: 348
    • Toggle On/Off: 349

Example:

{
  "BTTPredefinedActionType": 349
}

Show/Hide Stream Deck Emulator​

Controls Stream Deck emulator window.

Parameters:

  • BTTPredefinedActionType: 365
  • BTTAdditionalActionData: JSON object with emulator configuration
    • BTTStreamDeckDeviceSerial: string - Serial number of the Stream Deck device to emulate
    • BTTStreamDeckRows: number - Number of rows in the emulator grid
    • BTTStreamDeckColumns: number - Number of columns in the emulator grid
    • BTTStreamDeckShowTitlebar: boolean - Show window titlebar
    • BTTStreamDeckPaging: boolean - Enable paging
    • BTTStreamDeckFloatOnTop: boolean - Float emulator window on top

Example:

{
  "BTTPredefinedActionType": 365,
  "BTTAdditionalActionData": {
    "BTTStreamDeckRows": 3,
    "BTTStreamDeckColumns": 5,
    "BTTStreamDeckFloatOnTop": true,
    "BTTStreamDeckShowTitlebar": false
  }
}

Activate Stream Deck Touch Screen Group​

Activates touch screen configuration on Stream Deck+.

Parameters:

  • BTTPredefinedActionType: 376
  • BTTGenericActionConfig: Configuration group name

Example:

{
  "BTTPredefinedActionType": 376,
  "BTTGenericActionConfig": "Video Editing"
}

Temporarily Change Stream Deck Item​

Temporarily changes display of Stream Deck button.

Parameters:

  • BTTPredefinedActionType: 377
  • BTTGenericActionConfig: Item UUID
  • BTTGenericActionConfig2: New display configuration

Example:

{
  "BTTPredefinedActionType": 377,
  "BTTGenericActionConfig": "button-uuid-123",
  "BTTGenericActionConfig2": "{\"title\":\"Temp Text\",\"backgroundColor\":\"#FF0000\"}"
}

Floating Menu Actions​

Show Floating Menu​

Shows a specific floating menu.

Parameters:

  • BTTPredefinedActionType: 386
  • BTTAdditionalActionData: JSON object with menu configuration
    • BTTMenuActionMenuID: Menu UUID or identifier (primary way to specify the menu)
    • BTTMenuActionMenuName: Menu name (alternative to UUID, for display/lookup)
    • BTTMenuActionActivateKeyboardFocus: Keyboard focus mode (0 = do NOT steal keyboard focus, 1 = activate window & steal keyboard focus, 2 = steal keyboard focus without activating window)
    • BTTMenuActionHideOnModifierRelease: boolean - hide the menu after releasing all pressed modifier keys
    • BTTMenuActionRestorePosition: boolean - always move & resize to defined position when showing (defaults to true)
    • BTTMenuActionTriggerHoveredOnHide: boolean - trigger hovered item when menu is being hidden
    • BTTMenuActionCloseSubmenuOnHide: boolean - close submenus when menu is being hidden

Example:

{
  "BTTPredefinedActionType": 386,
  "BTTPredefinedActionName": "Show Floating Menu",
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "Move Window to Space",
    "BTTMenuActionActivateKeyboardFocus": 0,
    "BTTMenuActionHideOnModifierRelease": 0,
    "BTTMenuActionRestorePosition": true,
    "BTTMenuActionTriggerHoveredOnHide": 0,
    "BTTMenuActionCloseSubmenuOnHide": 0
  }
}

Hide Floating Menu​

Hides a specific floating menu.

Parameters:

  • BTTPredefinedActionType: 387
  • BTTAdditionalActionData: JSON object with menu configuration
    • BTTMenuActionMenuID: Menu UUID or identifier
    • BTTMenuActionMenuName: Menu name (alternative to UUID)
    • BTTMenuActionTriggerHoveredOnHide: boolean - trigger hovered item when menu is being hidden
    • BTTMenuActionCloseSubmenuOnHide: boolean - close submenus when menu is being hidden

Example:

{
  "BTTPredefinedActionType": 387,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "QuickActions",
    "BTTMenuActionTriggerHoveredOnHide": 0,
    "BTTMenuActionCloseSubmenuOnHide": 0
  }
}

Toggle Floating Menu​

Toggles visibility of floating menu.

Parameters:

  • BTTPredefinedActionType: 388
  • BTTAdditionalActionData: JSON object with menu configuration
    • BTTMenuActionMenuID: Menu UUID or identifier
    • BTTMenuActionMenuName: Menu name (alternative to UUID)
    • BTTMenuActionActivateKeyboardFocus: Keyboard focus mode (0 = don't steal, 1 = activate window & steal, 2 = steal without activating)
    • BTTMenuActionHideOnModifierRelease: boolean - hide after releasing all pressed modifier keys
    • BTTMenuActionRestorePosition: boolean - always move & resize to defined position when showing (defaults to true)
    • BTTMenuActionTriggerHoveredOnHide: boolean - trigger hovered item when menu is being hidden
    • BTTMenuActionCloseSubmenuOnHide: boolean - close submenus when menu is being hidden

Example:

{
  "BTTPredefinedActionType": 388,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "QuickActions",
    "BTTMenuActionActivateKeyboardFocus": 0,
    "BTTMenuActionRestorePosition": true
  }
}

Open Floating Menu Submenu​

Opens a submenu in floating menu. You can specify the target either by item UUID, or by menu name + item name.

Parameters:

  • BTTPredefinedActionType: 472
  • BTTAdditionalActionData: JSON object with submenu configuration
    • BTTMenuActionMenuItemUUID: UUID of the menu item (right-click item in BTT to copy UUID)
    • BTTMenuActionMenuName: Menu name to find the item in
    • BTTMenuActionMenuItemName: Item name within the menu

Example:

{
  "BTTPredefinedActionType": 472,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "MainMenu",
    "BTTMenuActionMenuItemName": "FileSubmenu"
  }
}

Close Floating Menu Submenu​

Closes current floating menu submenu. You can optionally provide the parent menu name or UUID. If no identifier is provided, all open submenus will be closed.

Parameters:

  • BTTPredefinedActionType: 445
  • BTTAdditionalActionData: JSON object (optional)
    • BTTMenuActionMenuID: Parent menu name or UUID containing the submenu

Example:

{
  "BTTPredefinedActionType": 445,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "MainMenu"
  }
}

Floating Menu Execute JavaScript​

Executes JavaScript in a floating menu web view item. Target the item by UUID, or by menu name + item name.

Parameters:

  • BTTPredefinedActionType: 398
  • BTTAdditionalActionData: JSON object with configuration
    • BTTMenuActionMenuItemUUID: UUID of the web view menu item
    • BTTMenuActionMenuName: Menu name (alternative to UUID)
    • BTTMenuActionMenuItemName: Item name within the menu
    • BTTMenuActionMenuItemContentJS: JavaScript code to execute
    • BTTMenuActionMenuItemUserAgent: Custom user agent string (optional)
    • BTTMenuActionActivateKeyboardFocus: Keyboard focus mode (0/1/2)

Example:

{
  "BTTPredefinedActionType": 398,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "MainMenu",
    "BTTMenuActionMenuItemName": "WebViewItem",
    "BTTMenuActionMenuItemContentJS": "document.title = 'Updated';"
  }
}

Floating Menu Load HTML​

Loads HTML or URL into a floating menu web view item. Target the item by UUID, or by menu name + item name.

Parameters:

  • BTTPredefinedActionType: 397
  • BTTAdditionalActionData: JSON object with configuration
    • BTTMenuActionMenuItemUUID: UUID of the web view menu item
    • BTTMenuActionMenuName: Menu name (alternative to UUID)
    • BTTMenuActionMenuItemName: Item name within the menu
    • BTTMenuActionMenuItemContentHTML: HTML content or URL to load
    • BTTMenuActionMenuItemContentJS: JavaScript to execute after loading (optional)
    • BTTMenuActionMenuItemUserAgent: Custom user agent string (optional)
    • BTTMenuActionActivateKeyboardFocus: Keyboard focus mode (0/1/2)
    • BTTMenuActionUpdateDefaults: boolean - persist update to the web view item

Example:

{
  "BTTPredefinedActionType": 397,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuName": "WebMenu",
    "BTTMenuActionMenuItemName": "Browser",
    "BTTMenuActionMenuItemContentHTML": "<html><body>Hello World</body></html>",
    "BTTMenuActionActivateKeyboardFocus": 1
  }
}

Floating Menu Evaluate Scripts​

Re-evaluates all scripts in a floating menu.

Parameters:

  • BTTPredefinedActionType: 389
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 389,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Floating Menu Re-evaluate Position​

Recalculates floating menu position based on its positioning configuration.

Parameters:

  • BTTPredefinedActionType: 390
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 390,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Floating Menu Bring to Mouse Screen​

Moves floating menu to the screen where the mouse cursor is located.

Parameters:

  • BTTPredefinedActionType: 399
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 399,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Trigger Floating Menu Highlighted Item​

Triggers the currently highlighted menu item in a floating menu.

Parameters:

  • BTTPredefinedActionType: 393
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 393,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Trigger Highlighted Item and Hide Menu​

Triggers the currently highlighted item and then hides the menu.

Parameters:

  • BTTPredefinedActionType: 404
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 404,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Floating Menu Hover/Unhover​

Controls hover state of a floating menu item.

Parameters:

  • BTTPredefinedActionType:
    • Hover: 394
    • Unhover: 395
    • Toggle Hover: 396
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 394,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Update Floating Menu Item Properties​

Dynamically updates properties of a floating menu item at runtime. This is configured through the floating menu item property editor in BTT preferences.

Parameters:

  • BTTPredefinedActionType: 447
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 447,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Update Floating Menu Properties​

Dynamically updates properties of a floating menu itself at runtime. This is configured through the floating menu property editor in BTT preferences.

Parameters:

  • BTTPredefinedActionType: 450
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 450,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Reset Floating Menu Item Properties​

Resets dynamically changed item properties back to their defaults. Right-click an item in BTT to copy its UUID. If no UUID is provided, the action applies to the item this action is assigned to.

Parameters:

  • BTTPredefinedActionType: 451
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Item or menu UUID

Example:

{
  "BTTPredefinedActionType": 451,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Run Floating Menu Content Scripts​

Executes content scripts in a floating menu (re-runs shell scripts, AppleScripts, etc. assigned to menu items).

Parameters:

  • BTTPredefinedActionType: 469
  • BTTAdditionalActionData: JSON object
    • BTTMenuActionMenuID: Menu UUID or identifier

Example:

{
  "BTTPredefinedActionType": 469,
  "BTTAdditionalActionData": {
    "BTTMenuActionMenuID": "12345678-1234-1234-1234-123456789012"
  }
}

Toggle Attach / Pin Floating Menu To Active Window​

Attaches or detaches a floating menu to/from the currently active window, so the menu moves with the window.

Parameters:

  • BTTPredefinedActionType: 548
  • BTTAdditionalActionData: JSON object with floating menu configuration

Example:

{
  "BTTPredefinedActionType": 548,
  "BTTAdditionalActionData": {}
}

Control Flow Actions​

Delay (Async / Non-Blocking)​

This action pauses the execution of the current action sequence but allows the BTT process to continue processing other stuff. Usually you'd use this action to add some delays to your action sequences, e.g. when waiting for some UI to react. If you need longer timeouts (e.g. to trigger something after 10 minutes) use the "Trigger Action Sequence After Timeout" action instead.

Parameters:

  • BTTPredefinedActionType: 345
  • BTTDelayNextActionBy: The amount of time to pause the action execution. Provided as number with a dot as decimal separator.

Example:

{
  "BTTPredefinedActionType": 345,
  "BTTDelayNextActionBy": 2.5
}

Delay (Blocking)​

This one freezes the BTT process for the specified amount of time, preventing any action processing during that time. You should only ever use this with small delays.

Parameters:

  • BTTPredefinedActionType: 129
  • BTTDelayNextActionBy: The amount of time to freeze / block the action execution. Provided as number with a dot as decimal separator.

Note: Usually you should use the "Delay (Async / Non-Blocking) action instead. The blocking one is only helpful for very few usecases.

Example:

{
  "BTTPredefinedActionType": 129,
  "BTTDelayNextActionBy": 2.5
}

Start Repeat​

This marks the start of a for loop / repeat. All actions that come between this and the "End / Stop Repeat" action will be repeated.

Parameters:

  • BTTPredefinedActionType: 329
  • BTTGenericActionConfig: The name of the for loop
  • BTTAdditionalActionData: Contains further action configuration object
    • BTTActionForLoopRepeat: Number of times the for loop should repeat (number)
    • BTTActionForLoopRepeatVariable: If the number of repeats is controlled by a BTT variable, you can specify the variable here

Example:

{
  "BTTPredefinedActionType": 329,
  "BTTAdditionalActionData": {
    "BTTActionForLoopRepeat": 99
  },
  "BTTGenericActionConfig": "nameOfTheLoop"
}

End / Stop Repeat​

Marks the end of the repeat / for loop.

Parameters:

  • BTTPredefinedActionType: 332

Example:

{
  "BTTPredefinedActionType": 332
}

Break​

Can only be used between "Start Repeat" and "End/Stop Repeat". Behaves like a standard break e.g. in JavaScript.

Parameters:

  • BTTPredefinedActionType: 332

Example:

{
  "BTTPredefinedActionType": 332
}

Cancel Repeat​

This will cancel the specified repeat loop (if it is running).

Parameters:

  • BTTPredefinedActionType: 424
  • BTTGenericActionConfig: The name of the repeat / loop that shall be canceled.

Example:

{
  "BTTPredefinedActionType": 424,
  "BTTGenericActionConfig": "theLoopIdentifier"
}

IF Condition​

Starts conditional block based on variable.

Parameters:

  • BTTPredefinedActionType: 330
  • BTTIfConditionFormat: Condition format string
  • BTTIfConditionData: Condition data (base64 encoded)

Example:

{
  "BTTPredefinedActionType": 330,
  "BTTIfConditionFormat": "myVar == 'true'",
  "BTTIfConditionData": "base64_encoded_data"
}

IF JavaScript True​

Conditional based on JavaScript evaluation.

Parameters:

  • BTTPredefinedActionType: 431
  • BTTRealJavaScriptString: JavaScript that returns boolean

Example:

{
  "BTTPredefinedActionType": 431,
  "BTTRealJavaScriptString": "return window.innerWidth > 1024;"
}

IF AppleScript True​

Conditional based on AppleScript evaluation.

Parameters:

  • BTTPredefinedActionType: 432
  • BTTInlineAppleScript: AppleScript that returns boolean

Example:

{
  "BTTPredefinedActionType": 432,
  "BTTInlineAppleScript": "tell application \"System Events\" to return (name of first process whose frontmost is true) is \"Safari\""
}

IF Image Visible​

Conditional based on image visibility on screen.

Parameters:

  • BTTPredefinedActionType: 405
  • BTTFindPositionOfImageImage: Base64 encoded image
  • BTTFindPositionOfImageImageDark: Base64 encoded dark mode image (optional)

Example:

{
  "BTTPredefinedActionType": 405,
  "BTTFindPositionOfImageImage": "base64_image_data"
}

IF Text Visible​

Conditional based on text visibility on screen.

Parameters:

  • BTTPredefinedActionType: 428
  • BTTGenericActionConfig: Text to find

Example:

{
  "BTTPredefinedActionType": 428,
  "BTTGenericActionConfig": "Submit Button"
}

ELSE​

Else clause for IF conditions.

Parameters:

  • BTTPredefinedActionType: 333

Example:

{
  "BTTPredefinedActionType": 333
}

END IF​

Ends conditional block.

Parameters:

  • BTTPredefinedActionType: 331

Example:

{
  "BTTPredefinedActionType": 331
}

Execute Action Sequence After Timeout (Cancellable)​

This allows to execute an action sequence after a specific amount of time. While the previously described delay actions are only meant to be used for short delays, this one can also be used for longer delays. Additionally you can specify a name for the timer, which allows you to cancel it if necessary.

Parameters:

  • BTTPredefinedActionType: 351
  • BTTGenericActionConfig: The timeout in seconds as string using a dot as decimal separator
  • BTTGenericActionConfig2: The name of the timer
  • BTTAdditionalActions: An array of actions that shall be executed after the timeout

Example:

{
  "BTTPredefinedActionType": 351,
  "BTTGenericActionConfig2": "timerName",
  "BTTGenericActionConfig": "3.5",
  "BTTAdditionalActions": [
    {
      "BTTTriggerType": 740,
      "BTTPredefinedActionType": 366,
      "BTTTriggerClass": "BTTTriggerTypeCustomActionConfig",
      "BTTAdditionalActions": [
        {
          "BTTTriggerClass": "BTTTriggerTypeCustomActionConfig",
          "BTTPredefinedActionType": 3
        },
        {
          "BTTTriggerClass": "BTTTriggerTypeCustomActionConfig",
          "BTTPredefinedActionType": 3
        }
      ]
    }
  ]
}

Cancel Timed / Delayed Action Sequences​

Cancels the execution of action sequences that has been scheduled via predefined action "Execute Action Sequence After Timeout (Cancellable)".

Parameters:

  • BTTPredefinedActionType: 352
  • BTTGenericActionConfig2: The name of the scheduled action sequence you want to cancel

Example:

{
  "BTTPredefinedActionType": 352,
  "BTTGenericActionConfig2": "theNameOfTheTimer"
}

Ask For Input & Save To Variable​

Shows a floating input field and saves the entered text into a variable.

Parameters:

  • BTTPredefinedActionType: 403
  • BTTAdditionalActionData: Contains the configuration object
    • BTTActionAskForInputPrompt: The input prompt (string)
    • BTTActionAskForInputVariableName: The variable name (string)
    • BTTActionAskForInputVariableType: 0 - String or 1 Number
    • BTTActionAskForInputOnlyHideOnEnterOrEsc: 0: Hide when clicking outside, when hitting esc or when hitting enter. 1: Hide when hitting esc or when hitting enter
    • BTTActionAskForInputUseActivatingWindow: If set to 1 the window will take focus - might be necessary in some situations to receive keyboard input

Example:

{
  "BTTPredefinedActionType": 403,
  "BTTAdditionalActionData": {
    "BTTActionAskForInputVariableName": "address",
    "BTTActionAskForInputPrompt": "Enter your address:"
  }
}

Wait for Keyboard Input​

This will pause the currently executing action sequence until the specified continue or cancel key has been pressed.

Parameters:

  • BTTPredefinedActionType: 486
  • BTTActionWaitForKeyboardInputCancelKeyCode: A keycode that cancels the action sequence when pressed (number)
  • BTTActionWaitForKeyboardInputContinueKeyCode: A keycode that continues the action sequence when pressed (number)
  • BTTActionWaitForKeyboardInputTimeout: Timeout in seconds (number)

Example:

{
  "BTTPredefinedActionType": 486,
  "BTTActionWaitForKeyboardInputCancelKeyCode": 7,
  "BTTActionWaitForKeyboardInputContinueKeyCode": 8,
  "BTTActionWaitForKeyboardInputTimeout": 10
}

Wait for Conditions To Become True​

This will pause the currently executing action sequence until the specified conditions have been met.

Parameters:

  • BTTPredefinedActionType: 417
  • BTTWaitForConditionFormat: The condition to be met (read only)
  • BTTWaitForConditionData: The condition to be met (data, can only be created via BTT UI)
  • BTTGenericActionConfig: An identifier to reference the wait
  • BTTGenericActionConfig2: A JSON string with the properties BTTActionWaitForConditionsInterval and BTTActionWaitForConditionsTimeout

Example:

{
  "BTTPredefinedActionType": 417,
  "BTTWaitForConditionFormat": "fingers_touching_trackpad >= 5",
  "BTTWaitForConditionData": "base64encodedconditiondata",
  "BTTGenericActionConfig": "identifier",
  "BTTGenericActionConfig2": "{\"BTTActionWaitForConditionsInterval\": 2, \"BTTActionWaitForConditionsTimeout\": 10}"
}

Cancel Wait for Conditions To Become True​

This will cancel a wait for conditions action.

Parameters:

  • BTTPredefinedActionType: 418
  • BTTGenericActionConfig: The identifier of the condition wait that you want to cancel

Example:

{
  "BTTPredefinedActionType": 418,
  "BTTGenericActionConfig": "example"
}

Wait for Change Of Focused Window​

This will pause the currently executing action sequence until the focused window changes.

Parameters:

  • BTTPredefinedActionType: 423
  • BTTGenericActionConfig2: A JSON string with the properties BTTActionWaitForFocusChangeInterval and BTTActionWaitForFocusChangeTimeout

Example:

{
  "BTTPredefinedActionType": 423,
  "BTTGenericActionConfig2": "{\"BTTActionWaitForFocusChangeInterval\": 2,\"BTTActionWaitForFocusChangeTimeout\": 10}"
}

Parameters:

  • BTTPredefinedActionType: 334

Example:

{
  "BTTPredefinedActionType": 334
}

Break​

Breaks out of current loop or control structure.

Parameters:

  • BTTPredefinedActionType: 331

Example:

{
  "BTTPredefinedActionType": 331
}

Continue With Next Action​

Continues to next action in sequence.

Parameters:

  • BTTPredefinedActionType: 366

Example:

{
  "BTTPredefinedActionType": 366
}

Stop All Action Sequences​

Stops all running action sequences.

Parameters:

  • BTTPredefinedActionType: 531

Example:

{
  "BTTPredefinedActionType": 531
}

Wait For Conditions​

Waits for specific conditions to become true.

Parameters:

  • BTTPredefinedActionType: 417
  • BTTWaitForConditionFormat: Condition format
  • BTTWaitForConditionData: Condition data (base64)
  • BTTGenericActionConfig2: JSON object with configuration (optional)
    • BTTActionWaitForConditionsInterval: Check interval in seconds
    • BTTActionWaitForConditionsTimeout: Wait timeout in seconds
    • Other BTTActionWaitForConditions* keys for specific conditions

Example:

{
  "BTTPredefinedActionType": 417,
  "BTTWaitForConditionFormat": "variable == 'ready'",
  "BTTWaitForConditionData": "base64_data",
  "BTTGenericActionConfig2": {
    "BTTActionWaitForConditionsInterval": 0.5,
    "BTTActionWaitForConditionsTimeout": 30
  }
}

Cancel Wait For Conditions​

Cancels waiting for conditions.

Parameters:

  • BTTPredefinedActionType: 418

Example:

{
  "BTTPredefinedActionType": 418
}

Wait For App Launch/Terminate​

Waits for app state changes.

Parameters:

  • BTTPredefinedActionType:
    • Launch: 413
    • Terminate: 414
    • Activate: 415
    • Deactivate: 416
  • BTTGenericActionConfig: App bundle identifier

Example:

{
  "BTTPredefinedActionType": 413,
  "BTTGenericActionConfig": "com.apple.Safari"
}

Wait For Image to Become Visible​

Waits for image to appear on screen.

Parameters:

  • BTTPredefinedActionType: 419
  • BTTFindPositionOfImageImage: Base64 encoded image
  • BTTGenericActionConfig2: Timeout in seconds

Example:

{
  "BTTPredefinedActionType": 419,
  "BTTFindPositionOfImageImage": "base64_image_data",
  "BTTGenericActionConfig2": "10"
}

Wait For Focus Change​

Waits for window focus to change.

Parameters:

  • BTTPredefinedActionType: 423
  • BTTGenericActionConfig2: JSON object with configuration
    • BTTActionWaitForFocusChangeInterval: Check interval in seconds (default: 0)
    • BTTActionWaitForFocusChangeTimeout: Wait timeout in seconds (optional)

Example:

{
  "BTTPredefinedActionType": 423,
  "BTTGenericActionConfig2": {
    "BTTActionWaitForFocusChangeInterval": 2,
    "BTTActionWaitForFocusChangeTimeout": 10
  }
}

Wait For Keyboard Input​

Waits for specific keyboard input.

Parameters:

  • BTTPredefinedActionType: 486
  • BTTActionWaitForKeyboardInputContinueKeyCode: Key code to continue (e.g., "36" for Return key)
  • BTTActionWaitForKeyboardInputCancelKeyCode: Key code to cancel (optional)
  • BTTActionWaitForKeyboardInputTimeout: Timeout in seconds (optional)

Example:

{
  "BTTPredefinedActionType": 486,
  "BTTActionWaitForKeyboardInputContinueKeyCode": "36",
  "BTTActionWaitForKeyboardInputCancelKeyCode": "53",
  "BTTActionWaitForKeyboardInputTimeout": 10
}

Trigger Action Sequence After Timeout​

Schedules actions to run after delay.

Parameters:

  • BTTPredefinedActionType: 351
  • BTTGenericActionConfig: Delay in seconds
  • BTTActionImmediatelyContinueWithNext: Continue flag (optional)
  • BTTGenericActionConfig2: Actions to trigger

Example:

{
  "BTTPredefinedActionType": 351,
  "BTTGenericActionConfig": "60",
  "BTTGenericActionConfig2": "{\"actions\":[{\"BTTPredefinedActionType\":371}]}"
}

Cancel Action Sequence After Timeout​

Cancels scheduled action sequence.

Parameters:

  • BTTPredefinedActionType: 352
  • BTTGenericActionConfig: Sequence identifier

Example:

{
  "BTTPredefinedActionType": 352,
  "BTTGenericActionConfig": "scheduled-123"
}

Wait For Other BetterTouchTool Trigger To Fire​

Pauses the action sequence and waits until a specific trigger (identified by UUID) fires. If the trigger doesn't fire within the timeout, the wait is cancelled.

Parameters:

  • BTTPredefinedActionType: 567
  • BTTGenericActionConfig: UUID of the trigger to wait for
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionWaitForTriggerTimeout: number - Timeout in seconds (default: very large value)

Example:

{
  "BTTPredefinedActionType": 567,
  "BTTGenericActionConfig": "12345678-1234-1234-1234-123456789012",
  "BTTAdditionalActionData": {
    "BTTActionWaitForTriggerTimeout": 30
  }
}

Debounce​

Only continues the action sequence if the last execution has been more than X seconds ago. Useful to prevent rapid repeated execution of expensive actions.

Parameters:

  • BTTPredefinedActionType: 579
  • BTTGenericActionConfig: Debounce time in seconds (as string)

Example:

{
  "BTTPredefinedActionType": 579,
  "BTTGenericActionConfig": "2.0"
}

Variable Actions​

Set Variable​

Sets a persistent or temporary variable.

Parameters:

  • BTTPredefinedActionType: 292
  • BTTVariableName: Variable name (string)
  • BTTVariableValue: Value to set (string)
  • BTTVariablePersist: 1 for persistent (survives restart), 0 for temporary
  • BTTVariableType: Variable type (0 = string, 1 = number)
  • BTTVariableOnlySetIfNotYetDefined: boolean - Only set the variable if it has not been defined yet

Example:

{
  "BTTPredefinedActionType": 292,
  "BTTVariableName": "counter",
  "BTTVariableValue": "0",
  "BTTVariablePersist": 1,
  "BTTVariableType": 1
}

Increase Variable​

Increases numeric variable value.

Parameters:

  • BTTPredefinedActionType: 412
  • BTTVariableName: Variable name
  • BTTGenericActionConfig: Amount to increase

Example:

{
  "BTTPredefinedActionType": 412,
  "BTTVariableName": "counter",
  "BTTGenericActionConfig": "1"
}

Toggle Variable​

Toggles variable between values.

Parameters:

  • BTTPredefinedActionType: 335
  • BTTVariableName: Variable name
  • BTTGenericActionConfig: Toggle values configuration

Example:

{
  "BTTPredefinedActionType": 335,
  "BTTVariableName": "mode",
  "BTTGenericActionConfig": "{\"values\":[\"on\",\"off\"]}"
}

Toggle Multiple Variables / Cycle Through Multiple Actions​

Toggles multiple variables at once or cycles through multiple actions.

Parameters:

  • BTTPredefinedActionType: 335
  • BTTGenericActionConfig: Multiple variable configuration
  • BTTAdditionalActionData: JSON object (optional)
    • BTTActionCycleThroughMultipleResetAfterTimeout: boolean - reset to first action after timeout
    • BTTActionCycleThroughMultipleResetTimeout: float - timeout in seconds

Example:

{
  "BTTPredefinedActionType": 335,
  "BTTGenericActionConfig": "{\"variables\":[{\"name\":\"var1\",\"values\":[\"a\",\"b\"]},{\"name\":\"var2\",\"values\":[\"1\",\"2\"]}]}",
  "BTTAdditionalActionData": {
    "BTTActionCycleThroughMultipleResetAfterTimeout": true,
    "BTTActionCycleThroughMultipleResetTimeout": 5.0
  }
}

Toggle On/Off​

Simple on/off toggle for variable.

Parameters:

  • BTTPredefinedActionType: 346
  • BTTVariableName: Variable name

Example:

{
  "BTTPredefinedActionType": 346,
  "BTTVariableName": "enabled"
}

Ask For Input & Save to Variable​

Shows input dialog and saves to variable.

Parameters:

  • BTTPredefinedActionType: 403
  • BTTVariableName: Variable to save to
  • BTTGenericActionConfig: Input prompt text
  • BTTAdditionalActionData: JSON object with dialog configuration (optional)
    • BTTActionAskForInputTitle: Dialog title
    • BTTActionAskForInputPlaceholder: Placeholder text
    • BTTActionAskForInputDefaultValue: Default value
    • BTTActionAskForInputIsSecure: boolean - secure text entry
    • BTTActionAskForInputAllowEmpty: boolean - allow empty input
    • Other dialog configuration options

Example:

{
  "BTTPredefinedActionType": 403,
  "BTTVariableName": "userName",
  "BTTGenericActionConfig": "Please enter your name:",
  "BTTAdditionalActionData": {
    "BTTActionAskForInputTitle": "User Registration",
    "BTTActionAskForInputPlaceholder": "John Doe",
    "BTTActionAskForInputAllowEmpty": false
  }
}

Refresh Condition Values​

Re-evaluates all condition-based variables.

Parameters:

  • BTTPredefinedActionType: 350

Example:

{
  "BTTPredefinedActionType": 350
}

Show Variables View​

Shows window with all current variables.

Parameters:

  • BTTPredefinedActionType: 523

Example:

{
  "BTTPredefinedActionType": 523
}

Device Control​

Connect Bluetooth Device​

Connects to a Bluetooth device.

Parameters:

  • BTTPredefinedActionType: 274
  • BTTActionBluetoothDeviceAddress: Device address
  • BTTActionBluetoothDeviceName: Device name (optional)

Example:

{
  "BTTPredefinedActionType": 274,
  "BTTActionBluetoothDeviceAddress": "00:11:22:33:44:55"
}

Disconnect Bluetooth Device​

Disconnects a Bluetooth device.

Parameters:

  • BTTPredefinedActionType: 275
  • BTTActionBluetoothDeviceAddress: Device address
  • BTTActionBluetoothDeviceName: Device name (optional)

Example:

{
  "BTTPredefinedActionType": 275,
  "BTTActionBluetoothDeviceName": "AirPods Pro"
}

Toggle Bluetooth Device​

Toggles Bluetooth device connection.

Parameters:

  • BTTPredefinedActionType: 276
  • BTTActionBluetoothDeviceAddress: Device address
  • BTTActionBluetoothDeviceName: Device name (optional)

Example:

{
  "BTTPredefinedActionType": 276,
  "BTTActionBluetoothDeviceAddress": "00:11:22:33:44:55"
}

Enable Bluetooth​

Enables Bluetooth on the system.

Parameters:

  • BTTPredefinedActionType: 277

Example:

{
  "BTTPredefinedActionType": 277
}

Disable Bluetooth​

Disables Bluetooth on the system.

Parameters:

  • BTTPredefinedActionType: 278

Example:

{
  "BTTPredefinedActionType": 278
}

Toggle Bluetooth​

Toggles Bluetooth on/off.

Parameters:

  • BTTPredefinedActionType: 279

Example:

{
  "BTTPredefinedActionType": 279
}

Connect MIDI Device​

Connects to a MIDI device.

Parameters:

  • BTTPredefinedActionType: 271
  • BTTMidiDeviceName: Device identifier

Example:

{
  "BTTPredefinedActionType": 271,
  "BTTMidiDeviceName": "MIDI Controller"
}

Send MIDI Command​

Sends MIDI command to device.

Parameters:

  • BTTPredefinedActionType: 462
  • BTTGenericActionConfig: MIDI command data

Example:

{
  "BTTPredefinedActionType": 462,
  "BTTGenericActionConfig": "{\"channel\":1,\"note\":60,\"velocity\":127}"
}

Send Raw Data to Generic Device​

Sends raw data to connected device.

Parameters:

  • BTTPredefinedActionType: 379
  • BTTGenericActionConfig: Device and data configuration

Example:

{
  "BTTPredefinedActionType": 379,
  "BTTGenericActionConfig": "{\"device\":\"device-id\",\"data\":\"raw-hex-data\"}"
}

Execute Generic Device Command​

Executes command on generic device.

Parameters:

  • BTTPredefinedActionType: 380
  • BTTGenericActionConfig2: Command configuration
  • BTTGenericActionConfig: Command name

Example:

{
  "BTTPredefinedActionType": 380,
  "BTTGenericActionConfig": "Toggle LED",
  "BTTGenericActionConfig2": "{\"command\":\"led_toggle\"}"
}

Connect Sidecar​

Connects iPad as Sidecar display.

Parameters:

  • BTTPredefinedActionType: 506
  • BTTGenericActionConfig: Device identifier (optional)

Example:

{
  "BTTPredefinedActionType": 506
}

Disconnect Sidecar​

Disconnects Sidecar display.

Parameters:

  • BTTPredefinedActionType: 507

Example:

{
  "BTTPredefinedActionType": 507
}

BTT Mobile Actions​

Controls BTT Mobile companion app.

Parameters:

  • BTTPredefinedActionType:
    • Show Specific Menu: 452
    • Show Trackpad: 453 (see Mobile Trackpad Widget below for configuration)
    • Show Menu Overview: 454
    • Show Default Actions: 455
    • Show File Browser: 456
    • Disconnect: 457
    • Show Menubar: 510
    • Go Back: 511
    • Enable: 514
    • Disable: 515

Example:

{
  "BTTPredefinedActionType": 453
}

Mobile Trackpad Widget​

Shows a configurable trackpad on BTT Mobile device.

Parameters:

  • BTTPredefinedActionType: 453
  • BTTAdditionalActionData: JSON object with trackpad configuration
    • BTTMenuWidgetTrackpadTwoFingerScroll: boolean - Enable two-finger scrolling
    • BTTMenuWidgetTrackpadThreeFingerDrag: boolean - Enable three-finger drag
    • BTTMenuWidgetTrackpadDisableOnHost: boolean - Disable when host is active
    • BTTMenuWidgetTrackpadWidth: number - Trackpad width
    • BTTMenuWidgetTrackpadHeight: number - Trackpad height
    • BTTMenuWidgetTrackpadBorderWidth: number - Border width
    • BTTMenuWidgetTrackpadCornerRadius: number - Corner radius
    • BTTMenuWidgetTrackpadBorderColor: string - Border color (hex)
    • BTTMenuWidgetTrackpadFingerMoveColor: string - Finger move color (hex)
    • BTTMenuWidgetTrackpadFingerDragColor: string - Finger drag color (hex)
    • BTTMenuWidgetTrackpadFingerScrollColor: string - Finger scroll color (hex)

Example:

{
  "BTTPredefinedActionType": 453,
  "BTTAdditionalActionData": {
    "BTTMenuWidgetTrackpadTwoFingerScroll": true,
    "BTTMenuWidgetTrackpadThreeFingerDrag": true,
    "BTTMenuWidgetTrackpadWidth": 300,
    "BTTMenuWidgetTrackpadHeight": 200,
    "BTTMenuWidgetTrackpadBorderColor": "#CCCCCC",
    "BTTMenuWidgetTrackpadCornerRadius": 10
  }
}

Siri Remote Mouse Mode​

Controls Siri Remote mouse mode.

Parameters:

  • BTTPredefinedActionType:
    • Enable: 516
    • Disable: 517
    • Toggle: 166

Example:

{
  "BTTPredefinedActionType": 166
}

Logitech: Change Mouse DPI​

Changes the DPI (sensitivity) setting of a Logitech mouse (e.g. MX Master).

Parameters:

  • BTTPredefinedActionType: 554
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechDPI: number - DPI value
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 554,
  "BTTAdditionalActionData": {
    "BTTActionLogitechDPI": 1600,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Change Smart Shift / Ratchet Mode / Scroll Settings​

Changes smart shift, ratchet mode, and scroll settings of a Logitech mouse.

Parameters:

  • BTTPredefinedActionType: 555
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechTorque: number - Torque value
    • BTTActionLogitechSmartshiftMode: number - Smart shift mode
    • BTTActionLogitechAutoDisengange: number - Auto disengage setting
    • BTTActionLogitechScrollWheelHighResolutionMode: number - High resolution scroll mode
    • BTTActionLogitechScrollWheelInvertMain: number - Invert main scroll wheel
    • BTTActionLogitechScrollWheelInvertThumb: number - Invert thumb scroll wheel
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 555,
  "BTTAdditionalActionData": {
    "BTTActionLogitechSmartshiftMode": 1,
    "BTTActionLogitechTorque": 20,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Change LED Color​

Changes the LED color of a Logitech device.

Parameters:

  • BTTPredefinedActionType: 556
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechLEDColor: string - RGBA color string
    • BTTActionLogitechLEDMode: number - LED mode
    • BTTActionLogitechLEDIntensity: number - LED intensity
    • BTTActionLogitechLEDPeriod: number - LED period
    • BTTActionLogitechLEDWaveform: number - LED waveform
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 556,
  "BTTAdditionalActionData": {
    "BTTActionLogitechLEDColor": "1.0,0.0,0.0,1.0",
    "BTTActionLogitechLEDMode": 1,
    "BTTActionLogitechLEDIntensity": 100,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Change Report Rate​

Changes the report rate (polling rate in Hz) of a Logitech mouse.

Parameters:

  • BTTPredefinedActionType: 557
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechReportRate: number - Report rate in Hz
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 557,
  "BTTAdditionalActionData": {
    "BTTActionLogitechReportRate": 1000,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Change Profile​

Switches the onboard profile of a Logitech device.

Parameters:

  • BTTPredefinedActionType: 558
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechProfile: number - Profile index
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 558,
  "BTTAdditionalActionData": {
    "BTTActionLogitechProfile": 0,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Increase / Decrease Keyboard Brightness​

Increases or decreases the keyboard backlight brightness of a Logitech keyboard.

Parameters:

  • BTTPredefinedActionType:
    • Increase: 561
    • Decrease: 562
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechDeviceName: string - Name of the Logitech keyboard

Example:

{
  "BTTPredefinedActionType": 561,
  "BTTAdditionalActionData": {
    "BTTActionLogitechDeviceName": "MX Keys"
  }
}

Logitech: Increase / Decrease Mouse DPI​

Incrementally increases or decreases the mouse DPI by a scale factor.

Parameters:

  • BTTPredefinedActionType:
    • Increase: 563
    • Decrease: 564
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechDPIScaleFactor: number - Scale factor (default: 1.2)
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 563,
  "BTTAdditionalActionData": {
    "BTTActionLogitechDPIScaleFactor": 1.5,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Toggle Ratchet Mode​

Toggles the scroll wheel ratchet mode (free-spin vs. ratchet) of a Logitech mouse.

Parameters:

  • BTTPredefinedActionType: 565
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 565,
  "BTTAdditionalActionData": {
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

Logitech: Haptic Feedback​

Triggers haptic feedback on a supported Logitech mouse (MX Master 4 only).

Parameters:

  • BTTPredefinedActionType: 566
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechHapticPattern: number - Haptic pattern ID
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 566,
  "BTTAdditionalActionData": {
    "BTTActionLogitechHapticPattern": 1,
    "BTTActionLogitechMouseName": "MX Master 4"
  }
}

Logitech: Change Host / Channel​

Switches the active host/channel (1-3) on a multi-device Logitech device.

Parameters:

  • BTTPredefinedActionType: 568
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionLogitechChannel: number - Channel number (1-3)
    • BTTActionLogitechMouseName: string - Name of the Logitech device

Example:

{
  "BTTPredefinedActionType": 568,
  "BTTAdditionalActionData": {
    "BTTActionLogitechChannel": 2,
    "BTTActionLogitechMouseName": "MX Master 3S"
  }
}

UI Automation Actions​

Find Position of Image on Screen​

Finds image on screen and optionally clicks it.

Parameters:

  • BTTPredefinedActionType: 291
  • BTTFindPositionOfImageImage: Base64 encoded image (deprecated - use BTTAdditionalActionData)
  • BTTFindPositionOfImageImageDark: Base64 encoded dark mode image (optional, deprecated)
  • BTTFindPositionOfImageConfig: Configuration options (deprecated - use BTTAdditionalActionData)
  • BTTAdditionalActionData: JSON object with find image configuration
    • BTTActionFindImagePath: string - Path to image file
    • BTTActionFindImageTolerance: number - Match tolerance (0-100, default: 80)
    • BTTActionFindImageContrastEnhance: boolean - Enhance contrast before matching
    • BTTActionFindImageMakeGrayscale: boolean - Convert to grayscale before matching
    • BTTActionFindImageBinaryThreshold: number - Binary threshold for image processing (0-255)
    • BTTActionFindImageMatchMultiple: boolean - Find all matches instead of just the first
    • BTTActionFindImageWaitFor: number - Wait duration in seconds for image to appear
    • BTTActionFindImageScreen: number - Screen to search (0=all, 1=main, 2=mouse screen)
    • BTTActionFindImageEnableVisualFeedback: boolean - Show visual feedback on matches
    • BTTActionFindImageVariableIdentifier: string - Variable name to store result coordinates
    • BTTActionFindImageWaitMode: number - Wait behavior (0=fail if not found, 1=wait up to duration)
    • BTTActionFindImageFuzzyMatching: number - Fuzzy matching level (0-100)
    • BTTActionFindImageAction: number - Action on find (0=nothing, 1=move mouse, 2=click, 3=double click)
    • BTTActionFindImageHideMouseCursor: boolean - Hide mouse cursor during search
    • BTTFindImageUseDifferentDarkModeImage: boolean - Use a different image when dark mode is active
    • BTTFindImageSkipFirstMatches: number - Skip the first N matches and use the next one
    • BTTFindImageSearchRegion: string - Limit search to a specific screen region (coordinates)
    • BTTFindImageSquareSize: number - Square size for grid-based search

Example:

{
  "BTTPredefinedActionType": 291,
  "BTTAdditionalActionData": {
    "BTTActionFindImagePath": "/path/to/image.png",
    "BTTActionFindImageTolerance": 85,
    "BTTActionFindImageAction": 2,
    "BTTActionFindImageWaitFor": 5,
    "BTTActionFindImageEnableVisualFeedback": true,
    "BTTActionFindImageVariableIdentifier": "found_image_location"
  }
}

Scroll​

Sends scroll events.

Parameters:

  • BTTPredefinedActionType: 272
  • BTTScrollBy: Scroll configuration

Example:

{
  "BTTPredefinedActionType": 272,
  "BTTScrollBy": "0,5"
}

Start/Stop Scroll Blocking​

Blocks scroll events from reaching apps.

Parameters:

  • BTTPredefinedActionType:
    • Start Blocking: 381
    • Stop Blocking: 382
  • BTTAdditionalActionData (for Start Blocking): JSON object with configuration
    • BTTActionBlockScrollingConfig: number - Blocking configuration mode
    • BTTActionBlockScrollingOnlyOnTouchDevices: boolean - Only block scrolling from touch input devices (trackpad, Magic Mouse)

Example:

{
  "BTTPredefinedActionType": 381,
  "BTTAdditionalActionData": {
    "BTTActionBlockScrollingOnlyOnTouchDevices": true
  }
}

Zoom (Pinch)​

Performs zoom/pinch gesture.

Parameters:

  • BTTPredefinedActionType: 478
  • BTTGenericActionConfig: Zoom configuration

Example:

{
  "BTTPredefinedActionType": 478,
  "BTTGenericActionConfig": "{\"zoomIn\":true,\"amount\":1.5}"
}

Rotate​

Performs rotation gesture.

Parameters:

  • BTTPredefinedActionType: 479
  • BTTGenericActionConfig: Rotation configuration

Example:

{
  "BTTPredefinedActionType": 479,
  "BTTGenericActionConfig": "{\"degrees\":90,\"clockwise\":true}"
}

Smart Zoom​

Performs smart zoom (double tap with two fingers).

Parameters:

  • BTTPredefinedActionType: 117

Example:

{
  "BTTPredefinedActionType": 117
}

Look Up​

Shows definition/info for selected text.

Parameters:

  • BTTPredefinedActionType: 116

Example:

{
  "BTTPredefinedActionType": 116
}

Show Context Menu​

Shows context menu at current position.

Parameters:

  • BTTPredefinedActionType: 288
  • BTTCustomContextMenu: Custom menu configuration (optional)

Example:

{
  "BTTPredefinedActionType": 288
}

Show Context Menu for Selection​

Shows context menu for selected text.

Parameters:

  • BTTPredefinedActionType: 353

Example:

{
  "BTTPredefinedActionType": 353
}

Trigger Menu Bar Item​

Clicks a menu bar menu item.

Parameters:

  • BTTPredefinedActionType: 124
  • BTTMenubarPath: Menu path (e.g., "File;New")

Example:

{
  "BTTPredefinedActionType": 124,
  "BTTMenubarPath": "File;Save"
}

Trigger Context Menu Item​

Clicks item in context menu.

Parameters:

  • BTTPredefinedActionType: 162
  • BTTTriggerContextMenuPath: Menu item path

Example:

{
  "BTTPredefinedActionType": 162,
  "BTTTriggerContextMenuPath": "Copy"
}

Click Status Bar Item​

Clicks a status bar item.

Parameters:

  • BTTPredefinedActionType: 375
  • BTTActionStatusItem: Item identifier or position
  • BTTActionStatusItemClickType: Click type (optional)

Example:

{
  "BTTPredefinedActionType": 375,
  "BTTActionStatusItem": "Wi-Fi"
}

Show/Hide Status Bar Items​

Controls visibility of status bar items.

Parameters:

  • BTTPredefinedActionType:
    • Show Specific Item: 458
    • Hide Items Left of Item: 460
    • Show Items Left of Item: 461
    • Toggle Items Left: 265
    • Show All Items: 463
    • Hide from Always Hidden: 467
    • Show from Always Hidden: 466
    • Toggle Always Hidden: 468
  • BTTActionStatusItem: Item identifier

Example:

{
  "BTTPredefinedActionType": 265,
  "BTTActionStatusItem": "Bluetooth"
}

Move Status Bar Item​

Moves status bar item to new position.

Parameters:

  • BTTPredefinedActionType: 459
  • BTTActionStatusItem: Item identifier
  • BTTActionMoveToStatusItem: New position

Example:

{
  "BTTPredefinedActionType": 459,
  "BTTActionStatusItem": "VPN",
  "BTTActionMoveToStatusItem": 3
}

Search Menu Bar Status Items​

Opens search for status bar items.

Parameters:

  • BTTPredefinedActionType: 464

Example:

{
  "BTTPredefinedActionType": 464
}

Click Button in Active Window​

Clicks a button by name in active window.

Parameters:

  • BTTPredefinedActionType: 520
  • BTTGenericActionConfig: Button name

Example:

{
  "BTTPredefinedActionType": 520,
  "BTTGenericActionConfig": "OK"
}

Change Slider Value​

Changes slider value in active window.

Parameters:

  • BTTPredefinedActionType: 521
  • BTTGenericActionConfig: Slider identifier
  • BTTGenericActionConfig2: New value

Example:

{
  "BTTPredefinedActionType": 521,
  "BTTGenericActionConfig": "Volume",
  "BTTGenericActionConfig2": "75"
}

Interact with UI Element​

Generic UI element interaction using accessibility (AX) paths.

Parameters:

  • BTTPredefinedActionType: 522
  • BTTActionInteractWithUIElementAction: Action type
  • BTTActionInteractWithUIElementBringToFront: Bring to front flag
  • BTTActionInteractWithUIElementOnlyFocusedWindow: Only focused window
  • BTTActionInteractWithUIElementOptions: Additional options
  • BTTAdditionalActionData: JSON object with AX path configuration
    • BTTActionAXPath: string - Accessibility path to the UI element
    • BTTActionAXPathOnlySearchInFocusedWindow: boolean - Only search within the focused window
    • BTTActionAXBringToFront: boolean - Bring the target app to front before interacting

Example:

{
  "BTTPredefinedActionType": 522,
  "BTTActionInteractWithUIElementAction": "click",
  "BTTAdditionalActionData": {
    "BTTActionAXPath": "AXMenuBar/AXMenuBarItem[title='File']/AXMenu/AXMenuItem[title='Save']",
    "BTTActionAXPathOnlySearchInFocusedWindow": true,
    "BTTActionAXBringToFront": true
  }
}

Show UI Element Viewers​

Shows debugging viewers for UI elements.

Parameters:

  • BTTPredefinedActionType:
    • Focused Element: 503
    • Hovered Element: 504
    • Visible Windows: 505

Example:

{
  "BTTPredefinedActionType": 503
}

Get Hovered Link/URL​

Gets link or URL under mouse cursor.

Parameters:

  • BTTPredefinedActionType:
    • Get Link: 524
    • Get URL: 526
  • BTTVariableName: Variable to store result

Example:

{
  "BTTPredefinedActionType": 526,
  "BTTVariableName": "hoveredURL"
}

Start/End Keyboard Input Blocking​

Blocks keyboard input from reaching apps.

Parameters:

  • BTTPredefinedActionType:
    • Start Blocking: 429
    • End Blocking: 430

Example:

{
  "BTTPredefinedActionType": 429
}

Lock Mouse Axis Movement​

Locks mouse movement to specific axis.

Parameters:

  • BTTPredefinedActionType:
    • Lock X Start: 533
    • Lock X End: 534
    • Lock Y Start: 535
    • Lock Y End: 536

Example:

{
  "BTTPredefinedActionType": 533
}

Start / Stop Smooth Scroll​

Starts or stops continuous smooth scrolling. Can be used to simulate touchpad-like smooth scrolling.

Parameters:

  • BTTPredefinedActionType:
    • Start: 569
    • Stop: 570
  • BTTAdditionalActionData (for Start): JSON object with configuration
    • BTTScrollModifierSpeedVertical: number - Vertical scroll speed
    • BTTScrollModifierSpeedHorizontal: number - Horizontal scroll speed
    • BTTScrollModifierDuration: number - Duration of scroll deceleration in seconds
    • BTTScrollModifierEmaAlpha: number - EMA alpha smoothing factor (0-1)
    • BTTScrollModifierSubPixelBoost: number - Sub-pixel boost multiplier
  • BTTAdditionalActionData (for Stop): JSON object with configuration
    • BTTScrollStopImmediate: boolean - Stop immediately without deceleration

Example:

{
  "BTTPredefinedActionType": 569,
  "BTTAdditionalActionData": {
    "BTTScrollModifierSpeedVertical": 5.0,
    "BTTScrollModifierSpeedHorizontal": 0,
    "BTTScrollModifierDuration": 0.5
  }
}

Start / Stop Smooth Zoom​

Starts or stops continuous smooth zooming (pinch zoom gesture simulation).

Parameters:

  • BTTPredefinedActionType:
    • Start: 571
    • Stop: 572
  • BTTAdditionalActionData (for Start): JSON object with configuration
    • BTTZoomSpeed: number - Magnification per second
  • BTTAdditionalActionData (for Stop): JSON object with configuration
    • BTTZoomStopImmediate: boolean - Stop immediately without deceleration

Example:

{
  "BTTPredefinedActionType": 571,
  "BTTAdditionalActionData": {
    "BTTZoomSpeed": 2.0
  }
}

Start / Stop Smooth Rotate​

Starts or stops continuous smooth rotation (rotation gesture simulation).

Parameters:

  • BTTPredefinedActionType:
    • Start: 573
    • Stop: 574
  • BTTAdditionalActionData (for Start): JSON object with configuration
    • BTTRotateSpeed: number - Degrees per second
  • BTTAdditionalActionData (for Stop): JSON object with configuration
    • BTTRotateStopImmediate: boolean - Stop immediately without deceleration

Example:

{
  "BTTPredefinedActionType": 573,
  "BTTAdditionalActionData": {
    "BTTRotateSpeed": 45.0
  }
}

Start / Stop Smooth Space Switch​

Starts or stops smooth space switching animation (smooth horizontal desktop transition).

Parameters:

  • BTTPredefinedActionType:
    • Start: 575
    • Stop: 578
  • BTTAdditionalActionData (for Start): JSON object with configuration
    • BTTSpaceSwitchSpeed: number - Offset progress per second
    • BTTSpaceSwitchDragSensitivity: number - Drag sensitivity multiplier
  • BTTAdditionalActionData (for Stop): JSON object with configuration
    • BTTSpaceSwitchStopImmediate: boolean - Stop immediately without deceleration

Example:

{
  "BTTPredefinedActionType": 575,
  "BTTAdditionalActionData": {
    "BTTSpaceSwitchSpeed": 1.5
  }
}

Start Dictation / Speech Recognition​

Starts recognizing and transcribing speech using macOS speech recognition.

Parameters:

  • BTTPredefinedActionType: 576

Example:

{
  "BTTPredefinedActionType": 576
}

Stop Dictation & Paste or Copy​

Stops speech recognition and pastes or copies the transcribed text.

Parameters:

  • BTTPredefinedActionType: 577

Example:

{
  "BTTPredefinedActionType": 577
}

Custom Actions​

Show Custom Context Menu​

Shows a custom context menu with items.

Parameters:

  • BTTPredefinedActionType: 327
  • BTTGenericActionConfig: Menu configuration JSON
  • BTTActionCustomScriptSettings: Script settings (optional)

Example:

{
  "BTTPredefinedActionType": 327,
  "BTTGenericActionConfig": "{\"items\":[{\"title\":\"Option 1\",\"action\":248,\"trigger\":\"action1\"},{\"title\":\"Option 2\",\"action\":248,\"trigger\":\"action2\"}]}"
}

Show Custom HTML Menu​

Shows menu with HTML content.

Parameters:

  • BTTPredefinedActionType: 339
  • BTTGenericActionConfig: HTML menu configuration

Example:

{
  "BTTPredefinedActionType": 339,
  "BTTGenericActionConfig": "{\"html\":\"<div>Custom Menu</div>\",\"width\":200,\"height\":300}"
}

Show Searchable List​

Shows a searchable list of items. Items can be provided statically or retrieved dynamically from a script.

Parameters:

  • BTTPredefinedActionType: 465
  • BTTAdditionalActionData: JSON object with searchable list configuration
    • BTTActionSearchableListIconBackgroundColor: string - Icon background color (hex)
    • BTTActionSearchableListInputBehavior: number - Input behavior mode
    • BTTActionSearchableListPosition: number - List position on screen
    • BTTActionEmbeddedFloatingMenuIdentifier: string - UUID of a floating menu to embed in the list
    • BTTActionShowWithSimpleJSONFormatScriptSettings: object - Script settings for retrieving list content dynamically (AppleScript/Shell Script)
  • BTTActionCustomScriptSettingsJSON: JSON object with script configuration for dynamic content (optional, stored separately)

Example:

{
  "BTTPredefinedActionType": 465,
  "BTTAdditionalActionData": {
    "BTTActionSearchableListIconBackgroundColor": "#0084FF",
    "BTTActionSearchableListInputBehavior": 0,
    "BTTActionSearchableListPosition": 0
  }
}

Show Floating Web View​

Shows floating window with web content.

Parameters:

  • BTTPredefinedActionType: 249
  • BTTActionURLToLoad: URL or HTML file path
  • BTTActionFloatingHTMLConfig: Window configuration as JSON string (contains width, height, x, y, etc.)
  • BTTActionFloatingHTMLName: Window name/identifier (optional)
  • BTTAdditionalActionData: JSON object with additional configuration
    • BTTWebviewClickThrough: boolean - Allow clicks to pass through the webview
    • BTTWebviewDoNotAutofocus: boolean - Do not automatically focus the webview

Example:

{
  "BTTPredefinedActionType": 249,
  "BTTActionURLToLoad": "https://example.com",
  "BTTActionFloatingHTMLConfig": "{\"width\":800,\"height\":600,\"x\":100,\"y\":100}",
  "BTTAdditionalActionData": {
    "BTTWebviewClickThrough": false,
    "BTTWebviewDoNotAutofocus": true
  }
}

Close Floating Web View​

Closes floating web view window.

Parameters:

  • BTTPredefinedActionType: 372
  • BTTGenericActionConfig: Window identifier

Example:

{
  "BTTPredefinedActionType": 372,
  "BTTGenericActionConfig": "webview-1"
}

Show HUD​

Shows a heads-up display overlay with a message.

Parameters:

  • BTTPredefinedActionType: 254
  • BTTHUDActionConfiguration: HUD configuration JSON string (legacy format)
  • BTTAdditionalActionData: JSON object with HUD configuration
    • BTTActionHUDTitle: string - Main title text (plain text)
    • BTTActionHUDAttributedTitle: string - Attributed title (rich text, alternative to BTTActionHUDTitle)
    • BTTActionHUDDetail: string - Detail/subtitle text
    • BTTActionHUDBackground: string - Background color (hex, e.g. "#000000CC")
    • BTTActionHUDBlur: boolean - Enable system blur effect behind HUD
    • BTTActionHUDDuration: number - Display duration in seconds (0 = stays until dismissed)
    • BTTActionHUDHideWhenOtherHUDAppears: boolean - Close immediately when another HUD appears
    • BTTActionHUDCloseOnClick: boolean - Close the HUD when clicked
    • BTTActionHUDPosition: number - Screen position (0=center, 1=top-center, 2=bottom-center, 3=top-left, 4=top-right, 5=bottom-left, 6=bottom-right)
    • BTTActionHUDOffsetX: number - Horizontal offset from position in pixels
    • BTTActionHUDOffsetY: number - Vertical offset from position in pixels
    • BTTActionHUDSlideDirection: number - Animation slide direction
    • BTTActionHUDDisplayToUse: number - Which display to show on (0=main, 1=mouse screen, etc.)
    • BTTActionHUDWidth: number - HUD width in pixels (0 = auto)
    • BTTActionHUDHeight: number - HUD height in pixels (0 = auto)
    • BTTActionHUDPadding: number - Inner padding in pixels
    • BTTActionHUDBorderColor: string - Border color (hex)
    • BTTActionHUDBorderWidth: number - Border width in pixels

Example:

{
  "BTTPredefinedActionType": 254,
  "BTTAdditionalActionData": {
    "BTTActionHUDTitle": "Action completed!",
    "BTTActionHUDDetail": "Your files have been saved.",
    "BTTActionHUDDuration": 2,
    "BTTActionHUDBackground": "#000000CC",
    "BTTActionHUDBlur": true,
    "BTTActionHUDPosition": 0,
    "BTTActionHUDCloseOnClick": true
  }
}

Show Notification​

Shows system notification.

Parameters:

  • BTTPredefinedActionType: 371
  • BTTAdditionalActionData: JSON object with notification configuration
    • BTTActionSendNotificationTitle: string - Notification title
    • BTTActionSendNotificationSubTitle: string - Notification subtitle
    • BTTActionSendNotificationMessage: string - Notification body message
    • BTTActionSendNotificationSound: string - Sound name to play (optional)
    • BTTActionSendNotificationAttachment: string - Path to image attachment (optional)

Example:

{
  "BTTPredefinedActionType": 371,
  "BTTAdditionalActionData": {
    "BTTActionSendNotificationTitle": "BetterTouchTool",
    "BTTActionSendNotificationSubTitle": "Task Update",
    "BTTActionSendNotificationMessage": "Task completed successfully",
    "BTTActionSendNotificationSound": "default"
  }
}

Haptic Feedback​

Triggers haptic feedback on trackpad.

Parameters:

  • BTTPredefinedActionType: 255
  • BTTHapticFeedbackAction: Pattern type (1-22)

Example:

{
  "BTTPredefinedActionType": 255,
  "BTTHapticFeedbackAction": 1
}

Show Color Picker​

Shows the color picker dialog.

Parameters:

  • BTTPredefinedActionType: 94

Example:

{
  "BTTPredefinedActionType": 94
}

Show Cheat Sheet​

Shows keyboard shortcut cheat sheet.

Parameters:

  • BTTPredefinedActionType: 354
  • BTTAdditionalActionData: JSON object with cheat sheet configuration
    • BTTActionCheatSheetTitleTextColor: string - Title text color (hex)
    • BTTActionCheatSheetDescriptionTextColor: string - Description text color (hex)
    • BTTActionCheatSheetBackground: string - Background color (hex)
    • BTTActionCheatSheetBackgroundAlpha: number - Background transparency (0-1)
    • BTTActionCheatSheetItemsPerColumn: number - Number of items per column
    • BTTActionCheatSheetItemHeight: number - Height of each item
    • BTTActionCheatSheetWindowCornerRadius: number - Window corner radius
    • BTTActionCheatSheetWindowWidth: number - Window width
    • BTTActionCheatSheetWindowPadding: number - Window padding
    • BTTActionCheatSheetItemBackground: string - Item background color (hex)
    • BTTActionCheatSheetItemBorderColor: string - Item border color (hex)
    • BTTActionCheatSheetShowIcon: boolean - Show app icons
    • BTTActionCheatSheetShowActiveAppOnly: boolean - Show only active app shortcuts

Example:

{
  "BTTPredefinedActionType": 354,
  "BTTAdditionalActionData": {
    "BTTActionCheatSheetBackground": "#000000",
    "BTTActionCheatSheetBackgroundAlpha": 0.9,
    "BTTActionCheatSheetTitleTextColor": "#FFFFFF",
    "BTTActionCheatSheetDescriptionTextColor": "#CCCCCC",
    "BTTActionCheatSheetItemsPerColumn": 10,
    "BTTActionCheatSheetShowIcon": true
  }
}

Hide/Toggle Cheat Sheet​

Controls cheat sheet visibility.

Parameters:

  • BTTPredefinedActionType:
    • Hide: 355
    • Toggle: 356

Example:

{
  "BTTPredefinedActionType": 356
}

Open URL​

Opens URL in default browser.

Parameters:

  • BTTPredefinedActionType: 59
  • BTTOpenURL: URL to open
  • BTTOpenURLBrowser: Specific browser (optional)
  • BTTOpenURLTerminalCommand: Use terminal command flag (optional)

Example:

{
  "BTTPredefinedActionType": 59,
  "BTTOpenURL": "https://folivora.ai",
  "BTTOpenURLBrowser": "com.apple.Safari"
}

Post Distributed Notification​

Posts a system-wide notification.

Parameters:

  • BTTPredefinedActionType: 136
  • BTTPostDistributedNotificationName: Notification name
  • BTTActionUserInfo: Notification data (optional)

Example:

{
  "BTTPredefinedActionType": 136,
  "BTTPostDistributedNotificationName": "com.myapp.notification"
}

Change Input Source​

Changes keyboard input source/language.

Parameters:

  • BTTPredefinedActionType: 420
  • BTTGenericActionConfig: Input source ID
  • BTTAdditionalActionData: JSON object with configuration (optional)
    • BTTActionChangeInputSourceID: Input source identifier
    • Other BTTActionChangeInputSource* keys for additional settings

Example:

{
  "BTTPredefinedActionType": 420,
  "BTTGenericActionConfig": "com.apple.keylayout.US",
  "BTTAdditionalActionData": {
    "BTTActionChangeInputSourceID": "com.apple.keylayout.US"
  }
}

Change Default Browser​

Changes system default browser.

Parameters:

  • BTTPredefinedActionType: 492
  • BTTGenericActionConfig: Browser bundle identifier

Example:

{
  "BTTPredefinedActionType": 492,
  "BTTGenericActionConfig": "com.google.Chrome"
}

Set Function Key Mode​

Sets function key behavior.

Parameters:

  • BTTPredefinedActionType: 436
  • BTTGenericActionConfig: Mode (0=F keys, 1=media keys)

Example:

{
  "BTTPredefinedActionType": 436,
  "BTTGenericActionConfig": "1"
}

Call macOS Service​

Calls a macOS service by name.

Parameters:

  • BTTPredefinedActionType: 435
  • BTTGenericActionConfig: Service name

Example:

{
  "BTTPredefinedActionType": 435,
  "BTTGenericActionConfig": "Look Up in Dictionary"
}

Set Icon for File​

Sets custom icon for file/folder/app.

Parameters:

  • BTTPredefinedActionType: 473
  • BTTGenericActionConfig: File path
  • BTTGenericActionConfig2: Icon path or data

Example:

{
  "BTTPredefinedActionType": 473,
  "BTTGenericActionConfig": "/Applications/MyApp.app",
  "BTTGenericActionConfig2": "/path/to/icon.icns"
}

Create Snap Area​

Creates a new window snap area.

Parameters:

  • BTTPredefinedActionType: 391
  • BTTGenericActionConfig: Snap area configuration

Example:

{
  "BTTPredefinedActionType": 391,
  "BTTGenericActionConfig": "{\"x\":0,\"y\":0,\"width\":640,\"height\":480}"
}

Edit Snap Areas​

Opens snap area editor.

Parameters:

  • BTTPredefinedActionType: 392

Example:

{
  "BTTPredefinedActionType": 392
}

Trigger Snap Area​

Triggers specific snap area.

Parameters:

  • BTTPredefinedActionType: 168
  • BTTDragPointUUID: Snap area identifier
  • BTTResizeWindowToRect: Window rect (optional)

Example:

{
  "BTTPredefinedActionType": 168,
  "BTTDragPointUUID": "left-half"
}

Plugin Action​

Executes a BTT plugin action.

Parameters:

  • BTTPredefinedActionType: 280
  • BTTGenericActionConfig2: Plugin identifier
  • BTTAdditionalActionData: Plugin parameters

Example:

{
  "BTTPredefinedActionType": 280,
  "BTTGenericActionConfig2": "com.example.plugin",
  "BTTAdditionalActionData": "{\"action\":\"custom\"}"
}

JSON Action Plugin​

Executes a JSON-based action plugin (.bttjsonplugin). JSON plugins are simple JSON files that define actions with configurable form fields and placeholder substitution. They do not require compiled code — just a .bttjsonplugin file placed in the BetterTouchTool Plugins folder.

Parameters:

  • BTTPredefinedActionType: 588
  • BTTGenericActionConfig2: Plugin identifier (e.g. "com.btt.jsonplugin.my-plugin")
  • BTTAdditionalActionData: JSON object with plugin form field values (keys prefixed with plugin_var_)

Example:

{
  "BTTPredefinedActionType": 588,
  "BTTGenericActionConfig2": "com.btt.jsonplugin.my-plugin",
  "BTTAdditionalActionData": {
    "plugin_var_message": "Hello World",
    "plugin_var_delay": "0.5"
  }
}

Comment​

No-op action for adding comments in action sequences.

Parameters:

  • BTTPredefinedActionType: 490
  • BTTComment: Comment text

Example:

{
  "BTTPredefinedActionType": 490,
  "BTTComment": "This is a comment explaining the next actions"
}

Separator​

Visual separator in action lists.

Parameters:

  • BTTPredefinedActionType: 323

Example:

{
  "BTTPredefinedActionType": 323
}

AI Actions​

AI-related actions for ChatGPT integration.

Parameters:

  • BTTPredefinedActionType:
    • Add User Message: 530
    • Switch Model: 537
  • BTTGenericActionConfig: AI configuration

Example:

{
  "BTTPredefinedActionType": 530,
  "BTTGenericActionConfig": "{\"message\":\"Hello AI\",\"conversation\":\"main\"}"
}

AI Chat Window​

Opens an AI chat window with customizable settings.

Parameters:

  • BTTPredefinedActionType: 999
  • BTTAdditionalActionData: JSON object with AI configuration
    • BTTAISystemPrompt: string - System prompt for the AI
    • BTTAIAPIKey: string - API key for AI service (secure)
    • BTTAIAPIKey1: string - Alternative API key 1
    • BTTAIAPIKey2: string - Alternative API key 2
    • BTTAICustomURL: string - Custom API endpoint URL
    • BTTAIModel: string - Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet-latest")
    • BTTAISInitialScreenshot: number - Screenshot capture option (0=None, 1=Interactive, 2=Focused Window)
    • BTTAIUserChatBubbleColor: string - Custom color for user messages (hex)
    • BTTAISystemChatBubbleColor: string - Custom color for AI responses (hex)
    • BTTAIWindowBackgroundColor: string - Background color for AI window (hex)

Example:

{
  "BTTPredefinedActionType": 999,
  "BTTAdditionalActionData": {
    "BTTAIModel": "gpt-4o",
    "BTTAISystemPrompt": "You are a helpful assistant",
    "BTTAISInitialScreenshot": 1,
    "BTTAIUserChatBubbleColor": "#0084FF",
    "BTTAISystemChatBubbleColor": "#E9E9EB"
  }
}

h@llo.ai - Show Customizable AI Assistant​

Shows the customizable h@llo.ai (hello.ai) AI assistant window.

Parameters:

  • BTTPredefinedActionType: 525
  • BTTAdditionalActionData: JSON object with AI assistant configuration

Example:

{
  "BTTPredefinedActionType": 525,
  "BTTAdditionalActionData": {}
}

h@llo.ai - Update AI Chat Properties​

Updates properties of an active h@llo.ai chat session.

Parameters:

  • BTTPredefinedActionType: 538
  • BTTAdditionalActionData: JSON object with configuration
    • BTTAIChatIdentifier: string - Identifier of the chat to update
    • BTTAIShowProgressIndicator: boolean - Show/hide progress indicator
    • BTTAIBackgroundReuseConversation: boolean - Reuse existing conversation

Example:

{
  "BTTPredefinedActionType": 538,
  "BTTAdditionalActionData": {
    "BTTAIChatIdentifier": "my_chat",
    "BTTAIShowProgressIndicator": true,
    "BTTAIBackgroundReuseConversation": true
  }
}

h@llo.ai - Cancel All Ongoing Requests​

Cancels all ongoing h@llo.ai AI requests.

Parameters:

  • BTTPredefinedActionType: 541

Example:

{
  "BTTPredefinedActionType": 541
}

h@llo.ai - Close All Assistant Windows​

Closes all open h@llo.ai assistant windows.

Parameters:

  • BTTPredefinedActionType: 542

Example:

{
  "BTTPredefinedActionType": 542
}

h@llo.ai - Run AI Task In Background​

Runs an AI task in the background without showing a window.

Parameters:

  • BTTPredefinedActionType: 581
  • BTTAdditionalActionData: JSON object with configuration
    • BTTAIChatIdentifier: string - Chat identifier
    • BTTAIUserMessage: string - The user message/prompt to send
    • BTTAIShowProgressIndicator: boolean - Show progress indicator
    • BTTAIBackgroundReuseConversation: boolean - Reuse existing conversation
    • BTTAIUserMessageFileType: number - File type for the message

Example:

{
  "BTTPredefinedActionType": 581,
  "BTTAdditionalActionData": {
    "BTTAIChatIdentifier": "background_task",
    "BTTAIUserMessage": "Summarize the clipboard contents",
    "BTTAIShowProgressIndicator": false,
    "BTTAIBackgroundReuseConversation": false
  }
}

Stage Manager Actions​

Controls macOS Stage Manager.

Parameters:

  • BTTPredefinedActionType:
    • Enable/Disable: 360
    • Activate Stage: 357
    • Cycle Stages: 358
    • Cycle Backward: 363
    • Activate Stage with Apps: 359
    • Show Switcher: 361
    • Toggle Recent: 362
  • BTTStageManagerStageNumber: Stage number (for activate)
  • BTTStageManagerRequiredApps: App identifiers (for activate with apps)
  • BTTStageManagerRequiredWindows: Window identifiers (optional)

Example:

{
  "BTTPredefinedActionType": 357,
  "BTTStageManagerStageNumber": "1"
}

Dock Actions​

Performs actions on dock items.

Parameters:

  • BTTPredefinedActionType:
    • Quit App: 145
    • Minimize: 146
    • Show All Windows: 147
    • Send Shortcut: 148

Example:

{
  "BTTPredefinedActionType": 145
}

Toggle Actions​

Various toggle actions.

Parameters:

  • BTTPredefinedActionType:
    • Mouse Cursor Hidden: 140
    • Cursor Size: 123
    • Mouse Speed: 126
    • Black Screen: 313

Example:

{
  "BTTPredefinedActionType": 140
}

Login/Security Actions​

Login and security related actions.

Parameters:

  • BTTPredefinedActionType:
    • Login Screen: 9
    • Free Menu Bar: 86

Example:

{
  "BTTPredefinedActionType": 9
}

Advanced Click Actions​

Clicks with specific modifiers.

Parameters:

  • BTTPredefinedActionType:
    • Cmd+Click: 2
    • Ctrl+Click: 87
    • Alt+Click: 88
    • Shift+Click: 89
    • Cmd+Shift+Click: 111
    • Cmd+Double Click: 149

Example:

{
  "BTTPredefinedActionType": 2
}

Gesture Control​

Controls for trackpad/mouse gestures.

Parameters:

  • BTTPredefinedActionType:
    • Begin Gesture: 75
    • End Gesture: 76
    • End Immediately: 83
    • Swipe Left: 77
    • Swipe Right: 78
    • Swipe Up: 79
    • Swipe Down: 80
    • Rotate Left: 81
    • Rotate Right: 82

Example:

{
  "BTTPredefinedActionType": 75
}

Zoom In/Out​

System zoom controls.

Parameters:

  • BTTPredefinedActionType:
    • Zoom In: 11
    • Zoom Out: 12

Example:

{
  "BTTPredefinedActionType": 11
}

Window Snapping​

Split screen and window snapping.

Parameters:

  • BTTPredefinedActionType:
    • Split Screen Left: 163
    • Split Screen Right: 164

Example:

{
  "BTTPredefinedActionType": 163
}

Fullscreen​

Fullscreen control.

Parameters:

  • BTTPredefinedActionType: 112

Example:

{
  "BTTPredefinedActionType": 112
}

No Action​

Placeholder that performs no action.

Parameters:

  • BTTPredefinedActionType: -1

Example:

{
  "BTTPredefinedActionType": -1
}

Additional Missing Actions​

Change Default Browser/Handler​

Changes the default application handler for specific file types, URL schemes, or UTIs. Parameters:

  • BTTPredefinedActionType: 492
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionChangeDefaultBrowserUTI: string - Scheme/UTI/Extension (e.g. "http://", "adobe.pdf", ".txt")
    • BTTActionChangeDefaultBrowserApp: object - Application info
      • name: string - Application name
      • path: string - Path to application
      • bundleIdentifier: string - Bundle ID Example:
{
  "BTTPredefinedActionType": 492,
  "BTTAdditionalActionData": {
    "BTTActionChangeDefaultBrowserUTI": "http://",
    "BTTActionChangeDefaultBrowserApp": {
      "name": "Safari",
      "path": "/Applications/Safari.app",
      "bundleIdentifier": "com.apple.Safari"
    }
  }
}

OCR (Extract Text from Image)​

Performs optical character recognition on screen content or images. Parameters:

  • BTTPredefinedActionType: 498
  • BTTAdditionalActionData: JSON object with OCR configuration
    • BTTOCRSourceType: number - Source type (0=screenshot, 1=file, 2=clipboard)
    • BTTOCRFileAtPath: string - Path to image file (when sourceType=1)
    • BTTOCRAutoDetectLanguage: boolean - Auto-detect language
    • BTTOCRLanguages: array - Language codes (e.g., ["en-US", "de-DE"])
    • BTTOCRCustomWords: array - Custom words for recognition
    • BTTOCRJoinBasedOnScreenCoordinates: boolean - Join text based on position
    • BTTOCRJoinFoundStringsWithCharacter: string - Character to join text (e.g., " " or "\n")
    • BTTOCRSaveToVariable: string - Variable name to save result
    • BTTOCRCopyToClipboard: boolean - Copy result to clipboard Example:
{
  "BTTPredefinedActionType": 498,
  "BTTAdditionalActionData": {
    "BTTOCRSourceType": 0,
    "BTTOCRAutoDetectLanguage": true,
    "BTTOCRCopyToClipboard": true,
    "BTTOCRSaveToVariable": "ocr_result"
  }
}

Remap Key​

Remaps keyboard input with customizable modifier keys and key codes. Parameters:

  • BTTPredefinedActionType: 483
  • BTTAdditionalActionData: JSON object with key remapping configuration
    • BTTActionRemapKeyOutDownCommand: number (0/1) - Command key on key down
    • BTTActionRemapKeyOutDownControl: number (0/1) - Control key on key down
    • BTTActionRemapKeyOutDownShift: number (0/1) - Shift key on key down
    • BTTActionRemapKeyOutDownOption: number (0/1) - Option key on key down
    • BTTActionRemapKeyOutDownFn: number (0/1) - Fn key on key down
    • BTTActionRemapKeyOutUpCommand: number (0/1) - Command key on key up
    • BTTActionRemapKeyOutUpControl: number (0/1) - Control key on key up
    • BTTActionRemapKeyOutUpShift: number (0/1) - Shift key on key up
    • BTTActionRemapKeyOutUpOption: number (0/1) - Option key on key up
    • BTTActionRemapKeyOutUpFn: number (0/1) - Fn key on key up
    • BTTActionRemapKeyOutKeyUsingKeyCode: boolean - Use key code instead of string
    • BTTActionRemapKeyOutKeyUsingString: boolean - Use string instead of key code
    • BTTActionRemapKeyOutKeyString: string - Key as string (when using string mode)
    • BTTActionRemapKeyOutKeyCode: number - Key code (when using key code mode) Example:
{
  "BTTPredefinedActionType": 483,
  "BTTAdditionalActionData": {
    "BTTActionRemapKeyOutDownCommand": 1,
    "BTTActionRemapKeyOutDownShift": 1,
    "BTTActionRemapKeyOutKeyUsingKeyCode": true,
    "BTTActionRemapKeyOutKeyCode": 0
  }
}

Send Data to Connected BTT Mobile/iOS Device​

Sends data to a connected BetterTouchTool mobile device. Parameters:

  • BTTPredefinedActionType: 285
  • BTTAdditionalActionData: JSON object with configuration
    • BTTActionSendDataData: string - The data to send
    • BTTActionSendDataMaxPayloadSize: number - Maximum payload size in bytes Example:
{
  "BTTPredefinedActionType": 285,
  "BTTAdditionalActionData": {
    "BTTActionSendDataData": "Hello from Mac!",
    "BTTActionSendDataMaxPayloadSize": 1024
  }
}

Unlock Screen (with Password)​

Unlocks the Mac screen using a stored password. Parameters:

  • BTTPredefinedActionType: 159
  • BTTAdditionalActionData: JSON object with configuration
    • unlockPassword: string - The password (stored securely) Example:
{
  "BTTPredefinedActionType": 159,
  "BTTAdditionalActionData": {
    "unlockPassword": "encrypted_password_data"
  }
}

Additional Notes​

Action Sequences​

Multiple actions can be chained together by including them in an array:

[
  {
    "BTTPredefinedActionType": 345,
    "BTTDelayNextActionBy": "1.0"
  },
  {
    "BTTPredefinedActionType": 193,
    "BTTStringToType": "Hello World"
  }
]

Helper Functions​

function getModifierBitmask(modifiers) {
    const modifierMap = {
        "Shift": 1 << 17,
        "Control": 1 << 18,
        "Left Control": 1 << 0,
        "Right Control": 1 << 13,
        "Option": 1 << 19,
        "Left Option": 1 << 5,
        "Right Option": 1 << 6,
        "Command": 1 << 20,
        "Left Command": 1 << 3,
        "Right Command": 1 << 4,
        "Function": 1 << 23
    };

    let bitmask = 0;

    for (const modifier of modifiers) {
        if (modifierMap[modifier] !== undefined) {
            bitmask |= modifierMap[modifier];
        } else {
            console.warn(`Unknown modifier: ${modifier}`);
        }
    }

    return bitmask;
}
  • 18: Custom Context Menu

Generic Configuration Fields​

When specific property names aren't mapped for an action, these generic fields are used as fallbacks:

  • BTTGenericActionConfig: Primary configuration string/JSON (used when gesture.launchPath isn't specifically mapped)
  • BTTGenericActionConfig2: Secondary configuration (used when gesture.additionalActionString isn't specifically mapped)
  • BTTAdditionalActionData: Complex data as JSON or base64 (typically from gesture.actionData)

Special Data Handling​

Some actions use special data storage:

  • BTTFindPositionOfImageImage: Base64 encoded image data
  • BTTFindPositionOfImageImageDark: Base64 encoded dark mode variant
  • BTTActionCustomScriptSettings: Base64 encoded script settings
  • BTTAdditionalActionData: Can contain JSON objects or base64 encoded data

Shortcuts and Modifiers​

When using keyboard shortcuts:

  • BTTShortcutToSend: The actual key or key combination
  • BTTShortcutModifierKeys: Modifier keys for general shortcuts
  • BTTRequiredModifierKeys: Modifier keys for non-shortcut triggers
  • BTTShortcutUpDown: Whether to send key up/down events

Best Practices​

  1. Always include BTTPredefinedActionType with the correct action ID
  2. Use the specific property names documented here instead of generic fallbacks when possible
  3. String values should be properly escaped in JSON
  4. Numeric values can be strings or numbers depending on the action
  5. Test actions individually before combining in sequences
  6. Use conditions to make actions context-aware
  7. Leverage variables for dynamic behavior
  8. Group related actions using control flow structures

Action Categories​

Many trigger types in BetterTouchTool support multiple action categories. Action categories allow a single trigger to execute different actions depending on how the trigger is activated (e.g., on key down vs. key release, on hover vs. click, etc.).

Each action assigned to a trigger has a BTTActionCategory integer value that determines when it fires. The available categories depend on the trigger type.

BTTActionCategory Values​

ValueConstantDescription
0BTTActionCategoryStandardDefault/primary action
1BTTActionCategoryHoverHover start
2BTTActionCategoryLongPressLong press / long hold down
3BTTActionCategoryTouchReleaseTouch release / button up
4BTTActionCategoryHoverEndHover end
5BTTActionCategoryHyperKeyReleaseHyper key release (unused)
6BTTActionCategoryRightClickRight click
7BTTActionCategoryChangeToFalseCondition changed to false
8BTTActionCategoryAppearItem appeared
9BTTActionCategoryDisappearItem disappeared
10BTTActionCategoryOnDropItem received a drop
11BTTActionCategoryScrollLeftScroll left
12BTTActionCategoryScrollRightScroll right
13BTTActionCategoryScrollUpScroll up
14BTTActionCategoryScrollDownScroll down
15BTTActionCategoryBTTMobileThreeFingerSwipeLeftBTT Remote three-finger swipe left
16BTTActionCategoryBTTMobileThreeFingerSwipeRightBTT Remote three-finger swipe right
17BTTActionCategoryPressDownButton press down
18BTTActionCategoryCustomContextMenuCustom context menu
19BTTActionCategoryAppIsRunningApp is running
20BTTActionCategoryAppIsNotRunningApp is not running
21BTTActionCategoryDragDownDrag down (discrete)
22BTTActionCategoryDragUpDrag up (discrete)
23BTTActionCategoryDragLeftDrag left (discrete)
24BTTActionCategoryDragRightDrag right (discrete)
25BTTActionCategoryDragDownContinuousDrag down (continuous)
26BTTActionCategoryDragUpContinuousDrag up (continuous)
27BTTActionCategoryDragLeftContinuousDrag left (continuous)
28BTTActionCategoryDragRightContinuousDrag right (continuous)
29BTTActionCategoryConnectDevice connected
30BTTActionCategoryDisconnectDevice disconnected
31BTTActionCategoryButtonReleaseButton/click release
32BTTActionCategoryButtonQuickReleaseQuick button/click release
33BTTActionCategoryButtonReleaseAfterLongPressButton/click release after long hold
34BTTActionCategorySeparatorSeparator (UI only, not assignable)
35BTTActionCategoryKeyReleaseKey release
36BTTActionCategoryKeyQuickReleaseQuick key release
37BTTActionCategoryKeyReleaseAfterLongPressKey release after long hold
38BTTActionCategoryKeyLongPressLong key hold down
39BTTActionCategoryFirstScrollFirst scroll only
40BTTActionCategoryCrownRotateLeftSmoothLogitech Craft Crown rotate left (smooth)
41BTTActionCategoryCrownRotateRightSmoothLogitech Craft Crown rotate right (smooth)
42BTTActionCategoryCrownRotateLeftRatchetLogitech Craft Crown rotate left (ratchet)
43BTTActionCategoryCrownRotateRightRatchetLogitech Craft Crown rotate right (ratchet)
44BTTActionCategoryCrownTapLogitech Craft Crown tap
45BTTActionCategoryCrownPressDownLogitech Craft Crown press down
46BTTActionCategoryCrownPressUpLogitech Craft Crown press up
47BTTActionCategoryKeyReleaseAfterAllModifiersReleasedKey release after all modifier keys released

Categories by Trigger Type​

Keyboard Shortcuts​

Regular keyboard shortcuts support the following action categories:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on key down
BTTActionCategoryKeyLongPress38Actions executed on long key hold down
BTTActionCategoryKeyRelease35Actions executed on key release
BTTActionCategoryKeyQuickRelease36Actions executed on quick key release
BTTActionCategoryKeyReleaseAfterLongPress37Actions executed on key release after long hold
BTTActionCategoryKeyReleaseAfterAllModifiersReleased47Actions executed after all modifier keys released

Hyper Key shortcuts only support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on trigger
BTTActionCategoryHyperKeyRelease5Actions executed on (unused) hyper key release

Mouse Triggers​

Mouse button triggers support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on press
BTTActionCategoryLongPress2Actions executed on long hold down
BTTActionCategoryButtonRelease31Actions executed on click release
BTTActionCategoryButtonQuickRelease32Actions executed on quick click release
BTTActionCategoryButtonReleaseAfterLongPress33Actions executed on click release after long hold
BTTActionCategoryDragUp22Actions executed on drag up (discrete)
BTTActionCategoryDragDown21Actions executed on drag down (discrete)
BTTActionCategoryDragLeft23Actions executed on drag left (discrete)
BTTActionCategoryDragRight24Actions executed on drag right (discrete)
BTTActionCategoryDragUpContinuous26Actions executed on drag up (continuous)
BTTActionCategoryDragDownContinuous25Actions executed on drag down (continuous)
BTTActionCategoryDragLeftContinuous27Actions executed on drag left (continuous)
BTTActionCategoryDragRightContinuous28Actions executed on drag right (continuous)

Mouse scroll triggers support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on scroll (repeating)
BTTActionCategoryFirstScroll39Actions executed on first scroll only

Mouse scroll+button combo triggers additionally support:

CategoryValueDescription
BTTActionCategoryButtonRelease31Actions executed on button release
BTTActionCategoryButtonQuickRelease32Actions executed on quick button release
BTTActionCategoryButtonReleaseAfterLongPress33Actions executed on button release after long hold

Trackpad / Magic Mouse / Siri Remote Triggers​

Most trackpad, Magic Mouse, and Siri Remote gesture triggers support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on trigger
BTTActionCategoryTouchRelease3Actions executed on touch release

Stream Deck Triggers​

Stream Deck button triggers support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on button down
BTTActionCategoryTouchRelease3Actions executed on button up
BTTActionCategoryLongPress2Actions executed on long press

Stream Deck dial triggers support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on dial turn
BTTActionCategoryTouchRelease3Actions executed on dial press
BTTActionCategoryLongPress2Actions executed on dial long press

Floating Menu Triggers​

Standard floating menu items and submenus support:

CategoryValueDescription
BTTActionCategoryHover1Actions executed on hover start
BTTActionCategoryHoverEnd4Actions executed on hover end
BTTActionCategoryOnDrop10Actions executed on drop
BTTActionCategoryAppear8Actions executed on appear
BTTActionCategoryDisappear9Actions executed on disappear

Other floating menu items (buttons, widgets, etc.) support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on trigger (button release)
BTTActionCategoryPressDown17Actions executed on button press down
BTTActionCategoryHover1Actions executed on hover start
BTTActionCategoryHoverEnd4Actions executed on hover end
BTTActionCategoryOnDrop10Actions executed on drop
BTTActionCategoryRightClick6Actions executed on right click
BTTActionCategoryScrollLeft11Actions executed on scroll left
BTTActionCategoryScrollRight12Actions executed on scroll right
BTTActionCategoryScrollUp13Actions executed on scroll up
BTTActionCategoryScrollDown14Actions executed on scroll down

BTT Remote trackpad items in floating menus support:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on trigger
BTTActionCategoryBTTMobileThreeFingerSwipeLeft15Actions executed on three-finger swipe left
BTTActionCategoryBTTMobileThreeFingerSwipeRight16Actions executed on three-finger swipe right

Menu Bar / Status Icon Triggers​

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on left click
BTTActionCategoryRightClick6Actions executed on right click

Dock Icon Triggers​

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on click
BTTActionCategoryCustomContextMenu18Custom dock context menu

Conditional Triggers (Advanced Trigger Conditions / Script Output Changed)​

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on change to TRUE
BTTActionCategoryChangeToFalse7Actions executed on change to FALSE

Logitech Craft Crown Triggers​

CategoryValueDescription
BTTActionCategoryCrownRotateLeftSmooth40Actions executed on rotate left (smooth)
BTTActionCategoryCrownRotateRightSmooth41Actions executed on rotate right (smooth)
BTTActionCategoryCrownRotateLeftRatchet42Actions executed on rotate left (ratchet)
BTTActionCategoryCrownRotateRightRatchet43Actions executed on rotate right (ratchet)
BTTActionCategoryStandard0Actions executed on crown tap
BTTActionCategoryCrownPressDown45Actions executed on crown press down
BTTActionCategoryCrownPressUp46Actions executed on crown press up

Default (All Other Trigger Types)​

Trigger types not listed above (Touch Bar, Notch Bar, generic devices, key sequences, drawings, etc.) use only:

CategoryValueDescription
BTTActionCategoryStandard0Actions executed on trigger

Using Action Categories in JSON​

When defining actions in JSON, set the BTTActionCategory field on the action to assign it to a specific category:

{
  "BTTPredefinedActionType": 3,
  "BTTActionCategory": 35
}

This example assigns a left-click action to the key release category (value 35) of a keyboard shortcut trigger, meaning the left click will be performed when the key is released rather than when it is pressed down.

This documentation covers all available BetterTouchTool actions as of the current version. Actions may be added or modified in future releases.