The sketchybarrc Configuration File

All of SketchyBar's configuration is managed through a single executable file, sketchybarrc. This file is simply a shell script that runs a series of sketchybar commands to set up your bar, its items, and their properties.

Location

By default, SketchyBar looks for the configuration file at the following location:

~/.config/sketchybar/sketchybarrc

You can also specify a different configuration file at launch time using the --config or -c flag:

sketchybar --config /path/to/my/custom_config

Structure

The sketchybarrc file is executed from top to bottom. It typically follows this structure:

  1. Global Bar Settings: Define the bar's position, height, color, etc., using sketchybar --bar ....
  2. Default Item Settings: Set default properties for all subsequent items using sketchybar --default ... to avoid repetition.
  3. Item Creation: Add all your desired items (--add item, --add space, etc.) and set their specific properties (--set <name> ...).
  4. Event Subscriptions: Subscribe items to events so they can update dynamically (--subscribe <name> <event>).

See the Quick Start guide for a detailed walkthrough of the default sketchybarrc.

Execution and Permissions

SketchyBar executes this file directly. Therefore, the sketchybarrc file must have execute permissions.

chmod +x ~/.config/sketchybar/sketchybarrc

Environment Variables in Scripts

When SketchyBar runs a script associated with an item (via the script or click_script property), it provides several helpful environment variables.

  • $NAME: The name of the item that triggered the script. This is crucial for updating the correct item from within the script. 

    # In a script, update the label of the item that ran it
sketchybar --set "$NAME" label="New Value"

  • $SENDER: The name of the event that triggered the script. This can be a system event like volume_change, a custom event, or special values like routine (for update_freq triggers) and forced (for manual triggers).

  • $INFO: Contains event-specific information. For example, for the front_app_switched event, $INFO will contain the name of the new frontmost application.

  • $SELECTED: This is specific to space components. It will be true if the space is currently active on its display, and false otherwise.

  • $CONFIG_DIR: An absolute path to the directory containing your sketchybarrc file (e.g., ~/.config/sketchybar). This is useful for reliably locating plugin scripts. The default configuration uses this to define a PLUGIN_DIR variable: 

    PLUGIN_DIR="$CONFIG_DIR/plugins"
sketchybar --set my_item script="$PLUGIN_DIR/my_script.sh"