SDK Reference - Rebind

The whole SDK runs free in software mode. No hardware is required. To install or update, run the one-line installer in the quickstart. A few namespaces depend on OS-specific APIs; see Platforms & limits for the authoritative per-namespace support matrix.

Globals

Run

local handle = Run(fn: function) -> TaskHandle

Launches a function as a coroutine. Returns immediately. The function executes concurrently with other script code. Returns a TaskHandle with:

handle:Cancel(): stop the coroutine
handle:IsRunning(): returns boolean

If the coroutine errors, the runtime logs it with a traceback (visible in the Logs tab), stops that coroutine (handle:IsRunning() then returns false), and marks the script’s error state. Other coroutines and hooks keep running. Wrap fallible work in pcall to let a coroutine survive a recoverable error.

Sleep

Sleep(ms: number)

Pauses the current coroutine for ms milliseconds. Only valid inside a Run() block. Calling Sleep() outside a coroutine raises an error. Does not block anything else.

After

local handle = After(ms: number, fn: function) -> TaskHandle

Shorthand for running a function after a delay. Equivalent to Run(function() Sleep(ms) fn() end). Returns a TaskHandle.

After(2000, function()
  Log.Info("2 seconds later")
end)

Async

local wrappedFn = Async(fn: function) -> function

Returns a new function that automatically runs fn in a coroutine when called. This lets you use Sleep() and other coroutine features inside callbacks that are normally synchronous (like Bind handlers). When the wrapped function is called from the main thread, it spawns a Run() and returns false (swallow). When called from inside an existing coroutine, it calls fn directly to avoid double-wrapping.

-- without Async: manual Run() wrapping
Bind("F10", function()
  Run(function()
    HID.Down("W")
    Sleep(500)
    HID.Up("W")
  end)
  return false
end)

-- with Async: Sleep() just works
Bind(
  "F10",
  Async(function()
    HID.Down("W")
    Sleep(500)
    HID.Up("W")
  end)
)

require

require(module: string) -> any

Loads a sibling module file relative to the script’s own directory and returns its value (a module is a file that returns something, usually a table). Modules are cached: the file is evaluated once on first require, and later requires of the same path return that same value. Resolution for an extensionless name, in order: <name>.luau, <name>.lua, <name>/init.luau, <name>/init.lua. Dots are path separators (require("lib.math") → lib/math.luau); a leading ./ is stripped; an explicit .lua / .luau suffix pins that exact file. Sandboxed to the script directory: a name containing .., or any candidate that resolves outside the directory, raises path traversal not allowed; an unresolved name raises module '<name>' not found. A name the script directory cannot resolve is looked up once more, by the same rules, in the packages folder of Rebind’s app directory. A name starting with macros/ that neither resolves is looked up in the macros folder of your scripts, where the recorder saves takes, so any script can require("macros/<name>") and get that macro’s actions. There are no registries, package.path, or aliases: local files only. rebind check and publishing resolve inside the package only.

local helpers = require("helpers") -- helpers.luau next to the script
local m = require("lib.math") -- lib/math.luau

Only a directly-run script needs a min_sdk modeline; a require’d module is loaded through that script, not run directly, so it needs no header. See the scripting guide.

_REBIND

_REBIND: {
  name: string,
  version: string,
  min_sdk: string,
  tick_rate: number,
  runtime_uuid: string,
  instance: string,
  platform: string,
}

Read-only table injected by the host with metadata about the current script and runtime. Available immediately at load time. version is the installed Rebind SDK version, not the script’s modeline version. platform is the host operating system as "windows", "macos" or "linux", for chords and launchers that differ per OS.

Log.Info("Running " .. _REBIND.name .. " on Rebind " .. _REBIND.version)
Log.Info("SDK: " .. _REBIND.min_sdk .. ", tick rate: " .. _REBIND.tick_rate)

Hooks

Global functions your script defines. The runtime calls them when events occur.

Lifecycle

function OnStart()          -- script loaded
function OnStop()           -- script about to unload
function OnFocus(window)    -- target window gained focus ({ title, process, x, y, width, height })
function OnBlur(window)     -- target window lost focus ({ title, process, x, y, width, height })
function OnTick(dtMs)       -- dtMs = ms elapsed since the previous OnTick (0 on the first)

OnTick fires on a fixed cadence set by the tick_rate modeline (default 1,000/s, max 8,000/s) while the script is active. Its argument dtMs is the real time elapsed since this script’s previous OnTick, in milliseconds. It is fractional (at 8,000/s it’s ~0.125), and 0 on the very first call. Use it for frame-rate- independent work, e.g. pos += velocity * dtMs. Run() coroutines, Timer callbacks, and network I/O are serviced on every engine tick regardless of tick_rate. OnStart runs once per load, before any other hook. For a targeted script that is already focused at load time, OnFocus fires immediately on the same load; an unfocused targeted script gets OnStart only, and its OnFocus/OnTick/timers wait until the target gains focus. Top-level code runs immediately when the script file is loaded, before OnStart is called. Use it for constants, module initialization, and guards that must run before anything else.

-- top-level: runs at load time
local BASE_SENS = 0.8

function OnStart()
  -- runs after the script is fully registered
  Log.Info("ready, sensitivity = " .. BASE_SENS)
end

OnStart is the right place for anything that needs the script to be fully registered first, such as reading persisted UI values or starting timers.

Input

All input hooks can return false to block the event from reaching the PC, or return true to pass it through. OnMove is the exception: it needs a Rebind device, and its return value counts only with mouse_block=true.

function OnDown(key)                -- key/button pressed
function OnUp(key, durationMs)      -- key/button released
function OnMove(dx, dy)             -- mouse moved
function OnScroll(delta)            -- vertical scroll

Exclusive capture: because OnDown/OnUp may block any key, defining either one makes Rebind intercept every key system-wide and re-emit the ones your script passes through. Tools that only trust real device input (Keyboard Maestro, Karabiner, some games) will not see re-emitted keys while such a script runs. If you only care about specific keys, use Bind. It intercepts only its declared triggers and leaves everything else untouched. A hook script that never blocks can also declare key_block=false to observe without intercepting.

Observers

Every input event is also delivered to a matching observer hook. Observers fire on all running scripts and their return value is ignored, so they cannot block an event. Use them to watch input without taking exclusive capture.

function OnInputDown(key)            -- key/button pressed
function OnInputUp(key, durationMs)  -- key/button released
function OnInputMove(dx, dy)         -- mouse moved
function OnInputScroll(delta)        -- vertical scroll

A script that defines only observers never intercepts anything, so it does not trigger the exclusive-capture behavior described above.

Other (reserved, not yet dispatched)

These hooks are recognized but not dispatched in the current release. Defining them will not cause errors; they won’t fire.

function OnScrollH(delta)           -- horizontal scroll (tilt wheel)
function OnReload()                 -- script reloaded from disk
function OnError(message)           -- runtime error in a hook or coroutine

System

Read-only methods updated automatically every tick.

Function	Returns	Description
`System.Time()`	number	Current timestamp in milliseconds
`System.Mouse()`	x, y	Cursor position in pixels (multiple return values)
`System.Screen()`	width, height	Primary display dimensions in pixels (multiple return values)
`System.Window()`	table	Active window info: `{ title, process, x, y, width, height }`
`System.Exec(cmd, options?)`	table	Run a shell command and capture output. Non-blocking inside `Run()`, sync fallback elsewhere
`System.ExecDetached(cmd, args?, options?)`	number	Launch a detached process, return its PID
`System.TypeText(text)`	nothing	Type a string through the host operating system, Unicode included

System.TypeText

System.TypeText inserts text the way the OS would from a keyboard, but it never touches the script’s HID output path. In hardware mode HID.Type goes to the Rebind Link and is limited to the characters its layout map knows; System.TypeText still reaches the focused app on the host and carries any Unicode. Use it for snippets, replies and clipboard slots. It raises an error when the OS refuses the injection (macOS without the Accessibility grant, a Windows secure desktop), so wrap it in pcall when you want to report that. Release the chord that triggered it before typing: a modifier still held turns the inserted characters into shortcuts in the receiving app. A Bind release callback plus a short wait on Input.GetModifiers() is the usual shape.

System.Exec

local result = System.Exec(cmd: string, options?: { timeout?: number, cwd?: string })

Runs a shell command (cmd.exe /C on Windows, sh -c on macOS/Linux) and returns when it completes. Returns: { exit: number, stdout: string, stderr: string } Options:

timeout: max execution time in ms (default: 5000). The process is killed if it exceeds this.
cwd: working directory for the command.

Output is capped at 64KB per stream. The console window is suppressed on Windows.

-- list files
local result = System.Exec("dir /b", { cwd = "C:\\Users" })
Log.Info(result.stdout)

-- run a Python script
local result = System.Exec("python analyze.py", { timeout = 10000 })
if result.exit ~= 0 then
  Log.Error("Failed: " .. result.stderr)
end

Non-blocking inside Run(): Called from inside Run() or an Async() handler, System.Exec runs the command on a background thread and yields the coroutine. The tick thread never blocks, and the call returns its result table on a later tick. Called outside a coroutine (OnTick, OnDown/OnUp/OnMove, plain Bind callbacks, the top-level chunk), it falls back to synchronous blocking that stalls the tick thread until the command finishes and logs a one-time warning. This sync fallback is deprecated. Wrap System.Exec in Run().

-- non-blocking: runs on a background thread, tick thread keeps ticking
Bind("F5", function()
  Run(function()
    local result = System.Exec("python analyze.py", { timeout = 10000 })
    Log.Info(result.stdout)
  end)
  return false
end)

Permission: System.Exec requires the exec permission. It is granted by default, but once the modeline declares any permission= line you must include permission=exec, or the call raises System.Exec() requires 'exec' permission at call time. (System.ExecDetached is gated by the same exec permission. See Permissions.)

System.ExecDetached

local pid = System.ExecDetached(cmd: string, args?: string[], options?: { cwd?: string })

Launches cmd as a detached, fire-and-forget process and returns immediately with its PID. Unlike System.Exec, it does not wait for the process or capture its output: stdio is discarded (null). Returns: the spawned process PID as a number. Options:

cwd: working directory for the process.

The console window is suppressed on Windows. The process keeps running after the script exits.

-- open a file in the default editor and keep going
local pid = System.ExecDetached("notepad.exe", { "notes.txt" })
Log.Info("launched editor, PID " .. pid)

System.Exec vs System.ExecDetached:

System.Exec: captures stdout/stderr/exit. Non-blocking inside Run() (yields the coroutine); synchronous blocking fallback elsewhere. Use when you need the output.
System.ExecDetached: detached, returns instantly with a PID, no output captured. Use to launch apps or background processes.

HID

Sends keyboard and mouse output through the active transport.

Keyboard

Function	Description
`HID.Down(key)`	Hold a key or button. Non-blocking, safe anywhere.
`HID.Up(key)`	Release a key or button. Non-blocking, safe anywhere.
`HID.Combo(chord)`	Fire a whole chord in one call: press left-to-right, release right-to-left. Non-blocking, safe anywhere (including directly in a `Bind` action).
`HID.Press(key, holdMs?)`	Tap a key (Down + Sleep + Up). Coroutine only. Default hold: 50ms
`HID.Type(text)`	Send a string through the active transport in one call. No coroutine required. Character and timing behavior varies by transport.
`HID.Typewriter(text, delayMs?)`	Type a string character-by-character with an inter-key delay, for a human-like effect. Coroutine only. Default delay: 30ms

Important: HID.Press and HID.Typewriter use Sleep() internally and must be called inside a Run() coroutine or an Async() handler: calling them outside a coroutine (e.g. directly in OnDown or a Bind action) raises an error. HID.Down, HID.Up, and HID.Combo do not sleep. HID.Type needs no coroutine, but hardware typing emits per-character reports and can occupy the calling hook while it does so.

-- WRONG: Press outside a coroutine raises an error
function OnDown(key)
  if key == "F1" then
    HID.Press("A") -- ERROR: not in a coroutine
  end
end

-- CORRECT: use Async to wrap the handler
Bind(
  "F1",
  Async(function()
    HID.Press("LCtrl+V") -- works: Async provides a coroutine context
  end)
)

-- CORRECT: use Run inside a hook
function OnDown(key)
  if key == "F1" then
    Run(function()
      HID.Press("A") -- works: Run provides a coroutine context
    end)
    return false
  end
  return true
end

-- CORRECT: non-blocking alternative (no coroutine needed)
-- Down and Up mirror the physical press and release, so A is held for
-- exactly as long as F1 is. Both halves are required: a Down with no
-- matching Up leaves A held down forever.
function OnDown(key)
  if key == "F1" then
    HID.Down("A") -- instant, non-blocking
    return false
  end
  return true
end

function OnUp(key)
  if key == "F1" then
    HID.Up("A")
    return false
  end
  return true
end

-- CORRECT: for a chord TAP, HID.Combo emits the whole chord and releases it
-- in one call. Native, does not sleep, needs no coroutine.
function OnDown(key)
  if key == "F2" then
    HID.Combo("LCtrl+C")
    return false
  end
  return true
end

Combos

Combo, Down, Up, and Press all support + for modifier combos:

HID.Combo("LCtrl+V") -- Ctrl+V paste in one call (non-blocking, works anywhere)
HID.Combo("cmd+shift+r") -- ⇧⌘R (macOS aliases; non-blocking)

Run(function()
  HID.Press("LCtrl+V") -- same effect, but holds for a duration (coroutine only)
  HID.Press("LCtrl+LShift+T") -- Ctrl+Shift+T (coroutine only)
end)

HID.Down("LCtrl+LShift") -- hold both modifiers (non-blocking, works anywhere)
HID.Up("LCtrl+LShift") -- release both in reverse order (non-blocking)

HID.Combo presses keys left-to-right and immediately releases them right-to-left, in one synchronous call. Use it to fire a shortcut from a Bind action or OnDown. HID.Press does the same but holds for a duration (coroutine only). HID.Down presses left-to-right; HID.Up releases right-to-left. Modifier aliases: in addition to the canonical LCtrl/LShift/LAlt/LWin names, combos accept the shorthands Ctrl, Shift, Alt, Win/Meta/Cmd, and (macOS-friendly) Opt/Option. So "cmd+opt+i" and "LWin+LAlt+I" are equivalent. The + key itself is spelled Equal (unshifted) or KpPlus (numpad), so there is no ambiguity.

Usages

Keys can also be named by USB HID keyboard usage: usage:N, where N is decimal or 0x hex from 0x04 to 0xE7. This reaches keys that have no name. The media codes 0xB5 to 0xB7 and 0xCD are refused, because the software transports treat them as media keys. An invalid usage raises an error before any key is pressed.

Function	Description
`HID.Usage(name)`	Returns the keyboard usage for a key name, or `nil` for unknown names and media keys

HID.Down("usage:0x04") -- same key as HID.Down("A")
HID.Up("usage:4")
print(HID.Usage("LCtrl")) -- 224

Mouse

Function	Description
`HID.Move(dx, dy)`	Relative mouse movement (pixels)
`HID.MoveTo(x, y)`	Move to absolute position via relative movement
`HID.Scroll(amount)`	Vertical scroll (positive = up)

Joypad

A Rebind Link whose USB profile includes a joypad appears to the computer as a game controller with 32 buttons, an 8-way hat, four axes, and two sliders.

Function	Description
`HID.Joypad(state)`	Set the whole joypad state. Fields left out are neutral.
`HID.JoypadReset()`	Return the joypad to neutral

state fields: buttons (a list of pressed buttons, 1 to 32), hat (0 for up through 7 clockwise; leave it out for centered), x, y, z, rz (-1 to 1, 0 is center), and slider, dial (0 to 1).

HID.Joypad({ buttons = { 1 }, x = 0.5 }) -- button 1 held, stick halfway right
HID.JoypadReset()

The last state written wins, whichever script wrote it. The relay returns the joypad to neutral when a script stops or errors and when the kill switch fires. On a Link whose profile has no joypad, and in software mode, these calls raise an error. Keyboard and mouse calls raise the same way on a Link whose profile leaves that interface out.

Mouse mode

Function	Description
`HID.SetMouseMode(mode)`	`"relative"` or `"absolute"`
`HID.GetMouseMode()`	Returns current mode string

Relative mode (default): single-pass movement, designed to be fast; may drift. Best for fast cursor movement. Absolute mode: iterative correction with position validation, slower, designed for sub-5px accuracy. Best for desktop automation.

Input

Reads the current physical state of input devices.

Function	Returns	Description
`Input.IsDown(key)`	`boolean`	Whether key/button is currently held
`Input.GetDuration(key)`	`number`	Milliseconds held, 0 if not pressed
`Input.GetActiveKeys()`	`string[]`	All currently held keys
`Input.GetMousePos()`	`{x, y}`	Current cursor position
`Input.GetModifiers()`	`table`	`{ctrl, shift, alt, win}` booleans

Input.IsDown / Input.GetDuration accept the same names as the rest of the SDK, including mouse buttons (Mouse1 through Mouse5); an unknown or never-pressed code returns false / 0 rather than erroring.

UI

Defines a settings panel rendered in the Rebind UI.

Schema

local cfg = UI.Schema({
  key = UI.Widget(default, options?),
  ...
})

Returns a proxy handle. Read values with cfg.key, write with cfg.key = value.

Widgets

Constructor	Default Type	Description
`UI.Toggle(default, opts?)`	boolean	On/off switch
`UI.Slider(default, opts?)`	number	Numeric slider
`UI.Keybind(default, opts?)`	string	Key binding selector
`UI.Select(default, choices, opts?)`	string	Dropdown selection
`UI.Text(default, opts?)`	string	Text input field
`UI.Color(default, opts?)`	string	Color picker; value is a hex string (e.g. `"#ff0000"`)

Option	Type	Applies to	Description
`label`	string	all	Display label (overrides key name)
`tooltip`	string	all	Hover description
`group`	string	all	Visual section header
`tab`	string	all	Tab panel name
`showIf`	string	all	Show only when the named toggle is on, or when `select:value` matches
`min`	number	Slider	Minimum value
`max`	number	Slider	Maximum value
`step`	number	Slider	Increment size
`suffix`	string	Slider	Unit label (e.g. `"%"`)
`placeholder`	string	Text	Hint when empty
`maxLength`	number	Text	Character limit

A Slider with no min/max defaults to a range of 0 to 100. tooltip, group, tab, and showIf apply to every widget, including UI.Color.

Other

Function	Description
`UI.Get(id)`	Read value by string key
`UI.Set(id, value)`	Write value by string key
`UI.GetAll()`	All current values as a table
`UI.GetSchema()`	Full schema descriptor array (for advanced introspection)
`UI.Notify(message, variant?)`	Show notification. Variant: `"info"` (default), `"success"`, `"warning"`, `"error"`

Persistence

Values are saved automatically on every change and restored at startup. Persistence is keyed to the script’s file path: no configuration required.

Macro

Record and play back input sequences.

Playback

Function	Description
`Macro.Play(macro, speed?, mode?)`	Play a macro. Returns a handle.
`Macro.StopAll()`	Stop all running macros

Speed: 1.0 = normal, 0.5 = half speed, 2.0 = double speed. Default: 1.0. Mode: "parallel" (default), "replace". Handle methods:

handle:Stop()
handle:Pause()
handle:Resume()
handle:IsPlaying(): returns boolean
handle:GetProgress(): returns 0.0 to 1.0
handle:Wait(): blocks the current coroutine until playback ends. Must be called inside Run()

Hardware streaming

Function	Description
`Macro.Stream(macro)`	Stream to device for hardware-precision playback
`Macro.Abort()`	Stop device-side playback immediately

Macros containing "type" actions always play host-side. Macro.Play() automatically falls back to host-side execution when any Type action is present.

Recording

Function	Description
`Macro.Record(options?)`	Start recording input events. Calling it again restarts the script’s own take. Raises “another recording is running” while the app’s recorder or another script is recording
`Macro.Finish()`	Stop recording, return macro table. Ends with a release for every key and button still held
`Macro.ToScript(macro, name)`	Return the macro as a macro file: a modeline with `macro=true`, then `return` of the actions. The app’s recorder saves the same format

Record options: { ignore_mouse = false, ignore_keyboard = false, precision = "normal" } (keys are snake_case, and camelCase is silently ignored)

Format

Actions in a macro table:

Action	Fields	Description
(shorthand)	`x, y, delay`	Mouse movement
`"move"`	`dx, dy, delay`	Mouse movement (explicit)
`"down"`	`code, delay`	Hold key
`"up"`	`code, delay`	Release key
`"press"`	`code, holdMs, delay`	Tap key
`"type"`	`text, charDelay, delay`	Type string
`"scroll"`	`amount, delay`	Scroll wheel
`"sleep"`	`delay`	Pause

Timer

Function	Returns	Description
`Timer.After(ms, callback)`	handle	Execute once after delay
`Timer.Every(ms, callback)`	handle	Execute repeatedly at interval
`Timer.CancelAll()`	nothing	Cancel all active timers

Handle methods: handle:Cancel(), handle:Pause(), handle:Resume()

Math

Random

Function	Returns	Description
`Math.Random(min, max)`	number	Uniform random number
`Math.Gaussian(mean, stdDev)`	number	Normal distribution random

Transforms

All transform functions return a new table (original is unchanged).

Function	Description
`Math.Scale(macro, xFactor, yFactor)`	Multiply movement values
`Math.Spline(macro, tension)`	Catmull-Rom curve smoothing
`Math.Resample(macro, intervalMs)`	Normalize timing to fixed intervals
`Math.Interpolate(macro, intervalMs, mode?)`	Resample the mouse path at a fixed interval. `mode` is `"catmull"` (default, smooth curves) or `"linear"`. Movement-only: clicks, key presses, scroll, and sleeps are dropped from the result.
`Math.TimeComp(macro, targetMs)`	Scale total duration to target

Interpolate vs Resample:

Resample changes all delays uniformly (normalizing recorded macros)
Interpolate adds intermediate steps between existing points (smoothing patterns)

JSON

Function	Returns	Description
`JSON.Parse(str)`	table	Parse JSON string to Luau table
`JSON.Stringify(tbl)`	string	Serialize table to JSON string

Hash

Common cryptographic and checksum hashing. All inputs are treated as raw bytes.

Function	Returns	Description
`Hash.MD5(data)`	string	MD5 digest as a lowercase hex string
`Hash.SHA1(data)`	string	SHA-1 digest as a lowercase hex string
`Hash.SHA256(data)`	string	SHA-256 digest as a lowercase hex string
`Hash.SHA512(data)`	string	SHA-512 digest as a lowercase hex string
`Hash.CRC32(data)`	number	CRC32 checksum as a number (not hex)
`Hash.HMAC(algo, key, data)`	string	Keyed HMAC digest as a lowercase hex string

Hash.HMAC accepts algo of "sha256", "sha512", or "sha1". Any other value raises an error.

Log.Info(Hash.SHA256("abc")) --> "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"

-- sign an API request
local sig = Hash.HMAC("sha256", apiSecret, payload)

Codec

Base64 and hex encoding/decoding. These are encodings, not encryption. They provide no confidentiality.

Function	Returns	Description
`Codec.Base64(data)`	string	Encode bytes to a Base64 string
`Codec.Base64Decode(str)`	string	Decode a Base64 string to bytes
`Codec.Hex(data)`	string	Encode bytes to a lowercase hex string
`Codec.HexDecode(str)`	string	Decode a hex string to bytes

local encoded = Codec.Base64("hello") --> "aGVsbG8="
local decoded = Codec.Base64Decode(encoded) --> "hello"

Log

Function	Description
`Log.Info(message)`	Info-level log
`Log.Warn(message)`	Warning-level log
`Log.Error(message)`	Error-level log
`Log.Debug(message)`	Debug-level log (dev mode only)

Globals: print(...) and log(...) are both aliases for Log.Info. They accept multiple arguments, joined by tabs, identical to standard Lua print behaviour.

log("feature enabled, sensitivity =", sensitivity)
print("device ready")

Logs appear in the Rebind UI Logs tab.

File

All paths are relative to your script’s directory. Path traversal (..) is rejected.

Function	Returns	Description
`File.Read(path: string)`	string	Read UTF-8 text
`File.ReadBytes(path: string)`	string	Read raw bytes as a byte-safe Luau string
`File.Write(path: string, content: string)`	`()`	Overwrite a file. `content` may hold arbitrary bytes, such as a decoded `Screen.Capture` image
`File.Append(path: string, content: string)`	`()`	Append to a file, creating it when absent. Bytes are written as given
`File.Exists(path: string)`	boolean	Check whether a path exists. `false` on resolution error.
`File.Delete(path: string)`	boolean	Delete a file. `false` when the resolved path is not a file.
`File.List(path: string?)`	string[]	List names in a directory. Omit `path` for the script directory.
`File.MkDir(path: string)`	boolean	Create the directory and missing parents. Returns `true` on success.
`File.RmDir(path: string)`	boolean	Recursively remove a directory. Returns `true` on success.
`File.IsDir(path: string)`	boolean	Whether the path is a directory. `false` on resolution error.
`File.IsFile(path: string)`	boolean	Whether the path is a file. `false` on resolution error.
`File.GetSize(path: string)`	number	File size in bytes
`File.GetTime(path: string)`	number	Last-modified time in Unix seconds
`File.Copy(src: string, dst: string)`	`()`	Copy a file
`File.Move(src: string, dst: string)`	`()`	Rename a file. May fail across filesystems.
`File.ReadJSON(path: string)`	any	Read and parse JSON
`File.WriteJSON(path: string, value: any)`	`()`	Write pretty-printed JSON
`File.GetScriptDir()`	string	Absolute path to the script directory

File.IsDir and File.IsFile never throw: they return false for missing or out-of-sandbox paths. File.Move uses a rename and may fail across filesystems.

Net

Client

Client calls yield. Wrap them in Run() / Async(). Every HTTP client method below blocks on a background thread and yields the coroutine, so calling one directly in OnDown, top-level code, or any synchronous hook raises Net.X() must be called inside Run(). The snippets below assume they run inside a Run() block or an Async() handler. (The WebSocket calls Net.WSListen / Net.WSConnect are exempt: their I/O runs on dedicated threads. Net.UDPListen is exempt too: it never blocks.)

Function	Returns	Description
`Net.Get(url, headers?, options?)`	response	HTTP GET
`Net.Post(url, body, headers?, options?)`	response	HTTP POST
`Net.Put(url, body, headers?, options?)`	response	HTTP PUT
`Net.Patch(url, body, headers?, options?)`	response	HTTP PATCH
`Net.Delete(url, headers?, options?)`	response	HTTP DELETE
`Net.Head(url, headers?, options?)`	response	HTTP HEAD
`Net.Request(options)`	response	Generic HTTP request

Response: { status: number, body: string, headers: table } Options: { timeout = milliseconds }: optional trailing table for convenience methods. Net.Request options: { method: string, url: string, body?: string, headers?: table, timeout?: number }

-- simple GET
local resp = Net.Get("https://api.example.com/data")

-- POST with headers
local resp = Net.Post(
  "https://api.example.com/data",
  JSON.Stringify({ key = "value" }),
  { ["Content-Type"] = "application/json", ["Authorization"] = "Bearer token" }
)

-- DELETE with timeout
local resp =
  Net.Delete("https://api.example.com/item/123", nil, { timeout = 5000 })

-- generic request
local resp = Net.Request({
  method = "PATCH",
  url = "https://api.example.com/item/123",
  body = JSON.Stringify({ name = "updated" }),
  headers = { ["Content-Type"] = "application/json" },
  timeout = 10000,
})

Custom headers (including User-Agent) can be set on any request via the headers table.

HTTP server

local server = Net.Listen(port, handler)

Handler: receives request, returns { status?, body?, headers? } (status defaults to 200), or a plain string sent as a 200 body. Request fields: req.method (e.g. "GET", "POST"), req.path (e.g. "/click"), req.body (string), req.headers (table). Server handle: server:Stop() Net.Listen binds 127.0.0.1 (localhost only). It is not reachable from other machines. For a LAN-facing endpoint use Net.WSListen, which binds 0.0.0.0, or Net.UDPListen on a LAN address. Each server answers one request at a time: a request waits for your handler, which runs on the script’s tick loop, before the next is read. A request still unanswered after 30 seconds receives 504, so keep handlers fast. For the same request-in, input-out shape over a persistent connection, see the WebSocket remote in the cookbook.

WebSocket server

local server = Net.WSListen(port, handlers)

Handlers table: all optional.

Handler	Signature	Fires when
`OnConnect`	`function(client)`	a new client has completed the WS handshake
`OnMessage`	`function(client, payload, is_binary)`	the server received a frame
`OnClose`	`function(client)`	the connection was closed (by either side)

Client handle (passed to handlers): client.id, client:Send(text), client:SendBinary(bytes), client:Close(). Server handle: server:Broadcast(text), server:BroadcastBinary(bytes), server:ClientCount(), server:Stop(). Binary frames arrive as Lua strings (read bytes with string.byte / string.unpack); the is_binary flag distinguishes them from text. The maximum message/frame size is 64 MiB per connection. A larger frame drops the connection. Net.WSListen and Net.WSConnect are exempt from the Run() requirement the HTTP client methods have: their socket I/O runs on dedicated threads. The server binds 0.0.0.0:<port>. Events are dispatched to Lua handlers on the script’s tick loop. Up to 32 events are processed per tick per server, within a 20 ms handler budget shared by every WebSocket server and client; excess messages backlog into the next tick. There is no built-in rate limiting. Scripts exposed to untrusted networks should implement their own. For latency and throughput caveats, see Remote control. Example:

local server = Net.WSListen(19561, {
  OnMessage = function(client, payload, is_binary)
    if payload == "hello" then
      client:Send("world")
    else
      server:Broadcast("someone said: " .. payload)
    end
  end,
})

WebSocket client

local conn = Net.WSConnect(url, handlers)

URL: ws://host:port/path or wss://host:port/path. TLS uses the standard web root certificates. Handlers table: all optional.

Handler	Signature	Fires when
`OnOpen`	`function()`	the WS handshake completed
`OnMessage`	`function(payload, is_binary)`	a frame arrived from the server
`OnClose`	`function()`	the connection closed

Connection handle: conn:Send(text), conn:SendBinary(bytes), conn:Close(). Example:

local conn = Net.WSConnect("wss://echo.websocket.events", {
  OnOpen = function()
    conn:Send("hello from rebind")
  end,
  OnMessage = function(payload, is_binary)
    Log.Info("got: " .. payload)
  end,
})

UDP

local socket = Net.UDPListen(bindIp, port, handler)

Handler: function(data, ip, port) receives each datagram’s bytes as a Lua string and the sender’s address. Socket handle: socket.port, socket:SendTo(ip, port, bytes), socket:Stop(). SendTo sends from the bound address, returns false when the send fails or the socket is stopped, and raises an error on an invalid address. Port 0 picks a free port, readable from socket.port. The socket binds the address you give, so "127.0.0.1" stays on this computer and a LAN address is reachable from that network. The call raises an error when the address is invalid or the port is taken. Datagrams are dispatched on the script’s tick loop, up to 32 per tick per socket within a 20 ms handler budget shared with Net.Listen servers; UDP sockets are served first. Datagrams of 2048 bytes or more are dropped. A handler error is logged and the socket keeps running. There is no authentication; check the sender and contents in your handler.

local socket
socket = Net.UDPListen("127.0.0.1", 19562, function(data, ip, port)
  socket:SendTo(ip, port, "ack:" .. data)
end)

Remote clients are available for TypeScript, Python, and Rust: drive a running script’s HTTP/WebSocket server from any program.

Screen

Pixel color sampling from the screen. See Platforms for supported calls and platform-specific errors.

Function	Returns	Description
`Screen.GetPixelColor(x?, y?)`	string	Hex color `"rrggbb"` at pixel coordinates. If no args, reads at current mouse position.
`Screen.SearchForColor(region, color, tolerance?)`	`{x, y}?`	Search a screen region for a pixel matching `color`. Returns `{x, y}` or `nil`.
`Screen.List()`	`{MonitorEntry}`	List all connected monitors. Each entry has `index`, `x`, `y`, `width`, `height`, `primary`.
`Screen.Capture(opts?)`	`{image, width, height, display, cursor}`	Capture a display (or a region of it) as a base64 PNG at native resolution, plus geometry and cursor for mapping image coordinates back to the screen.
`Screen.FindImage(needle, opts?)`	`{x, y, width, height}?`	Find a PNG from the script directory on a display (or a region of it). Returns the first match in screen coordinates, or `nil`.
`Screen.WorkArea(x?, y?)`	`{x, y, width, height}`	Usable desktop of the display containing the point (the cursor when omitted): the monitor minus the taskbar. Windows only; raises an error elsewhere.

While a script that mentions Screen is loaded, on macOS the relay streams each display into a frame it keeps in memory, so a read never waits on the compositor. On Windows each read is still a GDI call until the equivalent stream lands. GetPixelColor costs about a microsecond. SearchForColor scans the frame at about 0.6 ns per physical pixel: a region up to 200k physical pixels, about 220x220 on a 2x display or 440x440 on a 1x one, answers on the thread that calls it, tick included. A larger region runs on a worker thread and yields inside Run(); outside a coroutine it raises an error naming the limit. Screen.Capture and Screen.FindImage always yield and are refused outside a coroutine. The stream starts when the script loads and stops when it unloads. On macOS it lights the screen recording indicator, as any screen read does. Reads see the display as of the last change the window server published, which is what a screenshot would show at that moment. On macOS, capture handles Retina displays automatically. GetPixelColor/SearchForColor coordinates are in logical (non-retina) pixels; Screen.Capture returns native (physical) pixels and reports the scale via the returned dimensions vs the display’s logical size.

Screen.SearchForColor

region: {x1, y1, x2, y2} table of screen coordinates. Negative values address displays left of or above the primary.
color: hex string "rrggbb", case-insensitive (matches GetPixelColor output)
tolerance: optional, 0.0 to 1.0 (default 0.0 = exact match). Per-channel percentage of 255.
Returns {x, y} of first match (top-left to bottom-right scan), or nil if not found. A capture failure is an error, never nil.
Regions over 200k physical pixels must be called inside Run().

-- find a dark-red pixel in a region of the screen
local match = Screen.SearchForColor({ 900, 500, 1100, 530 }, "8b0000", 0.05)
if match then
  Log.Info("found at " .. match.x .. ", " .. match.y)
end

-- sample a color, then search for it elsewhere
local color = Screen.GetPixelColor(960, 540)
local match = Screen.SearchForColor({ 0, 0, 1920, 1080 }, color, 0.1)

Screen.List

Returns one entry per connected monitor. Use #Screen.List() for the monitor count. Each entry:

Field	Type	Description
`index`	number	Monitor index
`x`	number	Top-left X in virtual desktop coordinates
`y`	number	Top-left Y in virtual desktop coordinates
`width`	number	Monitor width in pixels
`height`	number	Monitor height in pixels
`primary`	boolean	Whether this is the primary monitor

for _, m in ipairs(Screen.List()) do
  Log.Info(
    "Monitor "
      .. m.index
      .. ": "
      .. m.width
      .. "x"
      .. m.height
      .. (m.primary and " (primary)" or "")
  )
end

Screen.Capture

Captures a display live and returns a lossless PNG plus the geometry needed to map image pixels back to screen coordinates. This is the primitive behind screenshot-driven automation (see the remote-control protocol’s screen.capture). opts (all optional):

display: 1-based index from Screen.List(). Defaults to the display under the cursor.
region: {x, y, w, h} in that display’s local coordinates. Defaults to the full display; clamped to the display’s bounds.
max_edge: optional. Downscale the returned PNG so its longer side is at most this many pixels, preserving aspect ratio. Omit for native resolution. Use it to keep base64 frames small in screenshot-heavy loops, for example a remote-control server passing max_edge = 1280 so a 4K capture doesn’t overrun the script’s memory limit.

Returns:

Field	Type	Description
`image`	string	Base64 lossless PNG of the captured pixels: native resolution, or downscaled when `max_edge` is set.
`width` / `height`	number	Pixel dimensions of the returned frame, after any `max_edge` downscale.
`display`	table	`{index, x, y, width, height, primary}` with a signed virtual-desktop origin, so monitors left of / above the primary are addressable.
`cursor`	table	`{x, y}` in screen coordinates, read together with the frame.

local cap = Screen.Capture() -- display under the cursor
local cap = Screen.Capture({ display = 2 }) -- a specific monitor
local cap = Screen.Capture({ region = { x = 0, y = 0, w = 320, h = 240 } })
Log.Info(
  "captured "
    .. cap.width
    .. "x"
    .. cap.height
    .. " from display "
    .. cap.display.index
)

Screen.FindImage

Captures a display live, like Screen.Capture, and scans it for a needle image. Inside Run() the capture and scan run on a worker thread and the coroutine yields; outside a coroutine the call raises an error.

needle: path to a PNG, relative to the script directory. Pixels with alpha below 128 match anything, so cut a needle with a transparent background to ignore what is behind it.
opts (all optional): display and region as in Screen.Capture, plus tolerance, 0.0 to 1.0 (default 0.0 = exact). Per-channel percentage of 255, the same scale as SearchForColor. scales is a list of 1 to 8 ratios, 0.1 to 10, the needle is resampled by before scanning (default { 1 }).
Returns {x, y, width, height} of the first match in screen coordinates, or nil. Scales are tried in the order given, and within one scale the scan runs top-left to bottom-right, so list the most likely ratio first.

The needle is compared at native pixel scale. Cut it from a Screen.Capture frame on the display you target and it matches with no options. When the same needle must work on another display, pass scales: a needle cut on a 2x Retina display finds its 1x rendering with scales = { 1, 0.5 }, a 1x needle finds pixel-doubled game UI with scales = { 1, 2 }. Each ratio costs one extra scan. Resampling softens edges, so start at tolerance = 0.1 and raise it until the needle hits, then confirm with Screen.Capture that the hit is the target and not a flat region. Icons and text that the OS renders separately per DPI, such as the macOS Dock or Windows text at 125%, are not resamples of each other and may never match across scales. Windows display scaling is not visible to the runtime, so a Windows needle is always compared at ratio 1 unless you pass scales.

Run(function()
  local hit = Screen.FindImage("ok-button.png", { tolerance = 0.05 })
  if hit then
    HID.MoveTo(hit.x + hit.width / 2, hit.y + hit.height / 2)
    HID.Press("Mouse1")
  end
end)

Window

Window manipulation functions. Handles are integer values obtained from Window.Find() or Window.List(). Passing nil for a handle targets the active (foreground) window. See Platforms for implemented calls and unsupported-call errors.

macOS Accessibility: Window.Activate and Window.Move require Rebind to hold the macOS Accessibility grant. Having this grant does not enable unimplemented Window calls. On macOS Window.Move targets the frontmost focused window; the handle is advisory.

Query

Function	Returns	Description
`Window.Find(title)`	number?	Find first visible window whose title contains `title` (case-insensitive). Returns handle or `nil`.
`Window.List(title?)`	`{WindowEntry}`	List all visible windows. Optional title filter. Each entry has `handle`, `title`, `process`, `x`, `y`, `width`, `height`.
`Window.GetTitle(handle?)`	string	Get window title.
`Window.GetClass(handle?)`	string	Get the window class name.
`Window.GetPos(handle?)`	`{x, y, width, height}`	Get window position and size. Windows only; raises an error elsewhere.
`Window.GetPID(handle?)`	number	Get the process ID that owns the window.
`Window.IsVisible(handle)`	boolean	Check if a window is visible. Windows only; raises an error elsewhere.
`Window.IsActive(handle?)`	boolean	Check if the window is the active (foreground) window.
`Window.GetForeground()`	number?	Handle of the focused window, or `nil`.
`Window.FromPoint(x, y)`	number?	Handle of the top-level window under a screen point, or `nil`.
`Window.GetState(handle?)`	string	`"minimized"`, `"maximized"` or `"normal"`. Windows only; raises an error elsewhere.

Activation

Function	Description
`Window.Activate(handle)`	Bring window to foreground. Restores a minimized window; a maximized one stays maximized. Raises an error when the OS refuses the focus change. On macOS it brings the owning app forward and raises that app’s focused window.

Movement / sizing

Function	Description
`Window.Move(handle?, x?, y?, w?, h?)`	Move and/or resize. Omit any param to leave unchanged. Keeps the window’s place in the stacking order.

State control

Function	Description
`Window.Minimize(handle?)`	Minimize to taskbar.
`Window.Maximize(handle?)`	Maximize to full screen.
`Window.Restore(handle?)`	Restore from minimized or maximized.
`Window.Hide(handle?)`	Hide the window.
`Window.Show(handle?)`	Show a hidden window.
`Window.SetTitle(handle, title)`	Set the window title.
`Window.SetAlwaysOnTop(handle, enabled)`	Pin (`true`) or unpin (`false`) the window above others.
`Window.SetTransparency(handle, alpha)`	Set window opacity. `alpha` is 0 (transparent) to 255 (opaque).
`Window.Close(handle?)`	Graceful close (sends WM_CLOSE).
`Window.Kill(handle?)`	Force-terminate the owning process.

Window.Close asks the window to close gracefully (it may prompt to save). Window.Kill force-terminates the process that owns the window. There is no prompt and unsaved work is lost. Window.Kill can take down sibling windows in the same process. Window.SetAlwaysOnTop and Window.SetTransparency are best-effort: some fullscreen/DirectX apps repaint over them.

Waiting

Function	Returns	Description
`Window.Wait(title, timeout?)`	number?	Wait for a window to appear. Must be called inside `Run()`. Timeout in ms (default 5000). Returns handle or `nil`.
`Window.WaitActive(title, timeout?)`	boolean	Wait for a matching window to become active. Must be called inside `Run()`. Timeout in ms (default 5000). Returns `true` if it activated, `false` on timeout.
`Window.WaitClose(title, timeout?)`	boolean	Wait for a matching window to disappear. Must be called inside `Run()`. Timeout in ms (default 5000). Returns `true` if it closed, `false` on timeout.

Examples

-- find and reposition a window
local hw = Window.Find("Notepad")
if hw then
  Window.Move(hw, 0, 0, 800, 600)
  Window.Activate(hw)
end

-- list all windows
for _, w in ipairs(Window.List()) do
  Log.Info(w.title .. " [" .. w.process .. "]")
end

-- wait for an application to launch
Run(function()
  local hw = Window.Wait("Untitled - Notepad", 30000)
  if hw then
    Window.Maximize(hw)
  end
end)

App

Application-level control: the counterpart to Window (which acts on individual windows). App acts on whole applications: launch, focus, hide, quit, and query running apps. Apps are addressed by name, matched case-insensitively against the application’s display name on macOS and its executable name on Windows. Platform support: macOS and Windows. On macOS, Front, IsFront, IsRunning, and Activate are permission-free; Hide, Quit, and IsHidden drive an AppleEvent and prompt for macOS Automation permission on first use. On Windows, chrome and chrome.exe name the same app and App.Front().name returns the file name (chrome.exe). Activate focuses a visible window of a running app but does not launch one (use System.ExecDetached), Quit closes the app’s windows (an app that minimizes to the tray keeps running), and Hide and IsHidden raise an error. On Linux every call raises an error.

Function	Returns	Description
`App.Front()`	AppInfo?	The frontmost application as `{ name, pid }`, or `nil` if unknown.
`App.IsFront(name)`	boolean	Whether the frontmost app’s name contains `name` (case-insensitive).
`App.IsRunning(name)`	boolean	Whether an app matching `name` is running.
`App.IsHidden(name)`	boolean	Whether a running app matching `name` is hidden (⌘H state). macOS only. Prompts for Automation.
`App.Activate(name)`	nothing	Launch `name` if not running, then bring it frontmost. On Windows it only focuses a running app.
`App.Hide(name)`	nothing	Hide the app (⌘H semantics). macOS only. Prompts for Automation.
`App.Quit(name)`	nothing	Ask the app to quit gracefully (not a force-kill). Prompts for Automation on macOS. On Windows it closes the app’s windows.

-- toggle Terminal: activate it, or hide it if it's already frontmost
if App.IsFront("Terminal") then
  HID.Combo("cmd+h")     -- hide the frontmost app (no Automation prompt)
else
  App.Activate("Terminal") -- launch-or-focus
end

-- app-conditional logic without a per-app scoped script
local front = App.Front()
if front and front.name == "Google Chrome" then
  -- ...
end

App vs Window: use App when you mean the whole application (“activate Terminal”, “is Slack running”), and Window when you mean a specific window (find/move/resize by handle or title). For app-conditional remaps, prefer a process=-scoped script (Rebind activates/deactivates it as you switch apps) over polling App.Front() on every keypress.

Audio

Function	Returns	Description
`Audio.Beep()`	nothing	Play system beep
`Audio.Play(path, options?)`	SoundHandle	Play an audio file (WAV, MP3, OGG, FLAC). Non-blocking.
`Audio.StopAll()`	nothing	Stop all playing sounds
`Audio.SetMasterVolume(vol)`	nothing	Set master volume (0.0 to 1.0)
`Audio.GetMasterVolume()`	number	Get current master volume

Audio.Play

local sound = Audio.Play("alert.wav")
local music = Audio.Play("bgm.mp3", { volume = 0.5, loop = true })

Options:

Option	Type	Default	Description
`volume`	number	1.0	Playback volume (0.0 to 1.0)
`loop`	boolean	false	Repeat when playback finishes

File paths are relative to the script directory (same sandboxing rules as File).

SoundHandle

The object returned by Audio.Play:

Method	Returns	Description
`sound:Stop()`	nothing	Stop playback and release resources
`sound:Pause()`	nothing	Pause playback
`sound:Resume()`	nothing	Resume paused playback
`sound:IsPlaying()`	boolean	True if playing (not paused, not finished)
`sound:SetVolume(vol)`	nothing	Set per-sound volume (0.0 to 1.0)
`sound:GetVolume()`	number	Get current per-sound volume

Always call Audio.StopAll() in OnStop and OnBlur to clean up playing sounds.

Clipboard

Read and write the system clipboard. See Platforms for platform support and unsupported-call errors.

Function	Returns	Description
`Clipboard.Get()`	string?	Read current clipboard text. Returns `nil` if empty or non-text.
`Clipboard.Set(text)`	nothing	Set clipboard text.

-- paste a multi-line message into a chat app
local msg = "Line one\nLine two\nLine three"
Clipboard.Set(msg)
HID.Combo("LCtrl+V")

-- read clipboard contents
local text = Clipboard.Get()
if text then
  Log.Info("Clipboard: " .. text)
end

Clipboard paste is the most reliable way to input multi-line or long text. Applications handle pasted newlines correctly, and there are no per-character timing concerns.

Process

Query and manage system processes.

Function	Returns	Description
`Process.Exists(name)`	number?	Find first process matching `name` (case-insensitive substring). Returns PID or `nil`.
`Process.List(name?)`	`{ProcessEntry}`	List processes. Optional name filter. Each entry has `pid` and `name`.
`Process.Kill(pid)`	boolean	Force-kill a process by PID. Returns `true` if killed, or `false` (never errors) when no such PID exists or the OS denies the kill (e.g. an elevated or another-user process).

-- check if an application is running
local pid = Process.Exists("notepad")
if pid then
  Log.Info("Notepad is running (PID " .. pid .. ")")
end

-- list all chrome processes
for _, p in ipairs(Process.List("chrome")) do
  Log.Info(p.name .. " [" .. p.pid .. "]")
end

Dialog

Native OS dialogs for messages, confirmations, and file selection. All functions must be called inside Run(): they yield the coroutine while the dialog is open. Input processing, timers, and other coroutines continue running uninterrupted.

Linux/BSD: requires Zenity, KDialog, or YAD to be installed.

Message and confirm

Function	Returns	Description
`Dialog.Message(text, options?)`	nothing	Show an alert box. Yields until dismissed.
`Dialog.Confirm(text, options?)`	boolean	Show a yes/no dialog. Returns `true` if the user clicked Yes.

Options: { title?: string, level?: string } level controls the icon: "info" (default), "warning" (alias "warn"), or "error". Matching is case-insensitive, and any unrecognized value falls back to "info".

Run(function()
  Dialog.Message("Script finished.", { title = "Done" })

  local ok = Dialog.Confirm(
    "Overwrite existing file?",
    { title = "Confirm", level = "warning" }
  )
  if not ok then
    return
  end
end)

File dialogs

Function	Returns	Description
`Dialog.OpenFile(options?)`	string?	Pick a single file. Returns path or `nil` if cancelled.
`Dialog.OpenDir(options?)`	string?	Pick a directory. Returns path or `nil` if cancelled.
`Dialog.SaveFile(options?)`	string?	Choose a save location. Returns path or `nil` if cancelled.

Options: { title?: string, location?: string, filters?: { { name: string, extensions: { string } } } }

location: initial directory the dialog opens in.
filters: restrict the file types shown. Each entry has a display name and a list of extensions (without leading dot).

Run(function()
  -- open a single Lua file
  local path = Dialog.OpenFile({
    title = "Open Script",
    filters = {
      { name = "Lua Scripts", extensions = { "lua", "luau" } },
    },
  })
  if path then
    local code = File.Read(path)
  end

  -- save a file
  local dest = Dialog.SaveFile({
    title = "Save As",
    location = File.GetScriptDir(),
    filters = {
      { name = "JSON", extensions = { "json" } },
    },
  })
  if dest then
    File.WriteJSON(dest, data)
  end

  -- pick a directory
  local dir = Dialog.OpenDir({ title = "Select Output Folder" })
  if dir then
    Log.Info("Output: " .. dir)
  end
end)

Regex

Pattern matching using Rust regex syntax. It is backtracking-free and does not support lookaround or backreferences. Use [[ ]] long strings for patterns to avoid Luau escape interpretation: [[\d+]] instead of "\\d+".

Function	Returns	Description
`Regex.IsMatch(text, pattern)`	boolean	Test if text matches the pattern
`Regex.Find(text, pattern)`	table?	First match with captures, or nil
`Regex.FindAll(text, pattern)`	`{table}`	All matches with captures
`Regex.Replace(text, pattern, rep)`	string	Replace first match
`Regex.ReplaceAll(text, pattern, rep)`	string	Replace all matches
`Regex.Split(text, pattern)`	`{string}`	Split text on pattern

Match result

Regex.Find and Regex.FindAll return tables with:

{
  match = "full matched text",
  captures = { "group1", "group2" }, -- positional capture groups
  start = 8, -- 1-indexed byte offset of match start
  finish = 11, -- 1-indexed byte offset of match end
}

Replacement syntax

Replacements use $1, $2, etc. for capture group references:

Regex.ReplaceAll("John Smith", [[(\w+) (\w+)]], "$2, $1") --> "Smith, John"

Examples

-- test a pattern
if Regex.IsMatch(win.process, "discord|slack|teams") then
  -- chat app behavior
end

-- extract data
local m = Regex.Find("Price: 500g", [[(\d+)g]])
if m then
  local amount = tonumber(m.captures[1]) --> 500
end

-- split CSV
local fields = Regex.Split("a,b,,d", ",") --> {"a", "b", "", "d"}

Note: Luau also has built-in Lua patterns (string.find, string.match, string.gmatch) which use different syntax (%d instead of \d). The Regex namespace uses standard regex syntax and supports features Lua patterns lack: alternation (|), counted repetition ({2,4}), and more.

Config

Read and write TOML configuration files. TOML is a superset of INI for common use cases: simple key = value files work as-is, with support for typed values (booleans, numbers, strings), arrays, and nested tables.

Function	Returns	Description
`Config.ParseTOML(text)`	table	Parse a TOML string into a Lua table
`Config.ToTOML(table)`	string	Serialize a Lua table to a TOML string
`Config.ReadTOML(path)`	table	Read and parse a TOML file
`Config.WriteTOML(path, table)`	nothing	Serialize and write a TOML file

File paths are relative to the script directory (same sandboxing rules as File).

-- settings.toml:
-- [general]
-- sensitivity = 0.8
-- enabled = true
-- profile = "default"

local cfg = Config.ReadTOML("settings.toml")
Log.Info(cfg.general.sensitivity) --> 0.8
Log.Info(cfg.general.profile) --> "default"

-- modify and save
cfg.general.sensitivity = 1.0
Config.WriteTOML("settings.toml", cfg)

For JSON config files, use the File.ReadJSON / File.WriteJSON functions in the File namespace.

Env

Environment variables and known user folders.

Variables

Function	Returns	Description
`Env.Get(name)`	string?	Read an environment variable. `nil` if unset.
`Env.Set(name, value)`	nothing	Set an environment variable for this process and its children.

Env.Set mutates the Rebind process-wide environment: the change is visible to Env.Get in every other running script and to any later System.Exec / System.ExecDetached, and persists until Rebind exits. It is not scoped to your script. Prefer File / Config for per-script state.

Known folders

Each returns an absolute path, or nil if the location cannot be determined. Env.Temp is the exception: it always returns a string.

Function	Returns	Description
`Env.Home()`	string?	User home directory
`Env.Config()`	string?	User config directory
`Env.Data()`	string?	User data directory
`Env.Desktop()`	string?	Desktop directory
`Env.Documents()`	string?	Documents directory
`Env.Downloads()`	string?	Downloads directory
`Env.AppData()`	string?	Application data directory
`Env.Temp()`	string	System temporary directory (always present)

These paths point outside the File sandbox. Use them for informational purposes (such as a Dialog.OpenFile start location), not for sandboxed File.* operations.

local downloads = Env.Downloads()
local path = Dialog.OpenFile({ location = downloads })

Pipe

Shared memory IPC for communicating with external processes (Python, Node.js, etc). Windows only. Returns an error on macOS and Linux (POSIX shared memory support planned).

Opening

local pipe = Pipe.Open(name, options?)

Creates or opens a shared memory region backed by the OS object Local\Rebind_<name>, the tag an external process opens (so Pipe.Open("vision") maps Local\Rebind_vision). The name must be 1 to 64 characters of ASCII letters, digits, -, or _. The size option (default 65536) is rounded up to the next power of two, then clamped between 1024 and 16 MiB, so pipe.size (and pipe.capacity = size/2 − 12) may exceed what you requested.

Methods

Method	Returns	Description
`pipe:Read()`	string or nil	Read latest data from external process. `nil` if nothing new.
`pipe:Write(data)`	nothing	Write data for external process to read
`pipe:Close()`	nothing	Release shared memory

Properties

Property	Type	Description
`pipe.name`	string	Pipe name
`pipe.size`	number	Total shared memory size
`pipe.capacity`	number	Max payload size per message

Wire protocol

The region is split into two fixed channels so both sides can read and write without locking: the script writes to channel A (offset 0) and reads from channel B (offset size / 2). An external peer does the inverse: it writes to channel B and reads from channel A. Each channel is a 12-byte header followed by the payload:

Bytes	Field
`0..8`	`u64` sequence number, little-endian (bumped on every write)
`8..12`	`u32` payload length, little-endian
`12..`	payload bytes (up to `pipe.capacity` = `size/2 − 12`)

A writer lays down the payload, then the length, then the sequence number last (a release barrier); a reader compares the sequence to the one it last saw and only reads when it changed. Each channel is a single slot, last-writer-wins. It is not a queue, so an unread message is overwritten by the next write. Pace writes to the reader’s poll interval. Working Python, Rust, and Node peers are included in the SDK’s examples.

Registry

Read and write the Windows registry. Windows only. Every function raises an error on macOS and Linux.

Function	Returns	Description
`Registry.Read(keyPath, valueName)`	string or number	Read a value. Returns a string or number depending on the value type.
`Registry.Write(keyPath, type, valueName, value)`	nothing	Write a typed value.
`Registry.DeleteValue(keyPath, valueName)`	nothing	Delete a single value.
`Registry.DeleteKey(keyPath)`	nothing	Delete a key and all its subkeys (recursive).
`Registry.CreateKey(keyPath)`	nothing	Create a key.

keyPath begins with a hive: HKLM / HKEY_LOCAL_MACHINE, HKCU, HKCR, HKU, or HKCC. Registry.Write accepts a type of REG_SZ, REG_DWORD, REG_QWORD, REG_EXPAND_SZ, REG_MULTI_SZ, or REG_BINARY.

Registry.CreateKey([[HKCU\Software\MyScript]])
Registry.Write([[HKCU\Software\MyScript]], "REG_SZ", "Profile", "default")

local profile = Registry.Read([[HKCU\Software\MyScript]], "Profile")
Log.Info(profile) --> "default"

Registry.DeleteKey([[HKCU\Software\MyScript]])

Script

Function	Description
`Script.Exit(reason?)`	Stop the current script. Optional reason is logged.
`Script.Reload()`	Reload the current script from disk

Globals: exit(reason?) and die(reason?) are aliases for Script.Exit.

die("shutting down for maintenance")

Bind

Declarative key binding as an alternative to writing OnDown/OnUp handlers.

-- simple binding (action on press, key is blocked by default)
local handle = Bind("F10", function()
  HID.Type("Hello!")
end)

-- explicitly pass the key through to the PC
local handle = Bind("F10", function()
  Log.Info("F10 was pressed")
  return true -- pass through (must be explicit)
end)

-- binding with condition, press, and release handlers
local handle = Bind("Mouse1", {
  when = function()
    return Input.IsDown("LAlt") -- only activate when Alt is held
  end,
  action = function()
    Log.Info("pressed")
  end,
  release = function()
    Log.Info("released")
  end,
})

-- toggle a UI boolean on keypress
local handle = Bind.Toggle("F9", "enabled")

-- simple remap (no logic needed)
local handle = Bind.Remap("Mouse4", "4")

Blocking

Bind blocks by default. This is the opposite of OnDown/OnUp.

Return value	`OnDown`/`OnUp`	`Bind` action
`return true`	pass through	pass through
`return false`	block	block
no return / `nil`	pass through	block

Most binds remap or trigger actions where blocking the original key is what you want. To pass the key through, you must explicitly return true. When using Async() with Bind, the wrapper always returns false (block) immediately when it spawns the coroutine. Any return value inside the coroutine body has no effect on propagation. The decision was already made.

Handle

Handle methods: handle:unbind(), handle:disable(), handle:enable(), handle.enabled (read-only).

Routing

Keys claimed by Bind do not reach OnDown/OnUp. If a bind’s when guard returns false, the key falls through to the next bind or to OnDown/OnUp.

Selective interception

Bind triggers are declared data, so Rebind intercepts only those keys at the OS level. Every other key stays outside the bind’s interception path, and device-level tools (Keyboard Maestro, Karabiner) keep working alongside your script. This is the key advantage over an OnDown handler that inspects key itself: defining OnDown forces system-wide interception (see Input hooks). The trigger string is captured when Bind() runs. Bind(cfg.hotkey, …) reads the saved value of a UI.Keybind field at load, but rebinding it later in the config panel takes effect on the next script restart, not live.

Modeline

A modeline at the top of a script sets its configuration. A directly-run script must declare min_sdk: in its modeline, or in its package’s rebind.toml (any script under a package root inherits [package].min_sdk; see Package format). Rebind refuses to run a plaintext script with no declared Rebind version. Every other key is optional and falls back to its default. (require’d modules are loaded through their parent script and are not gated.) Inside a package, rebind.toml overrides the modeline; see Package format. Three comment forms are accepted. The multi-line block is the recommended header. One rebind: line per setting reads cleanly as a script grows, and it is the exact form Rebind suggests on failure:

-- multi-line block (recommended)
--[[
  rebind: min_sdk=3.4.1
  rebind: name=My Script
  rebind: process=chrome.exe process=firefox.exe
  rebind: exclude_window_regex="private|incognito"
]]

-- single-line, best for one or two keys
-- rebind: min_sdk=3.0.0 name="My Script" tick_rate=8000

-- inline block
--[[ rebind: min_sdk=3.0.0 name="My Script" tick_rate=8000 ]]

Values may be unquoted (ending at the next space) or wrapped in " or ' to include spaces and =: name="My Script". Inside a quoted value, escape its quote and backslashes as \" and \\. A string-valued key alone on its own line (as in the block form) takes the rest of the line, so rebind: name=My Script needs no quotes. Repeatable keys may appear on separate lines or together on one line. Unknown keys are ignored. Scripts using regex or exclusion targeting must declare min_sdk=3.4.1 or newer so an older Rebind build refuses them instead of ignoring their scope.

Property	Type	Default	Description
`name`	string	filename	Display name
`version`	string	`"0.0.0"`	Script version
`author`	string	none	Creator attribution
`description`	string	none	Brief explanation
`min_sdk`	string	required	Minimum Rebind version the script needs. Must be numeric (partials allowed: `3` means `3.0.0`; a leading `v` and any pre-release/build suffix are ignored). Rebind refuses to run a plaintext script that omits it or asks for a version newer than the installed build.
`window`	string	none	Window-title match (repeatable, case-insensitive substring)
`process`	string	none	Process-name match (repeatable, case-insensitive)
`window_regex`	regex	none	Window-title regular expression (repeatable, case-insensitive)
`process_regex`	regex	none	Process-name regular expression (repeatable, case-insensitive)
`exclude_window`	string	none	Deactivate when the window title contains this value (repeatable, case-insensitive)
`exclude_process`	string	none	Deactivate when the process name contains this value (repeatable, case-insensitive)
`exclude_window_regex`	regex	none	Deactivate when the window title matches this regular expression (repeatable, case-insensitive)
`exclude_process_regex`	regex	none	Deactivate when the process name matches this regular expression (repeatable, case-insensitive)
`tick_rate`	number	1000	`OnTick` frequency in Hz (max 8000)
`z_index`	integer	1	Input priority (higher sees input first)
`instance`	string	`"replace"`	`"replace"`, `"single"`, or `"multiple"`
`mouse_mode`	string	`"relative"`	`"relative"` or `"absolute"`
`mouse_block`	boolean	`false`	When `true`, `OnMove` can block by returning `false`; when `false`, moves forward immediately and `OnMove` fires asynchronously. Requires a Rebind device: software mode cannot suppress mouse movement. (Note: defining `OnMove` at all requires a device, even without this key.)
`key_block`	boolean	`true`	When `true` (default), a script defining `OnDown`/`OnUp` captures keys exclusively: every key is intercepted so the script can block or transform any of it. When `false`, the script is a pure observer: the hooks still fire, but keys pass through as untouched hardware events (device-level tools like Keyboard Maestro keep working) and return values cannot block them. `Bind` triggers are intercepted selectively either way.
`hardware_only`	boolean	`false`	When `true`, the script waits for authenticated hardware mode before loading. Accepts `true`/`1`/`yes`.
`macro`	boolean	`false`	Marks a recorded macro file, whose chunk returns its actions. Running it adds Play hotkey, Playback speed, and Mouse movement scale to its Options, then plays the macro once and stops, or arms the play hotkey. A `require` of it returns the actions and runs nothing else. Accepts `true`/`1`/`yes`.
`permission`	string	none	Restrict the script’s access (repeatable): `exec`, `net`. See Permissions below.
`memory_limit_mb`	integer	8	Luau VM heap cap in MB. Raise it for image-heavy scripts (e.g. a remote-control server marshaling base64 screen captures) that would otherwise hit the default 8 MB limit.
`platforms`	list	none	Operating systems the script supports, comma separated: `windows`, `macos`, `linux`. Undeclared means all three. Rebind refuses to load the script on a platform it does not list; the marketplace does not filter by it yet, so state the platform in the README too.

Positive window and process rules combine with OR. With no positive rules, the script is active for every focused window. Any matching exclusion deactivates it, even when a positive rule also matches. Exclusion-only configs therefore mean “active everywhere except here.” Regular expressions use Rust regex syntax. Lookaround and backreferences are not supported. Invalid or empty expressions stop the script from loading instead of widening its scope. The former id key is deprecated and ignored. UI state now persists automatically by file path.

Permissions

A script that declares no permission= line holds every permission. The moment any permission= line is present, the script switches to allow-list mode: only the listed permissions are granted, so permission=net alone also denies exec, and vice-versa. To declare that a script needs nothing, give the key an empty value or none:

-- rebind: min_sdk=3.0.0
-- rebind: permissions=none

Both spellings behave identically. permission= and permissions= each accept one value or a comma-separated list, and every line adds to the set, so permissions=net,exec and two singular lines are the same thing. An empty value or none resets to the empty set, so a later “needs nothing” wins over an earlier grant. In a package, permissions = [] in rebind.toml means the same. Omitting the key entirely is the only state that grants everything. There is no difference between permission= and permissions=none: both deny. Only exec and net actually gate anything; any other permission= value grants nothing real but still flips the script into allow-list mode. A denied call fails as a runtime error when it runs (e.g. Net.Get() requires 'net' permission), not as a load-time refusal, so a gated call inside a branch only fails when reached.

--[[
  rebind: min_sdk=3.0.0
  rebind: permission=exec
  rebind: permission=net
]]

Permission	Gates
`exec`	`System.Exec` and `System.ExecDetached`
`net`	the `Net` namespace (HTTP client, `Net.Listen`, and WebSocket)

Nothing else is gated. File, Registry, Process, Clipboard, Env, Input, HID, and Macro have no permission check: they work the same whether or not the modeline declares permissions. File paths are still confined to the script directory, but that is path resolution, not a permission. Declare the minimum permissions a script needs.

Key reference

Key names are case-insensitive. "F1" and "f1" are identical. Use these strings with HID.Down, HID.Up, HID.Press, Bind, and in OnDown/OnUp hooks.

Transport key support

Named keys are USB HID usages, not characters. The operating system’s active keyboard layout decides which glyph a usage produces. Text handling differs by transport:

Software mode gives HID.Type text to the operating-system output backend. Unicode and layout behavior therefore follows that backend.
Rebind Link output converts each character to a USB HID usage. On Windows it consults the active keyboard layout when a matching HID usage exists. On macOS and Linux it uses a US-layout map for letters, digits, common punctuation, newline, and tab.
Unsupported hardware-mode characters may not type. macOS software mode can fall back to Unicode text for characters without a keycode mapping, but that is not a portable hardware guarantee.

For arbitrary Unicode or long text, use Clipboard.Set plus the platform paste shortcut where Clipboard is supported. Test layout-sensitive scripts on every target layout and transport.

Letters

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Numbers

0 1 2 3 4 5 6 7 8 9

Function keys

F1 through F24. F13-F24 are HID output only (they work with HID.Press but will not appear in OnDown/OnUp hooks).

Mouse buttons

Button	Name
Left click	`Mouse1`
Right click	`Mouse2`
Middle click	`Mouse3`
Back	`Mouse4`
Forward	`Mouse5`

Modifiers

Key	Name	Aliases
Left Ctrl	`LCtrl`	`Ctrl`, `Control`
Right Ctrl	`RCtrl`
Left Shift	`LShift`	`Shift`
Right Shift	`RShift`
Left Alt / Option	`LAlt`	`Alt`, `Opt`, `Option`
Right Alt	`RAlt`
Left Win / Cmd	`LWin`	`Win`, `GUI`, `Windows`, `Command`, `Cmd`, `Meta`, `LMeta`
Right Win / Cmd	`RWin`	`RGui`, `RMeta`

Editing and control

Key	Name	Aliases
Enter	`Enter`	`Return`
Escape	`Escape`	`Esc`
Backspace	`Backspace`
Tab	`Tab`
Space	`Space`
Caps Lock	`CapsLock`

Key	Name	Aliases
Insert	`Insert`
Delete	`Delete`	`Del`
Home	`Home`
End	`End`
Page Up	`PageUp`	`PgUp`
Page Down	`PageDown`	`PgDn`
Arrow Up	`Up`
Arrow Down	`Down`
Arrow Left	`Left`
Arrow Right	`Right`

System

Key	Name	Aliases
Print Screen	`PrintScreen`	`Print`, `PrintScr`, `PrtSc`
Scroll Lock	`ScrollLock`
Pause / Break	`Pause`	`Break`
Application / Menu	`Menu`	`App`, `ContextMenu`

Punctuation

These names refer to the physical key, regardless of shift state.

Key	Name	Aliases
`-` / `_`	`Minus`
`=` / `+`	`Equal`	`Equals`
`[` / `{`	`LeftBracket`	`LeftBrace`, `LBracket`
`]` / `}`	`RightBracket`	`RightBrace`, `RBracket`
`\` / `\|`	`Backslash`
`;` / `:`	`Semicolon`
`'` / `"`	`Apostrophe`	`Quote`
` / `~`	`Grave`	`Backtick`, `Tilde`
`,` / `<`	`Comma`
`.` / `>`	`Period`	`Dot`
`/` / `?`	`Slash`

Numpad

Key	Name	Aliases
Num Lock	`NumLock`
Numpad /	`KpDivide`	`NpDivide`
Numpad *	`KpMultiply`	`NpMultiply`, `KpAsterisk`
Numpad -	`KpMinus`	`NpSubtract`
Numpad +	`KpPlus`	`NpAdd`
Numpad Enter	`KpEnter`	`NpEnter`
Numpad .	`KpDot`	`NpDecimal`, `NpDot`
Numpad 0-9	`Kp0` through `Kp9`	`NP0`-`NP9`, `Numpad0`-`Numpad9`

Media keys (HID output only)

These can be sent via HID.Press but will not appear in input hooks.

Key	Name	Aliases
Next Track	`MediaNext`	`MediaNextTrack`
Previous Track	`MediaPrev`	`MediaPrevTrack`
Stop	`MediaStop`
Play / Pause	`MediaPlay`	`MediaPlayPause`
Volume Up	`VolumeUp`	`VolUp`
Volume Down	`VolumeDown`	`VolDown`
Mute	`Mute`	`VolumeMute`

​Globals

​Run

​Sleep

​After

​Async

​require

​_REBIND

​Hooks

​Lifecycle

​Input

​Observers

​Other (reserved, not yet dispatched)

​System

​System.TypeText

​System.Exec

​System.ExecDetached

​HID

​Keyboard

​Combos

​Usages

​Mouse

​Joypad

​Mouse mode

​Input

​UI

​Schema

​Widgets

​Widget options

​Other

​Persistence

​Macro

​Playback

​Hardware streaming

​Recording

​Format

​Timer

​Math

​Random

​Transforms

​JSON

​Hash

​Codec

​Log

​File

​Net

​Client

​HTTP server

​WebSocket server

​WebSocket client

​UDP

​Screen

​Screen.SearchForColor

​Screen.List

​Screen.Capture

​Screen.FindImage

​Window

​Query

​Activation

​Movement / sizing

​State control

​Waiting

​Examples

​App

​Audio

​Audio.Play

​SoundHandle

​Clipboard

​Process

​Dialog

​Message and confirm

​File dialogs

​Regex

​Match result

​Replacement syntax

​Examples

​Config

​Env

​Variables

​Known folders

​Pipe

Globals

Run

Sleep

After

Async

require

_REBIND

Hooks

Lifecycle

Input

Observers

Other (reserved, not yet dispatched)

System

System.TypeText

System.Exec

System.ExecDetached

HID

Keyboard

Combos

Usages

Mouse

Joypad

Mouse mode

Input

UI

Schema

Widgets

Widget options

Other

Persistence

Macro

Playback

Hardware streaming

Recording

Format

Timer

Math

Random

Transforms

JSON

Hash

Codec

Log

File

Net

Client

HTTP server

WebSocket server

WebSocket client

UDP

Screen

Screen.SearchForColor

Screen.List

Screen.Capture

Screen.FindImage

Window

Query

Activation

Movement / sizing

State control

Waiting

Examples

App

Audio

Audio.Play

SoundHandle

Clipboard

Process

Dialog

Message and confirm

File dialogs

Regex

Match result

Replacement syntax

Examples

Config

Env

Variables

Known folders

Pipe