Set refresh.mode to event, interval, or manual. Interval mode also requires seconds, from 1 to 86,400. Add an optional event name to refresh the item with sbar trigger <event>. You can also trigger an item by its ID.
For example, hold a CPU reading until the system-status event or the item’s ID is triggered:
{
"id": "cpu",
"type": "cpu",
"refresh": { "mode": "manual", "event": "system-status" }
}
sbar trigger system-status
Use "refresh": { "mode": "interval", "seconds": 30 } to update the displayed reading every 30 seconds instead. Manual items capture an initial provider value; they do not start empty while waiting for a trigger.
Sampling versus display refresh
Without refresh, native items follow their shared provider. An explicit event policy follows changes too. Interval and manual policies keep a snapshot for each item. They do not change how often the provider samples data. Native metrics still share a two-second sampling interval. A trigger normally captures the latest shared value, rather than forcing a hardware query. AeroSpace and Yabai items with manual or event refresh instead request a fresh query and capture its completed snapshot; interval refresh uses the latest polled state. Date and time snapshots capture the current time.
Mail queries Apple Mail when enabled and waits 30 seconds after each completed read before polling again. Item refresh settings control snapshots and do not change that polling schedule.
Commands run at startup even in manual mode. An interval reruns the command after the previous execution finishes and the interval elapses. Matching triggers coalesce for 50 milliseconds, replace a running command, and restart its interval schedule. Plugins stream updates at their own rate, regardless of the item refresh policy. The bar queues up to 32 triggers per plugin. It drops new triggers when the queue is full, while waiting to restart, or after a one-shot process exits. Each new process receives a fresh mailbox with start first.
Providers and commands pause during sleep and restart after wake.
Configuration reloads
Adding or removing an unrelated provider keeps existing native providers running. Their playback state, metric history, and sampling baselines remain available. For example, adding a clock does not reset an existing media item to Waiting for playback.
Native refresh snapshots and interval timing survive a reload when the item’s id, type, refresh settings, and disk path are unchanged. Styling edits, text-template edits, and changes to other items do not refresh a held reading. Templates render fields from that same snapshot. A new item or a change to its type, refresh policy, or disk path captures a new snapshot for that item. Removing its refresh policy returns it to live provider updates.
These rules apply to configuration reloads, not a process restart. Restarting the bar starts providers and captures initial values again.
Runtime commands
Start the bar
Run sbar or sbar start to start the bar with ~/.config/sbar/config.json. Both accept --config <path> for another configuration file. The process keeps running until you stop it.
Client commands connect to ~/.config/sbar/control.sock by default. A bar started with --config creates control.sock beside that file. Pass --socket <path> after the client subcommand to target that bar:
sbar start --config /path/to/config.json
In another terminal:
sbar query --socket /path/to/control.sock
sbar stop --socket /path/to/control.sock
Only one instance can own a given socket, and clients must run as the same user. A custom configuration filename in the same directory still uses the same socket. If a client reports Cannot connect to sbar, check that the bar is running and that --socket points to its configuration directory.
Run sbar --help or sbar <command> --help for help. Client commands and validation return a nonzero exit status on failure.
Validate configuration
sbar validate
sbar validate --config /path/to/config.json
Validation works without a running bar. It reads the default file unless you pass --config, reports invalid or missing files, and never writes to the file. See configuration for the required fields.
Query state
sbar query [--diagnostics | --displays] [--socket <path>]
query returns the running configuration as JSON. --diagnostics returns the configuration path, current configuration error, last action error, and up to 100 recent runtime events. --displays returns connected display IDs, names, and whether each is primary. Use only one of these flags at a time.
Reload configuration
sbar reload [--socket <path>]
Reload the file immediately. Invalid configuration returns an error and retains the last valid configuration.
Update items
sbar set <item-id> <property> <value> [--socket <path>]
sbar reads values as JSON when possible and as strings otherwise. For example:
sbar set clock enabled false
sbar set clock style '{"tint":"#88C0D0"}'
set changes in-memory configuration only. Supported properties are symbol, enabled, priority, format, dateStyle, timeStyle, style, and popup. Edit the configuration file to make changes persistent. A successful reload or restart discards these temporary changes.
Setting style replaces the item’s whole style object. Omitted fields then inherit from the theme. Use sbar set clock style null to clear all item style overrides. text, symbolPosition, provider blocks, actions, children, and refresh settings require a configuration-file edit.
Trigger events
sbar trigger <event> [<json>] [--socket <path>]
sbar trigger refresh '{"source":"manual"}'
Matching item IDs or refresh event names update native snapshots or rerun command items. Triggers are offered to running plugins, subject to their mailbox and lifecycle limits. The optional payload must be valid JSON and is included in runtime events and plugin input.
Subscribe to events
sbar subscribe [--socket <path>]
Streams JSON lines for configuration changes, provider values, and triggers until interrupted. Slow subscribers are disconnected.
Stop the bar
sbar stop [--socket <path>]
stop acknowledges the request, then shuts down the bar, stops providers and child processes, closes panels, and removes the control socket. Use --socket to target an instance started with a custom configuration directory.