Event data in shell scripts

Shell scripts run in zsh and receive event details as environment variables.

CRANK_EVENT_SOURCE, CRANK_EVENT_KIND, and CRANK_EVENT_TIMESTAMP are always set.

Each trigger adds its own: a USB event sets deviceName, Wi-Fi sets networkName, Calendar sets eventTitle and minutesUntil.

Rate limiting

Set a cooldown period on a rule to avoid triggering it multiple times in a short window.

File system events and battery percentage changes can come in bursts. Without a limit, one blip could run your action ten times before it finishes.

Time window scheduling

Limit a rule to a time window and specific days of the week.

A Bluetooth rule that runs a setup script can be set to only fire on weekday mornings.

Compound conditions

Build AND/OR conditions to control exactly when a rule fires.

Scope a Bluetooth rule to a specific device name, a file watcher to a filename pattern, or a battery rule to a percentage range. The action only runs when all conditions pass.

Rule groups

Rules can be organized into named groups. Group by device, project, or workflow.

Hardware-aware

Triggers that need specific hardware only appear on compatible devices.

Lid and ambient light triggers won't show up on a Mac Pro or Mac mini.

Event log

Every trigger event is recorded with its source, kind, values, and timestamp.

Good for figuring out what your Mac is reacting to, or why a rule did or didn't fire.

Action history

Shell script output, exit codes, and errors are saved per run.

If something triggered but didn't behave as expected, this is where to look.

Triggers

Crank listens for system events across 15 categories:

Bluetooth — device connected, device disconnected, Bluetooth on/off
Wi-Fi — network connected, network disconnected, Wi-Fi on/off
USB — device connected, device disconnected
Power — battery percentage, charging started/stopped, login, standby
Displays — monitor connected, monitor disconnected, number of monitors changed
Lid (MacBook only) — lid opened or closed
Ambient Light (MacBook only) — light level changed, crossed a lux threshold
Application — app launched, app quit, app focused
Time — a specific time of day reached
Calendar — event upcoming, event started
File Watcher — file created, deleted, or modified in a watched directory
Download — any file downloaded, or a file matching a pattern
Screenshot — screenshot taken
Clipboard — item added to clipboard, specific content type detected
Camera — camera activated or deactivated

Actions

Each rule runs one action when it fires:

Shell Script — run any zsh script, with event details available as environment variables
AppleScript — execute an AppleScript snippet
Shortcuts — run a macOS Shortcut by name
Notification — post a system notification with a custom title and body
Launch App — open an application
Open URL — open a URL in the default browser or a specific app
Open File — open a file, optionally with a specific app

Use cases

Run a script when a Bluetooth headset connects to switch the audio output
Mount a network drive automatically when joining a specific Wi-Fi network
Send a notification when a long-running download finishes
Launch an app when a USB device is plugged in
Adjust system settings when the laptop lid opens or closes
Dim displays or pause music when the screen locks
Trigger a build or deployment when a file changes in a watched directory
Run cleanup scripts at a specific time each day

How it works

Crank registers native listeners for macOS system events using CoreBluetooth, IOBluetooth, FSEvents, IOKit, and others. When an event fires and its conditions match, the action runs.

Shell scripts execute via /bin/zsh with your .zshrc sourced automatically, so your PATH, aliases, and functions are available.

Crank

React to macOS events

automate your frustrations away