Skip to main content

BetterTouchTool CLI (bttcli) Documentation

Overview​

BetterTouchTool has a Unix socket server that lets external applications talk to BTT through the socket at /tmp/com.hegenberg.BetterTouchTool.sock. The bttcli tool is a command-line interface for this socket server.

You need to enable the Command Line / Socket Server support in the BetterTouchTool Scripting Settings first (Settings → Scripting BTT → Command Line → "Enable BTT Socket Server For Command Line Usage", then relaunch BTT).

bttcli is bundled with BetterTouchTool at /Applications/BetterTouchTool.app/Contents/SharedSupport/bin/bttcli. To add it to your path (assuming you use zsh):

echo 'export PATH="/Applications/BetterTouchTool.app/Contents/SharedSupport/bin:$PATH"' >> ~/.zprofile

Socket Server Details​

  • Socket Path: /tmp/com.hegenberg.BetterTouchTool.sock
  • Protocol: Unix domain socket
  • Security:
    • The socket server must be enabled in BTT's settings (Settings → Scripting BTT → Command Line; defaults key BTTSocketServerEnabled)
    • Optional shared secret authentication
    • Socket permissions are 0600 (only processes running as your user can connect)

alt text alt text

Usage Examples​

Using the bttcli tool:

# Get clipboard content
bttcli get_clipboard_content

# Set a variable
bttcli set_string_variable variableName=myVar to="Hello World"

# Get a variable
bttcli get_string_variable variableName=myVar

# Trigger a named trigger
bttcli trigger_named "MyTriggerName"

# Display a notification
bttcli display_notification "Hello from BTT" title="Notification Title"

# Check if an app is running
bttcli is_app_running "Safari"

# Update a Touch Bar widget
bttcli update_touch_bar_widget "widget-uuid-here" text="New Text"

# Get selected text
bttcli get_selection

# Set the clipboard to HTML content
bttcli set_clipboard_content "<b>Hello</b>" format=NSPasteboardTypeHTML

# Execute ChatGPT query
bttcli chat_gpt user="What is the weather like?" identifier="weather-conversation"

Command Format​

Commands are sent as HTTP-style requests to the socket server:

/<command_name>/?param1=value1&param2=value2

bttcli <command_name> key=value ... builds this request for you. An argument without = is sent as the unnamed ("") parameter, which most commands accept as their main value (e.g. the trigger name for trigger_named, the UUID for get_trigger or the variable name for the variable functions).

When a shared scripting secret is configured, pass it as the shared_secret parameter:

bttcli trigger_named "MyTriggerName" shared_secret=yourSecret

Supported Commands​

1. get_selection​

Retrieves the currently selected text or content.

  • Parameters:
    • type / content / format: Pasteboard type (default: NSPasteboardTypeString)
      • Supported types: NSPasteboardTypeString, NSPasteboardTypeTIFF, NSPasteboardTypePNG, NSPasteboardTypeRTF, NSPasteboardTypeRTFD, NSPasteboardTypeHTML, NSPasteboardTypeTabularText, NSPasteboardTypeFont, NSPasteboardTypeRuler, NSPasteboardTypeColor, NSPasteboardTypeSound, NSPasteboardTypeMultipleTextSelection, NSPasteboardTypeTextFinderOptions, NSPasteboardTypeURL, NSPasteboardTypeFileURL
    • asBase64 / asbase64: Return the content base64 encoded (boolean)

2. get_clipboard_content​

Gets the current clipboard content.

  • Parameters:
    • type / content / format: Pasteboard type (same as get_selection)
    • asBase64 / asbase64: Return the content base64 encoded (boolean)
    • excludeConcealed: Exclude concealed / sensitive items (returns an empty string instead).

3. set_clipboard_content​

Sets the clipboard content.

  • Parameters:
    • content / text: The content to set
    • format: The format/type to use

4. set_clipboard_contents​

Sets multiple clipboard content types at once.

  • Parameters:
    • contents: Array of content items
    • formats: Array of format types

Note: bttcli can only send text values, so these arrays can't be passed from the command line. Use set_clipboard_content there, or call set_clipboard_contents from JavaScript, AppleScript or the webserver (JSON body).

5. is_app_running​

Checks if an application is running.

  • Parameters:
    • app: App name or bundle identifier

6. display_notification​

Shows a system notification.

  • Parameters:
    • "" (unnamed): Notification body
    • title: Notification title
    • subTitle: Notification subtitle
    • soundName: Sound to play
    • imagePath: Path to notification image

7. get_dock_badge_for​

Gets the badge count for a Dock item.

  • Parameters:
    • app: App name
    • update_interval: How often to check (minimum 0.5 seconds)

8. get_active_touch_bar_group​

Returns the currently active Touch Bar group name.

  • Parameters: None

9. is_true_tone_enabled​

Checks if True Tone is enabled.

  • Parameters: None

10. get_location​

Gets the current location.

  • Parameters:
    • format: Output format (default: {LAT},{LON})

11. get_weather​

Gets weather information for a location.

  • Parameters:
    • location: Location coordinates or "auto" for the current location
    • unit: Temperature unit ("fahrenheit", otherwise defaults to celsius)

12. set_persistent_string_variable​

Sets a persistent string variable that survives BTT restarts.

  • Parameters:
    • variableName / variable_name: Variable name
    • to: Value to set

13. set_string_variable​

Sets a temporary string variable.

  • Parameters:
    • variableName / variable_name: Variable name
    • to: Value to set

14. set_persistent_number_variable​

Sets a persistent number variable.

  • Parameters:
    • variableName / variable_name: Variable name
    • to: Numeric value to set

15. set_number_variable​

Sets a temporary number variable.

  • Parameters:
    • variableName / variable_name: Variable name
    • to: Numeric value to set

Special variables:

  • BTTDisabled: Enable/disable BTT
  • BTTSiriRemoteMouseModeActive: Toggle Siri Remote mouse mode
  • SystemDoNotDisturbState: Toggle Do Not Disturb
  • BluetoothConnectionState-<address>: Connect/disconnect Bluetooth devices
  • CurrentDisplayBrightness: Set current display brightness
  • BuiltInDisplayBrightness: Set built-in display brightness
  • OutputVolume: Set output volume

16. get_number_variable​

Gets a number variable value.

  • Parameters:
    • variableName / variable_name: Variable name
    • default: Default value if the variable doesn't exist

Special variables:

  • BTTIdleTime: System idle time in seconds
  • BTTDisabled: BTT disabled state
  • SystemDoNotDisturbState: Do Not Disturb state
  • BluetoothConnectionState-<address>: Bluetooth device connection state
  • CurrentDisplayBrightness: Current display brightness
  • BuiltInDisplayBrightness: Built-in display brightness
  • ActiveSpace: Active Space ID
  • OutputVolume: Current output volume

17. get_string_variable​

Gets a string variable value.

  • Parameters:
    • variableName / variable_name: Variable name
    • default: Default value if the variable doesn't exist

Special variables:

  • BTTActiveWindowTitle: Current window title
  • BTTActiveWindowNumber: Current window number
  • BTTCurrentlyPlaying / BTTNowPlaying*: Now playing information
  • clipboard_content: Current clipboard content
  • hovered_link: Currently hovered link
  • selected_text: Currently selected text

18. reveal_element_in_ui​

Reveals an element in the BTT UI.

  • Parameters:
    • uuid: UUID of the element to reveal

19. paste_text​

Pastes text, either by simulating keyboard input or via a clipboard paste.

  • Parameters:
    • text / text_to_paste: Text to paste
    • format: Format type
    • insert_by_pasting: Use paste instead of typing (boolean)
    • move_cursor_left_by_x_after_pasting: Move cursor left after pasting

20. get_menu_item_value / get_floating_menu_item_value​

Gets the value of a menu item.

  • Parameters:
    • uuid: Item UUID
    • menu_name: Menu name (if not using the UUID)
    • item_name: Item name (if not using the UUID)
    • itemUUID / item_uuid: Alternative UUID parameter

21. set_menu_item_value​

Sets the value of a menu item.

  • Parameters:
    • uuid: Item UUID
    • menu_name: Menu name
    • item_name: Item name
    • value: Value to set

22. update_menu_item / update_floating_menu_item​

Updates a menu item with a JSON configuration.

  • Parameters:
    • uuid: Item UUID
    • menu_name: Menu name
    • item_name: Item name
    • json: JSON configuration
    • persist: Save changes permanently (boolean)

23. webview_menu_item_load_html_url_js​

Loads HTML/URL or executes JavaScript in a WebView menu item.

  • Parameters:
    • uuid: Item UUID
    • menu_name: Menu name
    • item_name: Item name
    • html_or_url: HTML content or URL to load
    • javascript_to_execute: JavaScript to execute
    • useragent: Custom user agent

24. trigger_action​

Triggers an action.

  • Parameters:
    • json: JSON configuration of the action to trigger

25. execute_assigned_actions_for_trigger​

Executes all actions assigned to a trigger.

  • Parameters:
    • uuid: Trigger UUID

26. trigger_named​

Triggers a named trigger and waits for completion.

  • Parameters:
    • trigger_name: Trigger name
    • cancel_delayed: Cancel any delayed execution (boolean)

27. trigger_named_async_without_response​

Triggers a named trigger without waiting for a response.

  • Parameters:
    • trigger_name: Trigger name
    • delay: Delay in seconds before triggering
    • cancel_delayed: Cancel any delayed execution (boolean)

28. cancel_delayed_named_trigger_execution​

Cancels a delayed named trigger execution.

  • Parameters:
    • trigger_name: Trigger name

29. run_shortcut​

Runs an Apple Shortcuts shortcut.

  • Parameters:
    • shortcut_name: Shortcut name
    • input / shortcut_input: Input to pass to the shortcut

30. chat_gpt​

Sends a request to ChatGPT.

  • Parameters:
    • identifier: Conversation identifier
    • input: Input text
    • user: User prompt
    • system: System prompt (default: helpful assistant)
    • maxHistory: Maximum conversation history
    • model: GPT model to use (default: gpt-4o-mini)
    • apiKey: Custom API key
    • customURL: Custom API URL

31. get_trigger​

Gets details for a specific trigger.

  • Parameters:
    • uuid: Trigger UUID

32. get_triggers​

Gets multiple triggers that match the given criteria.

  • Parameters:
    • trigger_uuid: Specific trigger UUID
    • trigger_type: Type of trigger
    • trigger_id: Trigger ID
    • return_only_if_modifiers_match: Only return if modifiers match (boolean)
    • trigger_parent_uuid: Parent trigger UUID
    • trigger_app_bundle_identifier: App bundle identifier
    • preset: Preset name

33. add_new_trigger​

Adds a new trigger.

  • Parameters:
    • json: JSON configuration of the trigger
    • parent_uuid: UUID of a group to add the trigger to (optional). Note: this one is parent_uuid, not trigger_parent_uuid

34. delete_trigger​

Deletes a trigger.

  • Parameters:
    • uuid: Trigger UUID

35. delete_triggers​

Deletes multiple triggers.

  • Parameters:
    • trigger_uuid: Specific trigger UUID
    • trigger_type: Type of trigger
    • trigger_id: Trigger ID
    • return_only_if_modifiers_match: Only if modifiers match
    • trigger_parent_uuid: Parent trigger UUID
    • trigger_app_bundle_identifier: App bundle identifier
    • preset: Preset name

36. update_trigger​

Updates a trigger's configuration.

  • Parameters:
    • uuid: Trigger UUID
    • trigger_parent_uuid: Parent UUID
    • json: JSON configuration

37. get_preset_details​

Gets details about a preset.

  • Parameters:
    • name: Preset name

38. import_preset​

Imports a preset from a file.

  • Parameters:
    • path: Path to preset file
    • replaceExisting: Replace it if it already exists (boolean, default: true)

39. export_preset​

Exports a preset to a file.

  • Parameters:
    • name: Preset name
    • compress: Compress output (boolean)
    • includeSettings: Include settings (boolean)
    • outputPath: Output file path
    • comment: Export comment
    • link: Associated link
    • minimumVersion: Minimum BTT version

40. refresh_widget​

Refreshes a Touch Bar widget.

  • Parameters:
    • uuid: Widget UUID

41. update_touch_bar_widget​

Updates a Touch Bar widget's content.

  • Parameters:
    • "" (unnamed): Widget UUID
    • Various widget-specific parameters in the args dictionary

42. update_stream_deck_widget​

Updates a Stream Deck widget's content.

  • Parameters:
    • "" (unnamed): Widget UUID
    • text: Text to display
    • json: JSON configuration

43. update_menubar_item​

Updates a menu bar item.

  • Parameters:
    • "" (unnamed): Item UUID
    • Various item-specific parameters in the args dictionary

44. get_menu_item_details​

Gets the detailed status of a menu item.

  • Parameters:
    • itemPath: Menu item path

45. get_menu_item_value_objc / get_floating_menu_item_value_objc​

Gets a menu item's value (Objective-C version, returns the raw value).

  • Parameters: Same as get_menu_item_value

46. get_variable_type​

Gets the type a variable currently holds, so callers can pick the right getter.

  • Parameters:
    • variableName / variable_name: Variable name
  • Returns: string, number, boolean, json or unset

Security Notes​

  1. The socket server must be explicitly enabled in BTT's settings
  2. An optional shared secret can be configured for authentication
  3. The import_preset command shows a security warning unless the user has opted to always allow imports
  4. External scripting must be enabled for non-webserver requests