Skip to main content

Events & Scripting

Events and Scripting

All items can subscribe to arbitrary events; when the event happens, all items subscribed to the event will execute their script. This can be used to create more reactive and performant items which react to events rather than polling for a change.

sketchybar --subscribe <name> <event> ... <event>

where the events are:

front_app_switchedWhen the front application changes (not triggered if a different window of the same app is focused)front application name
space_changeWhen the active mission control space changesJSON for active spaces on all displays
display_changeWhen the active display is changednew active display id
volume_changeWhen the system audio volume is changednew volume in percent
brightness_changeWhen a displays brightness is changednew brightness in percent
power_source_changeWhen the devices power source is changednew power source (AC or BATTERY)
wifi_changeWhen the device connects of disconnects from wifinew WiFi SSID or empty on disconnect
media_changeWhen a change in now playing media is performed (experimental)media info in a JSON structure
system_will_sleepWhen the system prepares to sleep
system_wokeWhen the system has awaken from sleep
mouse.enteredWhen the mouse enters over an item
mouse.exitedWhen the mouse leaves an item
mouse.entered.globalWhen the mouse enters over any part of the bar
mouse.exited.globalWhen the mouse leaves all parts of the bar
mouse.clickedWhen an item is clickedmouse button and modifier info
mouse.scrolledWhen the mouse is scrolled over an itemscroll wheel delta
mouse.scrolled.globalWhen the mouse is scrolled over an empty region of the barscroll wheel delta

Some events send additional information in the $INFO variable When an item is subscribed to these events the script is run and it gets passed the $SENDER variable, which holds exactly the above names to distinguish between the different events. It is thus possible to have a script that reacts to each event differently e.g. via a switch for the $SENDER variable in the script.

Alternatively a fixed update_freq can be --set, such that the event is routinely run to poll for change, the $SENDER variable will in this case hold the value routine.

When an item invokes a script, the script has access to some environment variables, such as:


Where $NAME is the name of the item that has invoked the script and $SENDER is the reason why the script is executed. The variable $CONFIG_DIR contains the absolute path of the directory where the current sketchybarrc file is located.

If an item is clicked the script has access to the additional variables:


where the $BUTTON can be left, right or other and specifies the mouse button that was used to click the item, while the $MODIFIER is either shift, ctrl, alt or cmd and specifies the modifier key held down while clicking the item.

If an item receive a scroll event from the mouse the script gets send the additional $SCROLL_DELTA variable.

All scripts are forced to terminate after 60 seconds and do not run while the system is sleeping.

Creating custom events

This allows to define events which are triggered by arbitrary applications or manually (see Trigger custom events). Items can also subscribe to these events for their script execution.

sketchybar --add event <name> [optional: <NSDistributedNotificationName>]

Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g. the notification Spotify sends on track change: com.spotify.client.PlaybackStateChanged (example), or the notification sent by the system when the screen is unlocked: (example) to create more responsive items. Custom events that subscribe to NSDistributedNotificationCenter notifications will receive additional notification information in the $INFO variable if available. For more NSDistributedNotifications see this discussion.

Triggering custom events

This triggers a custom event that has been added before

sketchybar --trigger <event> [Optional: <envvar>=<value> ... <envvar>=<value>]

Optionally you can add environment variables to the trigger command witch are passed to the script, e.g.:

sketchybar --trigger demo VAR=Test

will trigger the demo event and $VAR will be available as an environment variable in the scripts that this event invokes.

Forcing all shell scripts to run and the bar to refresh

This command forces all scripts to run and all events to be emitted, it should never be used in an item script, as this would lead to infinite loops. It is prominently needed after the initial configuration to properly initialize all items by forcing all their scripts to run

sketchybar --update