Core Concepts

SketchyBar's power comes from its dynamic and script-driven nature. Understanding these core concepts is key to creating a powerful and personalized status bar.

The Command-Line Interface (CLI)

Everything in SketchyBar is controlled through its command-line interface. You add, remove, and configure items by sending commands to the running SketchyBar process. This is typically done from your sketchybarrc configuration file but can also be done from any terminal.

The basic syntax is:

sketchybar <command> <arguments...>
  • --add: Creates new elements like items, spaces, or events.
  • --set: Modifies the properties of existing elements.
  • --subscribe: Links an item to an event, causing its script to run when the event occurs.
  • --bar: Configures global settings for the bar itself.

Items: The Building Blocks

Everything you see on the bar is an item. An item can be a simple text label, an icon, or a more complex component like a graph or a space indicator.

Item Anatomy

An item is composed of several configurable parts:

  • Icon: A text or symbol, often from a Nerd Font.
  • Label: A text string, typically for displaying information.
  • Background: A colored and styled background for the item.
  • Popup: An optional menu that appears when the item is clicked.

Each of these parts has its own set of properties (e.g., icon.color, label.font, background.corner_radius).

The images/bar_item.svg file in the repository provides a helpful visual diagram of the different padding and height properties an item has.

Item Types (Components)

While most items are created with --add item, SketchyBar offers specialized components with unique behaviors:

  • Item: The standard component for text and icons.
  • Space: Integrates with macOS Mission Control spaces.
  • Alias: Displays an official macOS menu bar extra.
  • Graph: Renders a line graph from a series of data points.
  • Slider: An interactive, draggable slider.
  • Bracket: (Also called a Group) A special item that acts as a background for a collection of other items.

Properties

Properties control the appearance and behavior of items. You modify them using the --set command:

# Syntax: sketchybar --set <item_name> <property>=<value> ...

sketchybar --set cpu_usage label.color=0xffff0000 label="High Load!"

Properties are namespaced. For example:

  • label.color sets the label's color.
  • icon.font sets the icon's font.
  • background.height sets the item's background height.
  • popup.blur_radius sets the blur radius for the item's popup menu.

For a complete list of all available commands and properties, see the CLI Reference.

Scripting and Events

Scripting is at the heart of SketchyBar. You use scripts to fetch data and update the appearance of your bar items.

How it Works

  1. Assign a Script: You assign a script to an item using the script property. 

    sketchybar --set my_item script="/path/to/my/script.sh"

  2. Trigger the Script: The script can be triggered in two main ways:

    • By Timer (update_freq): The script runs at a regular interval. 

      # Run the script every 5 seconds
sketchybar --set my_item update_freq=5

    • By Event (--subscribe): The script runs only when a specific event occurs. 

      # Run the script whenever the system volume changes
sketchybar --subscribe my_item volume_change

  3. Update the Item: Inside your script, you update the item's properties by calling sketchybar --set again. SketchyBar provides an environment variable, $NAME, which holds the name of the item that triggered the script. 

    # Inside your script.sh
#!/bin/sh
sketchybar --set "$NAME" label="Updated!"

This event-driven model is highly efficient because scripts only run when they absolutely need to. For more details, see the Events documentation.