SketchyBar

https://felixkratz.github.io/SketchyBar/
Admin
SketchyBar is a highly customizable macOS menu bar application, enabling users to configure items...
Tokens:7,665
Snippets:132
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install SketchyBar via Homebrew

Source: https://felixkratz.github.io/SketchyBar/setup

Tap the custom Homebrew repository and install SketchyBar. This is the recommended installation method.

```bash
brew tap FelixKratz/formulae
brew install sketchybar
```

--------------------------------

### Start SketchyBar Service

Source: https://felixkratz.github.io/SketchyBar/setup

Starts the SketchyBar service to run the bar automatically at system startup using Homebrew services.

```bash
brew services start sketchybar
```

--------------------------------

### Copy Default Configuration and Plugins

Source: https://felixkratz.github.io/SketchyBar/setup

Copies the default SketchyBar configuration file and example plugins to the appropriate directories. Ensure these directories exist.

```bash
mkdir -p ~/.config/sketchybar/plugins
cp $(brew --prefix)/share/sketchybar/examples/sketchybarrc ~/.config/sketchybar/sketchybarrc
cp -r $(brew --prefix)/share/sketchybar/examples/plugins/ ~/.config/sketchybar/plugins/
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://felixkratz.github.io/SketchyBar/setup

Installs the necessary command line developer tools for compiling software on macOS. This is a prerequisite for compiling SketchyBar from source.

```bash
xcode-select --install
```

--------------------------------

### Trigger Custom Event with Environment Variables

Source: https://felixkratz.github.io/SketchyBar/config/events

Example of triggering a custom event named 'demo' and setting an environment variable 'VAR' to 'Test'.

```bash
sketchybar --trigger demo VAR=Test
```

--------------------------------

### Install SF Symbols Font

Source: https://felixkratz.github.io/SketchyBar/config/tricks

Install the SF Symbols font package using Homebrew to access Apple's symbol icons.

```bash
brew install --cask sf-symbols
```

--------------------------------

### Load Custom Font

Source: https://felixkratz.github.io/SketchyBar/setup

Loads a font file from a specified path. Use this if you are using a font not installed in a standard system directory.

```bash
sketchybar --load-font <path>
```

--------------------------------

### Install Hack Nerd Font

Source: https://felixkratz.github.io/SketchyBar/setup

Installs the Hack Nerd Font, which is the default font for SketchyBar. Install this if you experience missing icons.

```bash
brew install --cask font-hack-nerd-font
```

--------------------------------

### Uninstall SketchyBar via Homebrew

Source: https://felixkratz.github.io/SketchyBar/setup

Removes SketchyBar and its associated Homebrew tap. This is the standard method for uninstalling if installed via Homebrew.

```bash
brew uninstall sketchybar
brew untap FelixKratz/formulae
```

--------------------------------

### Compile SketchyBar from Source

Source: https://felixkratz.github.io/SketchyBar/setup

Compiles the SketchyBar project from its source code using the 'make' command. This generates a universal binary.

```bash
make
```

--------------------------------

### Run SketchyBar from Command Line

Source: https://felixkratz.github.io/SketchyBar/setup

Launches SketchyBar directly from the command line. Use this for testing or with verbose output.

```bash
sketchybar
```

--------------------------------

### Run SketchyBar with Custom Config

Source: https://felixkratz.github.io/SketchyBar/setup

Launches SketchyBar using a configuration file located at a specified path, overriding the default location.

```bash
sketchybar --config <path>
```

--------------------------------

### Query Display Configuration Information

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve information about the current display configuration of your system.

```bash
sketchybar --query displays
```

--------------------------------

### Query Default Properties

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve information about the current default settings in SketchyBar.

```bash
sketchybar --query defaults
```

--------------------------------

### Configure item icon properties

Source: https://felixkratz.github.io/SketchyBar/config/items

Set the icon for an item and its text properties.

```bash
sketchybar --set item_name icon=
```

```bash
sketchybar --set item_name icon.color=0xffffffff
```

```bash
sketchybar --set item_name icon.font.size=14.0
```

--------------------------------

### Query Item Properties

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve information about a specific item's configuration. Replace `<name>` with the item's name. The output is a JSON structure.

```bash
sketchybar --query <name>
```

--------------------------------

### Batch Multiple SketchyBar Commands

Source: https://felixkratz.github.io/SketchyBar/config/tricks

Combine several individual SketchyBar configuration commands into a single call to reduce startup times and clean up your configuration file. Ensure no whitespace follows the backslash when joining lines.

```bash
sketchybar --bar position=top 
sketchybar --bar margin=5 
sketchybar --add item demo left 
sketchybar --set demo label=Hello 
sketchybar --subscribe demo system_woke  

```

```bash
sketchybar --bar position=top           \
                 margin=5               \
           --add item demo left         \
           --set demo label=Hello       \
           --subscribe demo system_woke  

```

--------------------------------

### Configure item label properties

Source: https://felixkratz.github.io/SketchyBar/config/items

Set the label for an item and its text properties.

```bash
sketchybar --set item_name label="My Label"
```

```bash
sketchybar --set item_name label.color=0xff000000
```

```bash
sketchybar --set item_name label.font.family=Arial
```

--------------------------------

### Create a Symlink for Multiple SketchyBar Instances

Source: https://felixkratz.github.io/SketchyBar/config/tricks

Use this command to create a symbolic link for the SketchyBar binary, allowing you to run multiple independent instances with different configurations.

```bash
ln -s $(which sketchybar) $(dirname $(which sketchybar))/bottom_bar  

```

--------------------------------

### Make Scripts Executable

Source: https://felixkratz.github.io/SketchyBar/config/tricks

Ensure your scripts have execute permissions before running them with SketchyBar.

```bash
chmod +x script.sh
```

--------------------------------

### Query Bar Properties

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve information about the bar's configuration settings. The output is a JSON structure.

```bash
sketchybar --query bar
```

--------------------------------

### Query Event Properties

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve information about the events that SketchyBar is handling.

```bash
sketchybar --query events
```

--------------------------------

### Basic Animation Command

Source: https://felixkratz.github.io/SketchyBar/config/animations

Use this command to animate transitions between values for bar properties or set commands. Specify the animation curve and duration.

```bash
sketchybar --animate <curve> <duration> \
           --bar <property>=<value> ... <property>=<value> \
           --set <name> <property>=<value> ... <property>=<value>
```

--------------------------------

### Add Item Alias

Source: https://felixkratz.github.io/SketchyBar/config/components

Creates an alias for a default macOS menu bar item. Requires screen capture permissions.

```bash
sketchybar --add alias <application_name> <position>
```

--------------------------------

### Setting Popup Menu Properties

Source: https://felixkratz.github.io/SketchyBar/config/popups

Use this command to configure various properties of a popup menu associated with a bar item. This allows control over drawing, layout, and visual appearance.

```bash
sketchybar --set <name> popup.<popup_property>=<value>
```

--------------------------------

### Configure item scripting properties

Source: https://felixkratz.github.io/SketchyBar/config/items

Define scripts to run on events or clicks, and control update frequency.

```bash
sketchybar --set item_name script="~/.config/sketchybar/my_script.sh"
```

```bash
sketchybar --set item_name click_script="echo 'clicked'"
```

```bash
sketchybar --set item_name update_freq=10
```

```bash
sketchybar --set item_name updates=when_shown
```

```bash
sketchybar --set item_name mach_helper="com.example.helper"
```

--------------------------------

### Configure text properties for items

Source: https://felixkratz.github.io/SketchyBar/config/items

Customize the appearance and behavior of text within an item, including color, font, and scrolling.

```bash
sketchybar --set item_name drawing=off
```

```bash
sketchybar --set item_name highlight=on
```

```bash
sketchybar --set item_name color=0xff00ff00
```

```bash
sketchybar --set item_name highlight_color=0xffffffff
```

```bash
sketchybar --set item_name y_offset=2
```

```bash
sketchybar --set item_name font="SF Pro:Regular:13.0"
```

```bash
sketchybar --set item_name font.family=Helvetica
```

```bash
sketchybar --set item_name font.style=Italic
```

```bash
sketchybar --set item_name font.size=12.5
```

```bash
sketchybar --set item_name string="Status"
```

```bash
sketchybar --set item_name scroll_duration=200
```

```bash
sketchybar --set item_name max_chars=20
```

```bash
sketchybar --set item_name width=150
```

```bash
sketchybar --set item_name align=center
```

```bash
sketchybar --set item_name background.border_width=2
```

```bash
sketchybar --set item_name shadow.color=0x80000000
```

--------------------------------

### Clone SketchyBar Repository

Source: https://felixkratz.github.io/SketchyBar/setup

Clones the SketchyBar source code from its GitHub repository. This is the first step for compiling from source.

```bash
git clone https://github.com/FelixKratz/SketchyBar.git
```

--------------------------------

### Make Plugin Executable

Source: https://felixkratz.github.io/SketchyBar/setup

Ensures that a SketchyBar plugin script has execute permissions. This is required for plugins to run correctly.

```bash
chmod +x name/of/plugin.sh
```

--------------------------------

### Configure Bar Properties

Source: https://felixkratz.github.io/SketchyBar/config/bar

Use this command to set global bar properties. You can adjust settings like color, position, height, and more. Changes made this way can be included in your sketchybarrc for persistence.

```bash
sketchybar --bar <setting>=<value> ... <setting>=<value>
```

--------------------------------

### Chaining Multiple Animations

Source: https://felixkratz.github.io/SketchyBar/config/animations

Chain animations by specifying multiple property changes within a single command. This allows for custom animations with keyframes and staggered animations.

```bash
sketchybar --animate sin 30 --bar y_offset=10 y_offset=0
```

--------------------------------

### Subscribe to Events

Source: https://felixkratz.github.io/SketchyBar/config/events

Subscribe an item to one or more events. When an event occurs, the item's script will execute.

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

--------------------------------

### Configure item geometry

Source: https://felixkratz.github.io/SketchyBar/config/items

Control the position, size, and visibility of an item using geometry properties.

```bash
sketchybar --set item_name drawing=on
```

```bash
sketchybar --set item_name position=left
```

```bash
sketchybar --set item_name space=1
```

```bash
sketchybar --set item_name display=active
```

```bash
sketchybar --set item_name ignore_association=on
```

```bash
sketchybar --set item_name y_offset=5
```

```bash
sketchybar --set item_name padding_left=10
```

```bash
sketchybar --set item_name padding_right=10
```

```bash
sketchybar --set item_name width=100
```

```bash
sketchybar --set item_name width=dynamic
```

```bash
sketchybar --set item_name scroll_texts=on
```

```bash
sketchybar --set item_name blur_radius=5
```

```bash
sketchybar --set item_name background.color=0xffaabbcc
```

--------------------------------

### Force All Shell Scripts and Refresh Bar

Source: https://felixkratz.github.io/SketchyBar/config/events

This command forces all scripts to run and all events to be emitted. It should never be used in an item script due to the risk of infinite loops. It is primarily needed after initial configuration to initialize all items.

```bash
sketchybar --update  

```

--------------------------------

### Move Item Before Reference

Source: https://felixkratz.github.io/SketchyBar/config/items

Move an item to appear before a specified reference item.

```bash
sketchybar --move <name> before <reference name>
```

--------------------------------

### Use Bash Arrays for SketchyBar Configuration

Source: https://felixkratz.github.io/SketchyBar/config/tricks

Rewrite SketchyBar configuration commands using bash arrays to eliminate backslashes for line continuation. This method passes the array elements directly to the SketchyBar command for a cleaner syntax.

```bash
sketchybar --bar height=32        \
                 blur_radius=30   \
                 position=top     \
                 sticky=off       \
                 padding_left=10  \
                 padding_right=10 \
                 color=0x15ffffff  

```

```bash
bar=(
  height=32
  blur_radius=30
  position=top
  sticky=off
  padding_left=10
  padding_right=10
  color=0x15ffffff
)

sketchybar --bar "${bar[@]}"  

```

--------------------------------

### Add a Graph Component

Source: https://felixkratz.github.io/SketchyBar/config/components

Use this command to add a graph component to the bar. Specify the name, position, and width. Additional properties like color and line width can be configured separately.

```bash
sketchybar --add graph <name> <position> <width in points>
```

--------------------------------

### Query macOS Menu Bar Item Names

Source: https://felixkratz.github.io/SketchyBar/config/querying

Retrieve the names of menu bar items in the default macOS bar, useful for creating aliases.

```bash
sketchybar --query default_menu_items
```

--------------------------------

### Clone Item

Source: https://felixkratz.github.io/SketchyBar/config/items

Clone an existing item, inheriting all its properties. Optionally specify position relative to the parent.

```bash
sketchybar --clone <parent name> <name> [optional: before/after]
```

--------------------------------

### Reload Sketchybar Configuration

Source: https://felixkratz.github.io/SketchyBar/config/reloading

Reloads the current Sketchybar configuration file. An optional path to a new configuration file can be provided.

```bash
sketchybar --reload [Optional: <path>]
```

--------------------------------

### Add an item to SketchyBar

Source: https://felixkratz.github.io/SketchyBar/config/items

Use this command to add a new item to the SketchyBar. Specify the item's name and its position in the bar.

```bash
sketchybar --add item <name> <position>
```

--------------------------------

### Push Data to a Graph

Source: https://felixkratz.github.io/SketchyBar/config/components

Send data points to a graph component. Data points should be floating-point numbers between 0 and 1. Multiple data points can be pushed at once.

```bash
sketchybar --push <name> <data point> ... <data point>
```

--------------------------------

### Move Item After Reference

Source: https://felixkratz.github.io/SketchyBar/config/items

Move an item to appear after a specified reference item.

```bash
sketchybar --move <name> after <reference name>
```

--------------------------------

### Add a Bracket Component with Specific Members

Source: https://felixkratz.github.io/SketchyBar/config/components

Group specific items together using a bracket component. This is useful for applying common properties, like a background, to multiple items. Members can be specified by name.

```bash
sketchybar --add bracket spaces space.1 space.2 space.3     \
           --set         spaces background.color=0xffffffff \
                                background.corner_radius=4  \
                                background.height=20  
```

--------------------------------

### Add Item Alias with Window Owner and Name

Source: https://felixkratz.github.io/SketchyBar/config/components

Creates an alias for a specific menu bar item by specifying the window owner and name. Useful when an application has multiple menu bar widgets.

```bash
sketchybar --add alias "<window_owner>,<window_name>" <position>
```

--------------------------------

### Swap Two Items

Source: https://felixkratz.github.io/SketchyBar/config/items

A specific use case of reordering to swap two items.

```bash
sketchybar --reorder <item 1> <item 2>
```

--------------------------------

### Add a Bracket Component with Regex Members

Source: https://felixkratz.github.io/SketchyBar/config/components

Group items using a bracket component with a regular expression to match member names. This is useful for dynamically bracketing items that follow a naming pattern, such as multiple space components.

```bash
sketchybar --add bracket spaces '/space\..*/'               \
           --set         spaces background.color=0xffffffff \
                                background.corner_radius=4  \
                                background.height=20  
```

--------------------------------

### Configure Space Component Script

Source: https://felixkratz.github.io/SketchyBar/config/components

Set a custom script for a space component. The script will be executed when the selection state of the associated space changes, allowing dynamic updates to the item's appearance.

```bash
sketchybar --set <name> script=<script/path>
```

--------------------------------

### Click Event Variables

Source: https://felixkratz.github.io/SketchyBar/config/events

When an item is clicked, these additional variables are available to the script.

```bash
$BUTTON
$MODIFIER
```

--------------------------------

### Remove Item

Source: https://felixkratz.github.io/SketchyBar/config/items

Completely remove an item from the configuration. The name can also be a regex.

```bash
sketchybar --remove <name>
```

```bash
sketchybar --remove /<regex>/
```

--------------------------------

### Enable/Disable Hotloading Configuration

Source: https://felixkratz.github.io/SketchyBar/config/reloading

Controls the hotload functionality, which automatically reloads the configuration file when changes are detected in its directory. Set to 'on' or 'off'.

```bash
sketchybar --hotload <boolean>
```

--------------------------------

### Configure Graph Appearance and Position

Source: https://felixkratz.github.io/SketchyBar/config/components

Set properties for a graph component, such as background color, height, and vertical offset. This allows the graph to be drawn within a specific background area and positioned accordingly.

```bash
sketchybar --set <graph name> background.color=0xff00ff00 background.height=20 y_offset=2
```

--------------------------------

### Available Event Variables

Source: https://felixkratz.github.io/SketchyBar/config/events

When a script is invoked by an event, it has access to these environment variables.

```bash
$NAME
$SENDER
$CONFIG_DIR
```

--------------------------------

### Set Default Item Properties

Source: https://felixkratz.github.io/SketchyBar/config/items

Change the default values for all subsequent items. This applies to all item properties.

```bash
sketchybar --default <property>=<value> ... <property>=<value>
```

--------------------------------

### Add a Space Component

Source: https://felixkratz.github.io/SketchyBar/config/components

Add a space component to represent a Mission Control space. This associates the item with a specific space and optionally a display. The component provides variables like $SELECTED, $SID, and $DID for scripting.

```bash
sketchybar --add space <name> <position>
```

--------------------------------

### Set item properties in SketchyBar

Source: https://felixkratz.github.io/SketchyBar/config/items

Modify properties of an existing item using its name. Multiple properties can be set in a single command.

```bash
sketchybar --set <name> <property>=<value> ... <property>=<value>
```

--------------------------------

### Trigger Custom Event

Source: https://felixkratz.github.io/SketchyBar/config/events

Manually trigger a custom event. Optionally, pass environment variables to the triggered script.

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

--------------------------------

### Rename Item

Source: https://felixkratz.github.io/SketchyBar/config/items

Rename an existing item to a new, unused name.

```bash
sketchybar --rename <old name> <new name>
```

--------------------------------

### Reorder Items

Source: https://felixkratz.github.io/SketchyBar/config/items

Reorder items by providing a new order for specified items. Only the listed items are reordered.

```bash
sketchybar --reorder <name> ... <name>
```

--------------------------------

### Add Custom Event

Source: https://felixkratz.github.io/SketchyBar/config/events

Define a new custom event. Optionally, subscribe to an NSDistributedNotificationCenter notification for automatic triggering.

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

--------------------------------

### Set Alias Scale

Source: https://felixkratz.github.io/SketchyBar/config/components

Changes the scale of an item alias.

```bash
sketchybar --set <name> alias.scale=<float>
```

--------------------------------

### Add Slider Component

Source: https://felixkratz.github.io/SketchyBar/config/components

Adds a slider component to the bar. Sliders support all regular item properties and expose additional properties for width, percentage, highlight color, and knob customization.

```bash
sketchybar --add slider <name> <position> <width>
```

--------------------------------

### Scroll Event Variable

Source: https://felixkratz.github.io/SketchyBar/config/events

When a scroll event occurs, this additional variable is available to the script.

```bash
$SCROLL_DELTA
```

--------------------------------

### Set Alias Update Frequency

Source: https://felixkratz.github.io/SketchyBar/config/components

Adapts the update interval for an item alias. By default, it updates once per second.

```bash
sketchybar --set <name> alias.update_freq=<positive_integer>
```

--------------------------------

### Set Alias Color

Source: https://felixkratz.github.io/SketchyBar/config/components

Overrides the color of an item alias using ARGB hex format.

```bash
sketchybar --set <name> alias.color=<argb_hex>
```

--------------------------------

### Modify Alpha Channel of Bar Color

Source: https://felixkratz.github.io/SketchyBar/config/types

Use this command to change the alpha channel of the bar's color. Ensure the value is a float between 0 and 1.

```bash
sketchybar --bar color.alpha=0.5
```
Tokens:
Raw