Skip to content

Quick Start

This is the shortest path from a fresh install to a working EasyBar setup.

EasyBar can start without a custom config. The built-in defaults already show a useful bar with spaces, battery, Wi-Fi, and calendar enabled. Create config.toml only when you want to customize the bar.

1. Install EasyBar

Add the Homebrew tap and install EasyBar:

brew tap easybar-app/tap
brew install --cask easybar-app/tap/easybar

The cask installs the app and CLI and starts the separately managed calendar and network agent services. Installation explains upgrades, uninstall behavior, and the component lifecycle.

2. Start EasyBar

Open the app from Finder, Spotlight, or the command line:

open -a EasyBar

The agents provide permission-sensitive calendar and network data. macOS asks for Calendar and Location permissions on behalf of the corresponding agent. EasyBar can still start without those permissions, but the related widget may show empty or denied data until access is granted.

The controller icon in the macOS menu bar can stop or restart the bar, reload configuration, restart helper agents, and open EasyBar directories. It remains available when only the bar runtime is stopped.

3. Verify the bar responds

easybar refresh

If this fails or the bar does not appear, follow the matching symptom in Troubleshooting.

4. Optional: create a custom config

EasyBar reads custom config from:

~/.config/easybar/config.toml

The EasyBarKit repository includes config.minimal.toml as a small starter override. From a cloned checkout:

mkdir -p ~/.config/easybar
cp config.minimal.toml ~/.config/easybar/config.toml
easybar config reload

See Configuration for the starter files and config path.

5. Customize built-ins first

The default bar already enables spaces, battery, Wi-Fi, and calendar. Configure native built-ins before replacing platform integrations with Lua.

For example:

[builtins.time]
enabled = true

[builtins.date]
enabled = true

[builtins.volume]
enabled = true

Reload after editing:

easybar config reload

Use Built-ins for widget behavior and Native Groups when several built-ins should share one visual container.

6. Install a ready-made widget when one exists

Search the Widget Store before writing a service integration yourself:

easybar widgets search
easybar widgets install PACKAGE_NAME
easybar config reload

Browse the Widget Store to see official packages, installation sources, updates, dependencies, and package creation.

7. Write Lua for custom behavior

Use manual Lua when you need behavior that is not already covered by a built-in or store package: custom text, local scripts, project-specific status, bespoke click handling, or unique popup content.

Create the directory if needed:

mkdir -p ~/.config/easybar/widgets

Then follow First Widget.

8. Use references when needed