URL schemes

Trigger Thaw actions and read/write settings from thaw:// URLs. Use it with Raycast, Alfred, Shortcuts, or shell scripts.

Thaw registers the thaw:// scheme in Info.plist (CFBundleURLTypes).

thaw:// URL SchemeCopy Anchor Link

Supported ActionsCopy Anchor Link

Usage ExamplesCopy Anchor Link

open "thaw://toggle-hidden"
open "thaw://search"
open "thaw://open-settings"

NSWorkspace.shared.open(URL(string: "thaw://search")!)

tell application "System Events"
    open location "thaw://toggle-hidden"
end tell

Raycast IntegrationCopy Anchor Link

Quicklink: create one with link thaw://toggle-hidden and assign a hotkey (e.g. ⌃⌥⌘H).

Script command with a dropdown:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Thaw Actions
# @raycast.mode silent
# @raycast.argument1 { "type": "dropdown", "placeholder": "Action", "data": [{"title": "Toggle Hidden", "value": "toggle-hidden"}, {"title": "Search", "value": "search"}, {"title": "Settings", "value": "open-settings"}] }

open "thaw://${1}"

Alfred WorkflowCopy Anchor Link

Add an Open URL object with thaw://toggle-hidden and connect it to a hotkey trigger.

Info.plist URLsCopy Anchor Link

Internal URLs configured in Thaw/Resources/Info.plist:

System URLsCopy Anchor Link

macOS Settings URLs Thaw opens:

Settings URI (Automation)Copy Anchor Link

Read and write Thaw settings via thaw:// URLs, gated by a security whitelist. Automation tools like Droppy use this to control Thaw settings.

Security ModelCopy Anchor Link

1. Feature toggle: Settings URI is disabled by default (enable in Settings → Automation)
2. Whitelist: only approved apps can modify settings
3. First-time authorization: new apps trigger a confirmation dialog with app name and permissions. Apps can proactively request authorization via thaw://authorize without reading or writing settings
4. Silent failures: unauthorized requests fail without user interruption

Supported Settings KeysCopy Anchor Link

Global Settings (All Displays)Copy Anchor Link

Double/Time Interval SettingsCopy Anchor Link

Values outside the valid range are clamped to the nearest boundary. iconRefreshInterval is additionally snapped onto the discrete fps grid above before it is stored.

Enum SettingsCopy Anchor Link

Per-Display SettingsCopy Anchor Link

These settings affect specific displays based on context. The Scope column is the default; display=<UUID> overrides it to target one display by UUID and fails silently if that display is not connected.

Find display UUIDs in System Settings → Displays, or via system_profiler SPDisplaysDataType.

Settings URL FormatCopy Anchor Link

Set a boolean:

thaw://set?key=<setting>&value=<true|false>

open "thaw://set?key=autoRehide&value=true"
open "thaw://set?key=useIceBar&value=true&display=37D8832A-2D66-02CA-B9F7-8F30A301B230"

Toggle a boolean:

thaw://toggle?key=<setting>

open "thaw://toggle?key=autoRehide"
open "thaw://toggle?key=useIceBar&display=XYZ789-..."

Set a non-boolean (enum, double, location, layout) with thaw://set:

open "thaw://set?key=iceBarLocation&value=mousePointer"
open "thaw://set?key=iceBarLayout&value=grid"
open "thaw://set?key=gridColumns&value=5"
open "thaw://set?key=rehideInterval&value=10"
open "thaw://set?key=showOnHoverDelay&value=0.5"
open "thaw://set?key=rehideStrategy&value=timed"   # or numeric: value=1

Authorizing an AppCopy Anchor Link

External apps can proactively request authorization via thaw://authorize, which triggers the macOS permission dialog for the calling app without reading or writing any settings.

open "thaw://authorize"
open "thaw://get?key=all&callback=myapp://response&requestId=1"

• If the app is already whitelisted: silent no-op.
• If not whitelisted: shows the authorization dialog with app name, bundle ID, and signing info. After approval, the app can use all settings URIs.

Getting Settings (Read Operations)Copy Anchor Link

Read settings via thaw://get. Provide a response mechanism: a callback URL (recommended, receives full data) or broadcast=true (acknowledgement only).

For security, full settings data is only sent via callback. broadcast=true returns only an acknowledgement.

open "thaw://get?key=all&callback=droppy://thaw-response&requestId=abc123"
open "thaw://get?key=autoRehide&callback=droppy://thaw-response"
open "thaw://get?key=useIceBar&display=37D8832A-...&callback=droppy://thaw-response"
open "thaw://get?key=displays&callback=droppy://thaw-response"
open "thaw://get?key=display&display=37D8832A-...&callback=droppy://thaw-response"

App version is read-only and needs no whitelist auth; it works with broadcast=true too:

open "thaw://get?key=version&callback=droppy://thaw-response&requestId=abc123"
open "thaw://get?key=version&broadcast=true&requestId=abc123"

Response shapesCopy Anchor Link

All-settings (via callback):

{
  "requestId": "abc123",
  "status": "success",
  "data": {
    "appVersion": {"value": "1.2.3", "build": "42"},
    "global": {
      "autoRehide": {"value": true, "type": "boolean"},
      "rehideInterval": {"value": 5.0, "type": "double", "range": {"min": 1, "max": 300}},
      "rehideStrategy": {"value": "timed", "rawValue": 1, "type": "enum", "validValues": {"smart": 0, "timed": 1, "focusedApp": 2}}
    },
    "displays": {
      "37D8832A-2D66-02CA-B9F7-8F30A301B230": {
        "name": "Built-in Retina Display",
        "isConnected": true,
        "isPrimary": true,
        "hasNotch": true,
        "resolution": "2560x1600",
        "useIceBar": true,
        "useThawBarForAlwaysHidden": false,
        "iceBarLocation": "mousePointer",
        "alwaysShowHiddenItems": false
      }
    }
  }
}

Single setting:

{
  "requestId": "uuid",
  "status": "success",
  "key": "autoRehide",
  "data": {"value": true, "type": "boolean"}
}

Displays:

{
  "requestId": "uuid",
  "status": "success",
  "data": {
    "displays": [
      {
        "uuid": "37D8832A-...",
        "name": "Built-in Retina Display",
        "isConnected": true,
        "isPrimary": true,
        "hasNotch": true,
        "resolution": "2560x1600",
        "useIceBar": true,
        "useThawBarForAlwaysHidden": false,
        "iceBarLocation": "mousePointer",
        "alwaysShowHiddenItems": false
      }
    ]
  }
}

Broadcast (ack only):

{
  "requestId": "abc123",
  "status": "ack",
  "message": "Use callback URL to receive full settings data"
}

Error:

{
  "requestId": "uuid",
  "status": "error",
  "error": "Display not found",
  "details": "UUID: INVALID-UUID"
}

Response mechanismsCopy Anchor Link

Callback URL (recommended): Thaw opens yourapp://thaw-response?data=<url-encoded-json> with the full payload. Your app must implement a URI handler.

Distributed notification (ack only): Thaw broadcasts on DistributedNotificationCenter, notification name com.stonerl.Thaw.settingsURIGetResponse. Returns only an acknowledgement, not the full payload.

open "thaw://get?key=all&broadcast=true&requestId=abc123"

Testing from Terminal (DEBUG builds only)Copy Anchor Link

Sender detection fails from open, so DEBUG builds support a manual bundleId override:

open "thaw://set?key=showOnHover&value=true&bundleId=com.apple.Terminal"

The bundleId parameter is stripped/ignored in release builds. Remove it in production scripts.

Raycast Settings IntegrationCopy Anchor Link

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Toggle Thaw Setting
# @raycast.mode silent
# @raycast.argument1 { "type": "dropdown", "placeholder": "Setting", "data": [{"title": "Auto-Rehide", "value": "autoRehide"}, {"title": "Hover Reveal", "value": "showOnHover"}, {"title": "Thaw Bar", "value": "useIceBar"}] }

open "thaw://toggle?key=${1}"

Whitelist ManagementCopy Anchor Link

Manage authorized apps in Settings → Automation:

• View all whitelisted applications with icons and names
• Remove apps to revoke their access
• Manually add bundle IDs for apps not yet authorized
• Test with Thaw itself (DEBUG builds only)

Error HandlingCopy Anchor Link

Settings URI requests fail silently when the feature is disabled, the requesting app is not whitelisted (and the user denied authorization), the setting key is invalid, or the boolean value is not true/false/1/0/yes/no. Check Thaw’s diagnostic logs for details.

NotesCopy Anchor Link

• All thaw:// URLs work even when Thaw is not in the foreground
• The app may activate itself depending on the action
• URL handling is case-insensitive for the host portion
• Invalid URLs are logged but silently ignored
• Settings changes via URI trigger the same UI updates as manual changes