BetterTouchTool

https://docs.folivora.ai/
Admin
BetterTouchTool is a macOS utility that allows users to customize input devices, automate tasks, and...
Tokens:336,954
Snippets:3,237
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Smooth Space Switch Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for starting smooth horizontal desktop transition with a specified speed.

```json
{

  "BTTPredefinedActionType": 575,  

  "BTTAdditionalActionData": {  

    "BTTSpaceSwitchSpeed": 1.5  

  }  

}
```

--------------------------------

### Start Smooth Zoom Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for starting smooth pinch zoom simulation with a specified magnification speed.

```json
{

  "BTTPredefinedActionType": 571,  

  "BTTAdditionalActionData": {  

    "BTTZoomSpeed": 2.0  

  }  

}
```

--------------------------------

### Start Smooth Scroll Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for starting smooth scrolling with vertical speed and duration parameters.

```json
{

  "BTTPredefinedActionType": 569,  

  "BTTAdditionalActionData": {  

    "BTTScrollModifierSpeedVertical": 5.0,  

    "BTTScrollModifierSpeedHorizontal": 0,  

    "BTTScrollModifierDuration": 0.5  

  }  

}
```

--------------------------------

### Start Dictation Configuration

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for starting speech recognition with a specific locale, output action, custom vocabulary, and text replacement rules.

```json
{

  "BTTPredefinedActionType": 576,

  "BTTSpeechRecognitionLocale": "en-US",

  "BTTSpeechRecognitionOutputAction": 1,

  "BTTSpeechRecognitionVocabulary": "Folivora\nBetterTouchTool\nHegenberg",

  "BTTSpeechRecognitionReplacements": "better touch tool => BetterTouchTool"

}
```

--------------------------------

### Start Smooth Rotate Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for starting smooth rotation gesture simulation with a specified speed in degrees per second.

```json
{

  "BTTPredefinedActionType": 573,  

  "BTTAdditionalActionData": {  

    "BTTRotateSpeed": 45.0  

  }  

}
```

--------------------------------

### Start Keyboard Input Blocking

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of starting the keyboard input blocking action.

```json
{

  "BTTPredefinedActionType": 429

}
```

--------------------------------

### Start Resizing Window Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for the Start Resizing action using BTTPredefinedActionType 71 and an automatic stop policy.

```json
{

  "BTTPredefinedActionType": 71,

  "BTTGenericActionConfig2": "stop:auto"

}
```

--------------------------------

### BTTPluginMetadata Example

Source: https://docs.folivora.ai/docs/plugins/json-action-plugins

Example configuration for the BTTPluginMetadata section.

```json
"BTTPluginMetadata": {  

  "BTTPluginName": "My Custom Action",  

  "BTTPluginIdentifier": "com.example.myCustomAction",  

  "BTTPluginDescription": "Does something useful",  

  "BTTPluginIcon": "bolt.fill",  

  "BTTPluginVersion": "1.0"  

}
```

--------------------------------

### Complete example CSV file

Source: https://docs.folivora.ai/docs/keyboard-shortcuts/key-sequence-snippet-import

A comprehensive example showing configuration comments, plain text expansions, and JavaScript snippet definitions.

```text

# Optional: set the pause between keys (default 0.3s)  

#BTTBetweenTime: 0.4  

  

# Text expansions  

addr;123 Main Street, Springfield  

sig;Best regards, John  

brb;Be right back!  

  

# JavaScript snippets  

date;JSPASTE:async () => { return new Date().toLocaleDateString(); }  

hello;JSPASTE:async () => { return "Hello World!"; }  

uuid;JSPASTE:async () => { return crypto.randomUUID(); }  


```

--------------------------------

### Example AutoHotkey File

Source: https://docs.folivora.ai/docs/keyboard-shortcuts/key-sequence-snippet-import

A practical example file containing common abbreviations, email shortcuts, and a multi-line template for use with BetterTouchTool.

```autohotkey
; Common abbreviations  
::btw::by the way  
::omw::On my way!  
::thx::Thank you very much!  
  
  
; Email shortcuts (immediate trigger)  
:*:myemail::andreas@example.com  
:*:sig::Best regards, Andreas  
  
  
; Don't backspace the trigger  
:B0:@@::andreas@example.com  
  
  
; Multi-line template  
::letter::  
(  
Dear Sir or Madam,  
  
Thank you for your inquiry.  
  
Best regards,  
Andreas  
)  

```

--------------------------------

### Window Switcher Configuration Example

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example JSON configuration for the Window Switcher action, setting dimensions, appearance, sorting, and interaction behaviors.

```json
{

  "BTTPredefinedActionType": 99,

  "BTTAdditionalActionData": {

    "BTTWindowSwitcherWidth": 800,

    "BTTWindowSwitcherHeight": 600,

    "BTTWindowSwitcherAppearance": 2,

    "BTTWindowSwitcherSort": 0,

    "BTTWindowSwitcherSelectNextOnRepeat": true,

    "BTTWindowSwitcherTriggerOnRelease": true,

    "BTTWindowSwitcherShowPopover": 4,

    "BTTWindowSwitcherInitialFocus": 1

  }

}
```

--------------------------------

### Start Screen Saver

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts the configured screen saver.

```APIDOC
## Start Screen Saver

### Description
Starts the configured screen saver.

### Parameters
- **BTTPredefinedActionType** (integer) - Required - 202

### Request Example
{
  "BTTPredefinedActionType": 202
}
```

--------------------------------

### Install bettertouchtool package

Source: https://docs.folivora.ai/docs/scripting/node-js-library

Use npm to install the official BetterTouchTool client library.

```bash
npm install bettertouchtool
```

--------------------------------

### MCP Server Configuration Example

Source: https://docs.folivora.ai/docs/ai-assistants/mcp

Example JSON configuration for an MCP server using the shell command via uvx.

```json
{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": ["mcp-shell-server"],
      "env": {
        "ALLOW_COMMANDS": "say,ls,cat,pwd,grep,wc,find"
      }
    }
  }
}
```

--------------------------------

### Arrange Windows Side by Side Example

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example JSON configuration for the Arrange Windows Side by Side action using the Two Windows predefined action type.

```json
{

  "BTTPredefinedActionType": 317

}
```

--------------------------------

### Install yt-dlp and ffmpeg dependencies

Source: https://docs.folivora.ai/docs/other-triggers/text-selection-widgets

Prerequisite commands to install the necessary tools for the 'Download YouTube Video' widget using Homebrew.

```bash
brew install yt-dlp  

brew install ffmpeg  
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://docs.folivora.ai/docs/plugins/swift-source-plugins

Prerequisite command to install the necessary tools for compiling Swift plugins.

```bash
xcode-select --install
```

--------------------------------

### logitech_start()

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Starts the Logitech device manager and begins device discovery.

```APIDOC
## logitech_start()

### Description
Starts the Logitech device manager and begins device discovery. All functions support async/await and return Promises.

### Returns
- **success** (boolean) - Indicates if the operation was successful.
- **started** (boolean) - Present if the manager was started.
- **alreadyRunning** (boolean) - Present if the manager was already running.
```

--------------------------------

### logitech_start()

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Starts the Logitech device manager and begins device discovery.

```javascript
const result = await logitech_start();  

// Returns: { success: true, started: true }  

// Or if already running: { success: true, alreadyRunning: true }  
```

--------------------------------

### Start Siri

Source: https://docs.folivora.ai/docs/actions/action-definitions

Activates Siri.

```APIDOC
## Start Siri

### Description
Activates Siri.

### Parameters
- **BTTPredefinedActionType** (integer) - Required - 173

### Request Example
{
  "BTTPredefinedActionType": 173
}
```

--------------------------------

### Open Launcher Group

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of configuring the Launcher to open a specific top-level group immediately.

```json
{
  "BTTPredefinedActionType": 594,
  "BTTAdditionalActionData": {
    "BTTActionLauncherInitialRoute": {
      "BTTLauncherRouteType": "group",
      "BTTLauncherRouteID": "Apps",
      "BTTLauncherRouteTitle": "Apps"
    }
  }
}
```

--------------------------------

### Start Screen Saver Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts the configured screen saver using BTTPredefinedActionType 202.

```json
{

  "BTTPredefinedActionType": 202

}
```

--------------------------------

### Press Context Menu Key

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of simulating the context menu key press.

```json
{

  "BTTPredefinedActionType": 532

}
```

--------------------------------

### Notch Bar Button Configuration Example

Source: https://docs.folivora.ai/docs/json/trigger-definitions

A JSON configuration example for a Notch Bar button, including color, font settings, SF symbol icon, and visibility properties.

```json
{

  "BTTTriggerType": 696,

  "BTTTriggerClass": "BTTTriggerTypeNotchBar",

  "BTTTouchBarButtonName": "My Button",

  "BTTTriggerConfig": {

    "BTTTouchBarButtonColor": "75.323769, 75.323769, 75.323769, 255.000000",

    "BTTTouchBarFontColor": "255, 255, 255, 255",

    "BTTTouchBarFontSize": 15,

    "BTTTouchBarItemSFSymbolDefaultIcon": "star.fill",

    "BTTTouchBarItemIconWidth": 22,

    "BTTTouchBarItemIconHeight": 22,

    "BTTNotchBarVisibilityNotchScreen": 0,

    "BTTNotchBarVisibilityStandardScreen": 0

  },

  "BTTActionsToExecute": [{

    "BTTPredefinedActionType": 45

  }]

}
```

--------------------------------

### GET /get_info/

Source: https://docs.folivora.ai/docs/scripting/webserver

Retrieve server information including version, build, and a list of available functions.

```APIDOC
## GET /get_info/

### Description
Returns version, build, and the list of available functions for feature detection.

### Method
GET

### Endpoint
http://127.0.0.1:12345/get_info/

### Response
#### Success Response (200)
- **version** (string) - The BTT version.
- **build** (string) - The BTT build number.
- **functions** (array) - List of available function names.
```

--------------------------------

### logitech_quick_setup(options)

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Configures multiple device settings in a single call. Only provided settings will be changed.

```APIDOC
## logitech_quick_setup(options)

### Description
Configures multiple device settings in a single call. Only provided settings will be changed.

### Parameters
- **deviceName** (string) - Required - Name of the device
- **dpi** (number) - Optional - DPI value to set
- **reportRate** (number) - Optional - Report rate in Hz
- **ledColor** (array) - Optional - RGB array [red, green, blue]
- **enableHostMode** (boolean) - Optional - Enable host control mode
- **remapButtonsToMouseButtons** (boolean) - Optional - Remap special buttons to standard mouse buttons
- **ratchet** (boolean) - Optional - Scroll wheel mode (true=ratchet, false=freespin)
- **autoDisengage** (number) - Optional - SmartShift auto-disengage threshold (0-50)
- **torque** (number) - Optional - SmartShift torque (1-100, Enhanced SmartShift only)
- **hiResScrollEnabled** (boolean) - Optional - Enable high-resolution scrolling
- **invertMainWheel** (boolean) - Optional - Invert main scroll wheel
- **invertThumbWheel** (boolean) - Optional - Invert thumb wheel

### Request Example
const result = await logitech_quick_setup({ deviceName: "G502 HERO", dpi: 1600, reportRate: 1000, ledColor: [0, 128, 255], enableHostMode: true, remapButtonsToMouseButtons: true });
```

--------------------------------

### GET /get_info/

Source: https://docs.folivora.ai/docs/scripting/webserver

Retrieves version, build, and available functions information.

```APIDOC
## GET /get_info/

### Description
Retrieves version, build, and available functions information.

### Method
GET

### Endpoint
/get_info/
```

--------------------------------

### Using the Btt client

Source: https://docs.folivora.ai/docs/scripting/node-js-library

Demonstrates initializing the Btt client, executing scripting functions, triggering actions, chaining commands, and creating triggers programmatically.

```javascript
import { Btt, actions, triggers } from "bettertouchtool";  

  

const btt = Btt.http({ port: 64472, sharedSecret: "my-secret" });   // or Btt.socket()  

  

// scripting functions as typed methods  

await btt.triggerNamed("My Named Trigger");  

const app = await btt.getStringVariable("BTTActiveAppBundleIdentifier");  

await btt.vars.set("my_counter", 5, { persistent: true });  

const clip = await btt.getClipboardContent();  

  

// run any predefined action  

await btt.triggerAction(actions.showHUD("Hello", { detail: app, duration: 2 }));  

await btt.triggerAction(actions.sendShortcut("cmd+shift+4"));  

  

// several actions in one round trip  

await btt.chain().launchApp("com.apple.Safari").delay(0.5).sendShortcut("cmd+t").pasteText("folivora.ai").run();  

  

// create triggers from code  

const handle = await btt.addNewTrigger(  

  triggers.keyboardShortcut("cmd+shift+k", [actions.showHUD("⌘⇧K pressed")], { description: "created from Node" }),  

);  

await handle.invoke();  

await handle.delete();  

  

// anything else: raw scripting call (parameter names as documented in this section)  

await btt.call("update_menu_item", { item_uuid: "…", json: { BTTMenuItemText: "hi" } });
```

--------------------------------

### Pairing workflow example

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Demonstrates a complete workflow for initiating pairing mode with a specified timeout.

```javascript
async function startPairing() {  

    log("Starting pairing mode for 60 seconds...");  

    log("Turn on your Logitech device now.");  

  

    const result = await logitech_start_pairing({ timeout: 60 });  

  

    if (result.error) {  

        return `Pairing failed: ${result.error}`;

    }  

  

    return "Pairing mode active. Turn on your device.";  

}  
```

--------------------------------

### Open Clipboard Surface Launcher

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of configuring the Launcher to open the clipboard surface immediately.

```json
{
  "BTTPredefinedActionType": 594,
  "BTTAdditionalActionData": {
    "BTTActionLauncherInitialRoute": {
      "BTTLauncherRouteType": "surface",
      "BTTLauncherRouteID": "surface:clipboard",
      "BTTLauncherSurfaceKind": "clipboard",
      "BTTLauncherRouteTitle": "Clipboard"
    }
  }
}
```

--------------------------------

### Simulate Page Up Key

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of simulating the Page Up key press.

```json
{

  "BTTPredefinedActionType": 60

}
```

--------------------------------

### Act as Hyper Key

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of configuring a key to act as a Hyper Key.

```json
{

  "BTTPredefinedActionType": 293,

  "BTTAdditionalActionData": {

    "BTTActionHyperkeyExcludeShift": false

  }

}
```

--------------------------------

### Start Scroll Blocking Action Configuration

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for BTTPredefinedActionType 381, used to start blocking scroll events specifically on touch devices.

```json
{

  "BTTPredefinedActionType": 381,

  "BTTAdditionalActionData": {

    "BTTActionBlockScrollingOnlyOnTouchDevices": true

  }

}
```

--------------------------------

### Get Hovered URL

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of retrieving the URL under the mouse cursor and storing it in a variable.

```json
{

  "BTTPredefinedActionType": 526,

  "BTTVariableName": "hoveredURL"

}
```

--------------------------------

### List all connected devices

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Example function to iterate through connected devices and log their details.

```javascript
async function listDevices() {  

    const result = await logitech_get_devices();  

  

    for (const device of result.devices) {  

        log(`Device: ${device.name}`);  

        log(`  Protocol: HID++ ${device.protocolVersion}`);  

        log(`  DPI Support: ${device.features.supportsDPI}`);  

        log(`  LED Support: ${device.features.supportsLED}`);  

    }  

  

    return `Found ${result.count} device(s)`;  

}  
```

--------------------------------

### GET /get_triggers/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets multiple triggers.

```APIDOC
## GET /get_triggers/

### Description
Gets multiple triggers.

### Method
GET

### Endpoint
/get_triggers/
```

--------------------------------

### GET /get_trigger/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets trigger information.

```APIDOC
## GET /get_trigger/

### Description
Gets trigger information.

### Method
GET

### Endpoint
/get_trigger/
```

--------------------------------

### Simulate Page Forward Key

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example of simulating the Page Forward key press.

```json
{

  "BTTPredefinedActionType": 51

}
```

--------------------------------

### GET /get_weather/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets weather information.

```APIDOC
## GET /get_weather/

### Description
Gets weather information.

### Method
GET

### Endpoint
/get_weather/
```

--------------------------------

### GET /get_location/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets location information.

```APIDOC
## GET /get_location/

### Description
Gets location information.

### Method
GET

### Endpoint
/get_location/
```

--------------------------------

### GET /get_menu_item_value/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets menu item value.

```APIDOC
## GET /get_menu_item_value/

### Description
Gets menu item value.

### Method
GET

### Endpoint
/get_menu_item_value/
```

--------------------------------

### Create a BTTLauncherPluginResult instance

Source: https://docs.folivora.ai/docs/plugins/launcher

Initializes a top-level creator item to open a launcher-hosted surface.

```swift
let result = BTTLauncherPluginResult()  

result.itemIdentifier = "create-quick-link"  

result.title = "Create Quick Link"  

result.systemImageName = "link.badge.plus"  

result.surfaceIdentifier = "create-quick-link-surface"  
```

--------------------------------

### Cycle through DPI presets

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Example function to cycle through a predefined list of DPI values.

```javascript
async function cycleDPI() {  

    const deviceName = "G502 HERO";  

    const presets = [800, 1600, 3200, 6400];  

  

    const current = await logitech_get_dpi({ deviceName });  

    if (current.error) return `Error: ${current.error}`;  

  

    // Find next preset  

    let nextIndex = 0;  

    for (let i = 0; i < presets.length; i++) {  

        if (current.dpi < presets[i]) {  

            nextIndex = i;  

            break;  

        }  

        if (i === presets.length - 1) {  

            nextIndex = 0; // Wrap around  

        }  

    }  

  

    const result = await logitech_set_dpi({ deviceName, dpi: presets[nextIndex] });  

    return `DPI set to ${result.actualDPI}`;  

}  
```

--------------------------------

### Function Key F11 Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for simulating the F11 function key.

```json
{

  "BTTPredefinedActionType": 43

}
```

--------------------------------

### GET /get_dock_badge_for/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets dock badge information.

```APIDOC
## GET /get_dock_badge_for/

### Description
Gets dock badge information.

### Method
GET

### Endpoint
/get_dock_badge_for/
```

--------------------------------

### logitech_quick_setup complete mouse setup

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Demonstrates a complete configuration for an MX Master 3, including scroll wheel and SmartShift settings.

```javascript
async function setupMouse() {  

    const result = await logitech_quick_setup({  

        deviceName: "MX Master 3",  

        dpi: 1600,  

        enableHostMode: true,  

        ratchet: false,          // Freespin mode  

        autoDisengage: 10,  

        hiResScrollEnabled: true,  

        invertThumbWheel: true  

    });  

  

    return result.success ? "Mouse configured!" : `Error: ${result.error}`;  

}  
```

--------------------------------

### GET /get_menu_item_details/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets detailed information about a menu item.

```APIDOC
## GET /get_menu_item_details/

### Description
Gets detailed information about a menu item.

### Method
GET

### Endpoint
/get_menu_item_details/
```

--------------------------------

### GET /get_floating_menu_item_value/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets floating menu item value.

```APIDOC
## GET /get_floating_menu_item_value/

### Description
Gets floating menu item value.

### Method
GET

### Endpoint
/get_floating_menu_item_value/
```

--------------------------------

### Start Repeat

Source: https://docs.folivora.ai/docs/actions/action-definitions

Marks the start of a for loop or repeat block.

```APIDOC
## Start Repeat

### Description
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** (number) - Required - 329
- **BTTGenericActionConfig** (string) - Required - The name of the for loop.
- **BTTAdditionalActionData** (object) - Required - Contains `BTTActionForLoopRepeat` (number) and optionally `BTTActionForLoopRepeatVariable` (string).

### Request Example
{
  "BTTPredefinedActionType": 329,
  "BTTAdditionalActionData": {
    "BTTActionForLoopRepeat": 99
  },
  "BTTGenericActionConfig": "nameOfTheLoop"
}
```

--------------------------------

### Get Hovered Link/URL

Source: https://docs.folivora.ai/docs/actions/action-definitions

Gets link or URL under mouse cursor.

```APIDOC
## Get Hovered Link/URL

### Description
Gets link or URL under mouse cursor and stores it in a variable.

### Parameters
- **BTTPredefinedActionType** (integer) - Required - 524 (Get Link) or 526 (Get URL).
- **BTTVariableName** (string) - Required - Variable to store result.

### Request Example
{
  "BTTPredefinedActionType": 526,
  "BTTVariableName": "hoveredURL"
}
```

--------------------------------

### GET /get_active_touch_bar_group/

Source: https://docs.folivora.ai/docs/scripting/webserver

Gets the currently active touch bar group.

```APIDOC
## GET /get_active_touch_bar_group/

### Description
Gets the currently active touch bar group.

### Method
GET

### Endpoint
/get_active_touch_bar_group/
```

--------------------------------

### get_items_from_clipboard_manager output example

Source: https://docs.folivora.ai/docs/scripting/java-script

Example JSON structure returned by the get_items_from_clipboard_manager function.

```json
{

  "items" : [  

  

    {

      "meta" : {

        "copiedFrom" : "com.sublimetext.4",

        "uuid" : "1B1F7F7D-EF28-4B45-9AF1-248768BFCB8C",

        "previewText" : "Test5",

        "date" : "2025-10-01T13:25:09Z"

      },

      "content" : "Test5"

    },

    {

      "meta" : {

        "copiedFrom" : "com.sublimetext.4",

        "uuid" : "10C6C74F-8373-4810-909E-544318EC4ED7",

        "previewText" : "Test4",

        "date" : "2025-10-01T13:25:08Z"

      },

      "content" : "Test4"

    },

    {

      "meta" : {

        "copiedFrom" : "com.sublimetext.4",

        "uuid" : "D8956BBC-7699-43D7-BF22-3E648B05D631",

        "previewText" : "Test3",

        "date" : "2025-10-01T13:25:08Z"

      },

      "content" : "Test3"

    },

    {

      "meta" : {

        "copiedFrom" : "com.sublimetext.4",

        "uuid" : "A9880066-4438-4CD2-A103-FB7E3CAD47FC",

        "previewText" : "Test2",

        "date" : "2025-10-01T13:25:07Z"

      },

      "content" : "Test2"

    },

    {

      "meta" : {

        "copiedFrom" : "com.sublimetext.4",

        "uuid" : "0BD5D9D6-B76D-4E91-99E9-5B59F9067C44",

        "previewText" : "Test1",

        "date" : "2025-10-01T13:25:07Z"

      },

      "content" : "Test1"

    }

  ],

  "latest" : "2025-10-01T13:25:14Z"

}
```

--------------------------------

### Example Incoming OSC Message

Source: https://docs.folivora.ai/docs/scripting/osc

An example of an OSC message path and its argument.

```text
/track/1/volume 0.75
```

--------------------------------

### POST /run_shortcut/

Source: https://docs.folivora.ai/docs/scripting/webserver

Runs a shortcut.

```APIDOC
## POST /run_shortcut/

### Description
Runs a shortcut.

### Method
POST

### Endpoint
/run_shortcut/
```

--------------------------------

### BTTPluginActions Example

Source: https://docs.folivora.ai/docs/plugins/json-action-plugins

Example of the BTTPluginActions array using placeholders for dynamic values.

```json
"BTTPluginActions": [  

  {  

    "BTTIsPureAction": true,  

    "BTTPredefinedActionType": 254,  

    "BTTAdditionalActionData": {  

      "BTTActionHUDTitle": "@@@hudTitle@@@",  

      "BTTActionHUDDuration": "@@@duration@@@"  

    }  

  }  

]
```

--------------------------------

### Espanso YAML Match File Example

Source: https://docs.folivora.ai/docs/keyboard-shortcuts/key-sequence-snippet-import

A sample Espanso configuration file demonstrating triggers, variables, shell commands, clipboard usage, and form fields.

```yaml
matches:  

  # Simple replacement  

  - trigger: ":addr"  

    replace: "123 Main Street, Springfield"  

  

  # Date variable  

  - trigger: ":now"  

    replace: "It's {{mytime}}"  

    vars:  

      - name: mytime  

        type: date  

        params:  

          format: "%H:%M"  

  

  # Shell command  

  - trigger: ":ip"  

    replace: "{{output}}"  

    vars:  

      - name: output  

        type: shell  

        params:  

          cmd: "curl -s 'https://api.ipify.org'"  

  

  # Clipboard + cursor positioning  

  - trigger: ":clink"  

    replace: "<a href='{{clipb}}'>$|$</a>"  

    vars:  

      - name: clipb  

        type: clipboard  

  

  # Case propagation  

  - trigger: ":btw"  

    replace: "by the way"  

    propagate_case: true  

  

  # Random choice  

  - trigger: ":quote"  

    replace: "{{output}}"  

    vars:  

      - name: output  

        type: random  

        params:  

          choices:  

            - "Every moment is a fresh beginning."  

            - "Whatever you do, do it well."  

  

  # Simple form  

  - trigger: ":meeting"  

    form: |  

      Meeting with [[person]] on [[date]] about [[topic]]  


```

--------------------------------

### Codex Controller - Start Task

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts a new Codex task using the provided prompt and configuration.

```APIDOC
## Codex Controller - Start Task

### Description
Starts a new Codex task. With a prompt, BTT opens Codex's native new-task composer and submits it. Without a prompt, the action only opens the composer.

### Parameters
- **BTTPredefinedActionType** (integer) - Required - 605
- **BTTAdditionalActionData** (object) - Required
  - **BTTActionCodexPrompt** (string) - Optional - The initial task / prompt.
  - **BTTActionCodexWorkingDirectory** (string) - Required - Working directory for the task.
  - **BTTActionCodexThreadName** (string) - Optional - Task name.
  - **BTTActionCodexResultVariable** (string) - Optional - Variable to store the JSON result in.

### Request Example
{
  "BTTPredefinedActionType": 605,
  "BTTAdditionalActionData": {
    "BTTActionCodexPrompt": "Fix the failing unit tests",
    "BTTActionCodexWorkingDirectory": "/Users/me/Projects/MyApp",
    "BTTActionCodexThreadName": "Test fixes",
    "BTTActionCodexResultVariable": "BTTLastCodexControllerResult"
  }
}
```

--------------------------------

### Start / Stop Smooth Rotate

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts or stops continuous smooth rotation, simulating rotation gestures.

```APIDOC
## Start / Stop Smooth Rotate

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

### Parameters
- **BTTPredefinedActionType** (number) - Required - 573 (Start), 574 (Stop)
- **BTTAdditionalActionData** (object) - Optional - Configuration object for rotation behavior.

### Request Example
{
  "BTTPredefinedActionType": 573,
  "BTTAdditionalActionData": {
    "BTTRotateSpeed": 45.0
  }
}
```

--------------------------------

### Start / Stop Smooth Scroll

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts or stops continuous smooth scrolling, simulating touchpad-like behavior.

```APIDOC
## Start / Stop Smooth Scroll

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

### Parameters
- **BTTPredefinedActionType** (number) - Required - 569 (Start), 570 (Stop)
- **BTTAdditionalActionData** (object) - Optional - Configuration object for scroll behavior.

### Request Example
{
  "BTTPredefinedActionType": 569,
  "BTTAdditionalActionData": {
    "BTTScrollModifierSpeedVertical": 5.0,
    "BTTScrollModifierSpeedHorizontal": 0,
    "BTTScrollModifierDuration": 0.5
  }
}
```

--------------------------------

### Implement Configuration Forms

Source: https://docs.folivora.ai/docs/plugins/swift-source-plugins

Shows how to define configuration form items and handle incoming configuration values. Note that BTT automatically applies a 'plugin_var_' prefix to field IDs.

```swift
static func configurationFormItems() -> BTTPluginFormItem? {  

    let group = BTTPluginFormItem()  

    group.formFieldType = BTTFormTypeFormGroup  

  

    let textField = BTTPluginFormItem()  

    textField.formFieldType = BTTFormTypeTextField  

    textField.formLabel1 = "Label Text"  

    textField.formFieldID = "labelText"  

    textField.defaultValue = "Hello!"  

  

    group.formOptions = [textField]  

    return group  

}  

  

func didReceiveNewConfigurationValues(_ configurationValues: [String: Any]?) {  

    // Values arrive with a "plugin_var_" prefix on the formFieldID  

    if let text = configurationValues?["plugin_var_labelText"] as? String {  

        labelText = text  

    }  

}
```

--------------------------------

### Start / Stop Smooth Zoom

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts or stops continuous smooth zooming, simulating pinch zoom gestures.

```APIDOC
## Start / Stop Smooth Zoom

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

### Parameters
- **BTTPredefinedActionType** (number) - Required - 571 (Start), 572 (Stop)
- **BTTAdditionalActionData** (object) - Optional - Configuration object for zoom behavior.

### Request Example
{
  "BTTPredefinedActionType": 571,
  "BTTAdditionalActionData": {
    "BTTZoomSpeed": 2.0
  }
}
```

--------------------------------

### Start Drag By Double-Click Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts a mouse drag operation initiated by a double-click using BTTPredefinedActionType 296.

```json
{

  "BTTPredefinedActionType": 296  

}
```

--------------------------------

### Supported AutoHotkey Syntax Examples

Source: https://docs.folivora.ai/docs/keyboard-shortcuts/key-sequence-snippet-import

Demonstrates various AHK hotstring configurations including immediate triggers, case sensitivity, escape sequences, and multi-line continuation sections.

```autohotkey
; Comments start with semicolons  
  
  
; Basic hotstring: typing "btw" + ending char → "by the way"  
::btw::by the way  
  
  
; Immediate trigger (* = no ending character needed)  
:*:addr::123 Main Street  
  
  
; Don't delete the abbreviation (B0)  
:B0:@@::andreas@example.com  
  
  
; Combined options  
:*B0:!!::ALERT  
  
  
; AHK escape sequences: `n = newline, `t = tab, `s = space  
::nl::Line one`nLine two  
  
  
; Multi-line with continuation section  
::letter::  
(  
Dear Sir or Madam,  
  
Thank you for your inquiry.  
  
Best regards  
)  
  
  
; Case-sensitive (C option)  
:C:AFK::Away From Keyboard  
  
  
; Global default change  
#Hotstring B0  

```

--------------------------------

### logitech_quick_setup basic usage

Source: https://docs.folivora.ai/docs/normal-mouse/logitech-javascript

Configures multiple device settings for a G502 HERO mouse in a single call.

```javascript
const result = await logitech_quick_setup({  

    deviceName: "G502 HERO",  

    dpi: 1600,  

    reportRate: 1000,  

    ledColor: [0, 128, 255],  

    enableHostMode: true,  

    remapButtonsToMouseButtons: true  

});  

// Returns: { success: true }  
```

--------------------------------

### Start / Stop Smooth Space Switch

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts or stops smooth space switching animation for horizontal desktop transitions.

```APIDOC
## Start / Stop Smooth Space Switch

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

### Parameters
- **BTTPredefinedActionType** (number) - Required - 575 (Start), 578 (Stop)
- **BTTAdditionalActionData** (object) - Optional - Configuration object for space switching behavior.

### Request Example
{
  "BTTPredefinedActionType": 575,
  "BTTAdditionalActionData": {
    "BTTSpaceSwitchSpeed": 1.5
  }
}
```

--------------------------------

### Initial AI Assistant Request

Source: https://docs.folivora.ai/docs/ai-assistants/getting-started

A simple example request to test the assistant's functionality after initial configuration.

```text
Create a keyboard shortcut that shows a HUD saying "Hello".
```

--------------------------------

### Save Focused Window Size and Position Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration to save the size and position of the currently focused window.

```json
{

  "BTTPredefinedActionType": 539

}
```

--------------------------------

### Complete Touch Bar plugin example

Source: https://docs.folivora.ai/docs/plugins/touch-bar

A full implementation of a Touch Bar widget that displays a configurable label and handles configuration updates.

```swift
// BTT-Plugin-Name: Custom Label  
// BTT-Plugin-Type: TouchBar  
// BTT-Plugin-Icon: textformat  

  

import Cocoa  

  

class CustomLabel: NSObject, BTTPluginInterface {  

    weak var delegate: (any BTTTouchBarPluginDelegate)?  

    private var labelText = "Hello"  

  

    static func configurationFormItems() -> BTTPluginFormItem? {  

        let group = BTTPluginFormItem()  

        group.formFieldType = BTTFormTypeFormGroup  

  

        let title = BTTPluginFormItem()  

        title.formFieldType = BTTFormTypeTitleField  

        title.formLabel1 = "Custom Label Settings"  

  

        let textField = BTTPluginFormItem()  

        textField.formFieldType = BTTFormTypeTextField  

        textField.formLabel1 = "Label Text"  

        textField.formFieldID = "labelText"  

        textField.defaultValue = "Hello"  

  

        group.formOptions = [title, textField]  

        return group  

    }  

  

    func didReceiveNewConfigurationValues(_ configurationValues: [String: Any]) {  

        if let text = configurationValues["plugin_var_labelText"] as? String {  

            labelText = text  

        }  

    }  

  

    func touchBarTitleString() -> String? {  

        return labelText  

    }  

}  
```

--------------------------------

### loadLauncherResults(for:completion:)

Source: https://docs.folivora.ai/docs/plugins/launcher

Asynchronously fetches search results for a given query to keep the plugin responsive.

```APIDOC
## func loadLauncherResults(for:completion:)

### Description
Provides an asynchronous way to return search results. The completion handler must be called exactly once.

### Parameters
- **context** (BTTLauncherPluginContext) - The current launcher context containing the query.
- **completion** (@escaping ([BTTLauncherPluginResult]?) -> Void) - The handler to return results. Return nil or an empty array if no results are found.
```

--------------------------------

### BTTTriggerLauncherConfig JSON Example

Source: https://docs.folivora.ai/docs/json/trigger-definitions

A sample JSON configuration for a trigger including the BTTTriggerLauncherConfig object to define its launcher appearance and associated actions.

```json
{

  "BTTTriggerType": 643,

  "BTTTriggerClass": "BTTTriggerTypeOtherTriggers",

  "BTTTriggerName": "quick_note",

  "BTTTriggerLauncherConfig": {

    "BTTLauncherShowInLauncher": 1,

    "BTTLauncherTitle": "Quick Note",

    "BTTLauncherDetails": "Create a new note",

    "BTTLauncherOrder": -500

  },

  "BTTActionsToExecute": [{

    "BTTPredefinedActionType": 49

  }]

}
```

--------------------------------

### Archive the Plugin

Source: https://docs.folivora.ai/docs/plugins/xcode-bundle-distribution

Build and archive your plugin scheme to prepare it for signing and notarization.

```bash
xcodebuild archive \
  -scheme YourPluginScheme \
  -configuration Release \
  -archivePath ./build/yourplugin.xcarchive
cd build/yourplugin.xcarchive/Products/Library/Bundles/
```

--------------------------------

### Start Dictation / Speech Recognition

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts the speech recognition process using macOS native capabilities with configurable output and recognition settings.

```APIDOC
## Start Dictation / Speech Recognition

### Description
Starts recognizing and transcribing speech using macOS speech recognition. Requires macOS 26+ and microphone permission.

### Parameters
- **BTTPredefinedActionType** (integer) - Required - Must be 576.
- **BTTSpeechRecognitionLocale** (string) - Optional - Recognition language (e.g., "en-US").
- **BTTSpeechRecognitionOutputAction** (integer) - Optional - Output behavior: 0=nothing, 1=paste, 2=copy, 3=set variable, 4=type, 5=paste & copy.
- **BTTSpeechRecognitionVariableName** (string) - Optional - Variable name for output action 3.
- **BTTSpeechRecognitionPersistVariable** (boolean) - Optional - Keep variable across restarts.
- **BTTSpeechRecognitionVocabulary** (string) - Optional - Custom words/names to bias recognition.
- **BTTSpeechRecognitionReplacements** (string) - Optional - Spelling corrections in 'recognized => corrected' format.
- **BTTSpeechRecognitionShowWindow** (boolean) - Optional - Show recording window.
- **BTTSpeechRecognitionLiveTranscription** (boolean) - Optional - Show text while speaking.
- **BTTSpeechRecognitionMaxDuration** (integer) - Optional - Max recording length in seconds.
- **BTTSpeechRecognitionSilenceTimeout** (integer) - Optional - Stop after silence duration.
- **BTTSpeechRecognitionStopOnModifierRelease** (boolean) - Optional - Stop on modifier key release.
- **BTTSpeechRecognitionPlayStartSound** (boolean) - Optional - Play sound on start.
- **BTTSpeechRecognitionPlayStopSound** (boolean) - Optional - Play sound on stop.
- **BTTSpeechRecognitionInputDevice** (string) - Optional - UID of audio input device.

### Request Example
{
  "BTTPredefinedActionType": 576,
  "BTTSpeechRecognitionLocale": "en-US",
  "BTTSpeechRecognitionOutputAction": 1,
  "BTTSpeechRecognitionVocabulary": "Folivora\nBetterTouchTool\nHegenberg",
  "BTTSpeechRecognitionReplacements": "better touch tool => BetterTouchTool"
}
```

--------------------------------

### Launch Application Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Launches a specific application using its path or bundle identifier.

```json
{

  "BTTPredefinedActionType": 49,

  "BTTLaunchPath": "/Applications/Safari.app"

}
```

--------------------------------

### Tile Window to Left Half Action

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration to tile the focused window to the left half of the screen using the native macOS tiling engine.

```json
{

  "BTTPredefinedActionType": 627

}
```

--------------------------------

### Codex Controller - Start Task (Type 605)

Source: https://docs.folivora.ai/docs/actions/action-definitions

Starts a new Codex task using the specified prompt and working directory. The task uses current desktop composer defaults.

```json
{

  "BTTPredefinedActionType": 605,

  "BTTAdditionalActionData": {

    "BTTActionCodexPrompt": "Fix the failing unit tests",

    "BTTActionCodexWorkingDirectory": "/Users/me/Projects/MyApp",

    "BTTActionCodexThreadName": "Test fixes",

    "BTTActionCodexResultVariable": "BTTLastCodexControllerResult"

  }

}
```

--------------------------------

### Using subgroup prompt as input with launcherDisplayMode

Source: https://docs.folivora.ai/docs/launcher/dynamic_content

This example demonstrates returning browser actions that remain visible while typing a URL, using the BTTLauncherPrompt variable to capture input.

```javascript
async function retrieveJSON() {  

  return JSON.stringify([  

    {  

      title: "Open in Safari",  

      subtitle: "Uses the current Launcher prompt as URL",  

      meta: "open-in-safari",  

      icon: "sfsymbol::safari",  

      launcherDisplayMode: "always",  

      action: openUrlAction("com.apple.Safari")  

    },  

    {  

      title: "Open in Default Browser",  

      subtitle: "Uses the current Launcher prompt as URL",  

      meta: "open-in-default-browser",  

      icon: "sfsymbol::globe",  

      launcherDisplayMode: "always",  

      action: openUrlAction("Default")  

    },  

    {  

      title: "Paste URL",  

      subtitle: "Uses the current Launcher prompt as URL",  

      meta: "paste-url",  

      icon: "sfsymbol::doc.on.clipboard",  

      launcherDisplayMode: "always",  

      action: pasteUrlAction()  

    }  

  ]);  

}  

  

function openUrlAction(browserBundleIdentifier) {  

  return {  

    js: `  

      async function run() {  

        const input = await get_string_variable({ variable_name: "BTTLauncherPrompt" });  

        const url = normalizeUrl(input);  

        return await trigger_action({  

          json: JSON.stringify({  

            BTTPredefinedActionType: 59,  

            BTTPredefinedActionName: "Open URL  or  Open URL With Selection",  

            BTTOpenURL: url,  

            BTTOpenURLBrowser: ${JSON.stringify(browserBundleIdentifier)}  

          }),  

          wait_for_reply: true  

        });  

      }  

  

      function normalizeUrl(value) {  

        const text = String(value || "").trim();  

        if (/^https?:\\/\\//i.test(text)) {  

          return text;  

        }  

        return "https://" + text;  

      }  

    `,  

    function: "run"  

  };  

}  

  

function pasteUrlAction() {  

  return {  

    js: `  

      async function run() {  

        const input = await get_string_variable({ variable_name: "BTTLauncherPrompt" });  

        const url = normalizeUrl(input);  

        return await paste_text({  

          text: url,  

          insert_by_pasting: true  

        });  

      }  

  

      function normalizeUrl(value) {  

        const text = String(value || "").trim();  

        if (/^https?:\\/\\//i.test(text)) {  

          return text;  

        }  

        return "https://" + text;  

      }  

    `,  

    function: "run"  

  };  

}  
```

--------------------------------

### get_preset_details

Source: https://docs.folivora.ai/docs/scripting/cli

Gets details about a preset.

```APIDOC
## get_preset_details

### Description
Gets details about a preset.

### Parameters
- **name** (string) - Required - Preset name
```

--------------------------------

### Run Swift Script Library Mode Configuration

Source: https://docs.folivora.ai/docs/actions/action-definitions

Example configuration for running a Swift script as a library, which requires defining a run function to interact with the BTT object.

```json
{
  "BTTPredefinedActionType": 691,
  "BTTAdditionalActionData": {
    "BTTScriptType": 5,
    "BTTScriptLocation": 0,
    "BTTSwiftScriptExecutionMode": 0,
    "BTTSwiftScriptTimeout": "10",
    "BTTScriptString": "import Foundation\nimport AppKit\n\nfunc run(_ btt: BTTScript) async throws -> Any? {\n    let app = NSWorkspace.shared.frontmostApplication?.localizedName ?? \"unknown\"\n    await btt.setVariable(\"frontApp\", app)\n    return app\n}"
  }
}
```

--------------------------------

### App Launch Trigger JSON

Source: https://docs.folivora.ai/docs/json/trigger-definitions

Example configuration for triggering an action when a specific application is launched.

```json
{

  "BTTTriggerType": 670,

  "BTTTriggerClass": "BTTTriggerTypeOtherTriggers",

  "BTTAdditionalConfiguration": "file:///Applications/Safari.app/",

  "BTTActionsToExecute": [{

    "BTTPredefinedActionType": 371,

    "BTTAdditionalActionData": { "BTTActionSendNotificationMessage": "Safari launched!" }

  }]

}
```

--------------------------------

### get_trigger

Source: https://docs.folivora.ai/docs/scripting/cli

Gets details for a specific trigger.

```APIDOC
## get_trigger

### Description
Gets details for a specific trigger.

### Parameters
- **uuid** (string) - Required - Trigger UUID
```

--------------------------------

### BTTLauncherPluginCommand

Source: https://docs.folivora.ai/docs/plugins/launcher

Defines a command that appears in the launcher's command list, supporting keyboard shortcuts and item-specific actions.

```APIDOC
## BTTLauncherPluginCommand

### Properties
- **commandIdentifier** (String) - Unique identifier for the command.
- **title** (String) - Display title of the command.
- **subtitle** (String) - Optional subtitle for the command.
- **systemImageName** (String) - Name of the system image to display.
- **shortcut** (BTTLauncherPluginShortcut) - Keyboard shortcut associated with the command.
- **surfaceIdentifier** (String) - Identifier for a launcher-hosted plugin surface.
- **closesLauncherOnSuccess** (Bool) - Whether the launcher closes upon successful execution.
- **destructive** (Bool) - Whether the command is destructive.
```

--------------------------------

### Configure title property

Source: https://docs.folivora.ai/docs/scripting/simple-format

Example of setting the title property with color and size using the string-based syntax.

```json
{

"title": "hello::size@@30::color@@#000000"

}
```
Tokens:
Raw