cowbar(1)

📦 version 0.3, in fedora 44

💖 cowbar(1) — cow status relay 💖

okay bestie, so cowbar is a lil command from the cow(1) family, and it's literally the group chat between your cow window manager and your status bar. let's get into it 🫶

✨ NAME ✨

cowbar — relay cow window manager status updates. that's it, that's the job 💅

🌸 SYNOPSIS 🌸

cowbar [-h] [-n] [-c path] [-o output] [-f field] [-w module]

🦋 DESCRIPTION 🦋

so here's the vibe: cowbar connects to the cow(1) status socket and relays JSON state snapshots to standard output, one per line, whenever window or desk state changes. it's built to be a data source for status bars like waybar(1) or i3bar(1). no cap 💖

with no options, the full snapshot gets relayed verbatim. like, untouched, as-is, iconic behavior.

the -o option filters snapshots to a single named output.
the -f option extracts a single field from each snapshot.

and here's the bestie part: cowbar retries the socket connection up to 30 times (once per second), so you can start it concurrently with cow during session initialisation without needing any ordering guarantees. it just waits for you. loyal. 🥹

👑 OPTIONS 👑

-c path — load style and format overrides from path. the installed defaults are loaded first, and an explicit file replaces those defaults.
-o output — filter snapshots to an output name or selector. selectors are @N, @current, @next, and @prev, with the same meaning as in cow(1). when combined with -f desks, the desk information for that output is extracted. when used alone, the full state object for that output is emitted on each update.
-f field — extract a single field from each snapshot. valid values are:
- desks — emit desk state for the selected output (or the first output if -o is not given). the emitted object contains desks, current_desk, and output keys.
- focused — emit the focused window object on each update. the object includes display_title, which is already formatted by cow(1)'s title_format setting. yes bestie, the formatting is done for you, you're welcome 💅
- language — emit the active keyboard layout and keyboard lock states as a Waybar-compatible text object.
- outputs — emit the full outputs array on each update.
-n — when used with -w desks, render desk names instead of numbers. it falls back to the number when a desk has no name, because nobody should be left nameless fr fr.
-h — print usage and exit. the classic escape hatch 🙈

🎀 WAYBAR PRESENTATION 🎀

Waybar modules emitted with -w use Pango markup so that individual desks within a single custom module can have different styles. Waybar CSS can still style the custom module as a whole, but it cannot select the individual spans. sad but true.

the installed cowbar.conf supplies the default presentation. a readable $XDG_CONFIG_HOME/cow/cowbar.conf or ~/.config/cow/cowbar.conf override the defaults.

style lines 💖

style lines have the form:

style name attribute value [attribute value ...]

valid style names are desk.active, desk.collected, desk.occupied, desk.separator, page.separator, page, status, and title.

valid attributes are foreground, background, weight, style, and underline.

attribute values follow Pango markup conventions.

⚠️ quote colours beginning with #, since an unquoted # begins a comment. this one bites people, don't let it be you 🫶

the special value none clears an attribute inherited from the installed defaults.

format lines 🌈

format lines have the form:

format name "value"

the supported formats and required conversions are:

desk — one %s (desk name or number)
page — two %d values (column and row)
status — %s, %d, %s (output, active-window count, desktop configuration)
title — one %s (focused-window title)

use %% for a literal percent sign. dynamic text and configured Pango attribute values are escaped before markup is emitted.

layout 🌟

the layout command controls the order of the three desk-module elements:

layout desks page status

valid elements are desks, page, and status. each may appear at most once. omit an element to hide it. the installed default shown above preserves the traditional cowbar order.

reloading 🔄

send SIGHUP to a running cowbar process to reload its configuration. a successful reload immediately re-renders the most recent Waybar snapshot. if the new configuration is invalid, cowbar reports the error and keeps the previous configuration active. graceful queen behavior 👑

💜 OUTPUT FORMAT 💜

each line of output is a self-contained JSON object, suitable for parsing with jq(1) or any JSON library.

full snapshot (no -f):

{
  "outputs": [
    {
      "name": "DP-1",
      "desks": [...],
      "current_desk": 1
    }
  ],
  "focused": {
    "app_id": "foot",
    "title": "fish",
    "display_title": "[0123abcd] fish",
    "desk": 1
  },
  "language": {
    "name": "English (UK)",
    "caps_lock": false,
    "num_lock": true,
    "scroll_lock": false
  }
}

heads up bestie: the language.caps_lock, language.num_lock, and language.scroll_lock values are null until River has reported those states for the keyboard providing the active layout. so if you see null, that's not a bug, that's just ✨pending✨.

-f desks output:

{"desks": [...], "current_desk": 1, "output": "DP-1"}

-f focused output:

{"app_id": "foot", "title": "fish", "display_title": "[0123abcd] fish", "desk": 1}

-f language output:

{"text": "English (UK)", "caps_lock": false, "num_lock": true, "scroll_lock": false}

-f outputs output:

[{"name": "DP-1", ...}, {"name": "HDMI-A-1", ...}]

🧚 ENVIRONMENT 🧚

XDG_RUNTIME_DIR — used to locate the status socket. must be set. like, mandatory, no wiggle room 💀
WAYLAND_DISPLAY — used to qualify the default status socket name so separate CoW instances in the same runtime directory do not share a status socket. sharing is caring except when it's chaos.

🍓 FILES 🍓

/<PREFIX>/etc/cow/cowbar.conf — installed default Waybar styles and formats.
$XDG_CONFIG_HOME/cow/cowbar.conf or ~/.config/cow/cowbar.conf — optional per-user style and format overrides.
$XDG_RUNTIME_DIR/cow-$WAYLAND_DISPLAY-status.sock — status broadcast socket created by cow(1). cow writes a JSON snapshot to every connected client on each state change. if WAYLAND_DISPLAY is unset, the fallback path is $XDG_RUNTIME_DIR/cow-status.sock.

⭐ EXAMPLES ⭐

relay all state snapshots:

cowbar

filter to output DP-1:

cowbar -o DP-1

extract desk state for output DP-1:

cowbar -f desks -o DP-1

extract focused window information:

cowbar -f focused

show the current keyboard layout:

cowbar -f language

pipe into jq(1) for the title of the focused window:

cowbar -f focused | jq -r '.title // empty'

override the active desk colour while retaining all other defaults:

style desk.active foreground "#ffffff" background "#75507b"

🌈 SEE ALSO 🌈

cow(1), moocow(1), jq(1)

💖 AUTHORS 💖

Thomas Adam <thomas@xteddy.org>

and that's the whole thing bestie 🎀 this page is from cowbar 0.3, dated 2026-09-07, and it's the cowbar - cow status relay manual. go forth and relay those snapshots, you absolute icon 👑✨

📦 where this page comes from

fedora 44: cow 0.3-1.fc44 · ISC
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms