cowbar(1)

NAME

cowbar - relay cow window manager status updates

SYNOPSIS

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

DESCRIPTION

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 is intended to be used as a data source for status bars such as waybar(1) or i3bar(1).

With no options, the full snapshot is relayed verbatim. The -o option filters snapshots to a single named output. The -f option extracts a single field from each snapshot.

cowbar retries the socket connection up to 30 times (once per second), allowing it to be started concurrently with cow during session initialisation without requiring ordering guarantees.

OPTIONS

-o output
    Filter snapshots to the named output. 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:

    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.

    outputs
        Emit the full outputs array on each update.

-n
    When used with -w desks, render desk names instead of numbers (falls back to the number when a desk has no name).

-h
    Print usage and exit.

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
      }
    }

-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 outputs output:

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

ENVIRONMENT

XDG_RUNTIME_DIR
    Used to locate the status socket. Must be set.

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.

FILES

$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

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

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

SEE ALSO

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

AUTHORS

Thomas Adam <thomas@xteddy.org>