cowbuttons(1)

📦 version 0.3, in fedora 44

👑 cowbuttons(1) — the button panel bestie for cow 💖

okay so. cowbuttons is a little button panel that lives inside your cow window manager setup, and honestly? it's giving main character energy. ✨

🌸 NAME 🌸

cowbuttons — Button panel for the cow window manager 🎀

✨ SYNOPSIS ✨

cowbuttons [-c config] [-h]

💅 DESCRIPTION 💅

cowbuttons puts up a small, configurable grid of cells, and every cell is doing something cute. A cell can:

  • run cow(1) commands when you click it 🔥
  • periodically show the output of a script, like a lil live widget 🦋
  • display selected state pulled from cow's status socket 👑
  • or just be an empty spacer, vibing, holding space 💀

now, important lore: Wayland does not do X11 window reparenting, so cowbuttons does not swallow clients. periodt. So instead of eating your apps, you use command buttons to launch or focus applications, and you use cow rules to style or place companion windows. iykyk. 💜

🌈 OPTIONS 🌈

  • -c config — load config instead of the default configuration file. (custom config? obsessed.)
  • -h — show usage. the "help me bestie" flag 🫶

🎀 CONFIGURATION 🎀

the format is line-oriented. blank lines and lines starting with # are ignored (they're just there for the aesthetic 🌸). labels and commands that contain whitespace must be quoted. no cap.

colours can be opaque 0xRRGGBB values, or 0xRRGGBBAA values carrying an alpha component. in that second form, 00 is fully transparent and FF is fully opaque. for example, style button.bg 0x282828CC uses an 80-percent opaque dark grey. slay. 💅

  • cell W H — set the default cell size in pixels. the default is 96 by 32.
  • grid rows cols — set the grid size.
  • col col width N — set one column's width in pixels.
  • show panel name [...] — show one or more named panel definitions from the configuration file. multiple names on the same show panel line get combined into one cowbuttons window. multiple top-level show panel lines create separate cowbuttons windows from the same configuration file. and settings outside panel blocks can be used as shared defaults. very reusable, very iconic. ✨
  • panel name [direction [property value ...]] { — start a named panel definition. a panel is loaded when it's named by show panel. when direction is left, right, up, or down, cowbuttons adds an attached handle and opens the panel in that direction. pressing the handle collapses or expands the panel. handle properties use the same styling keys as button. 👑
  • row [height N] { ... } — start a new visual row. cells inside the block are appended left-to-right.
  • if [not] command name { ... } — process the block only when name exists in PATH and is executable.
  • if [not] file path { ... } — process the block only when path exists. relative paths are resolved against the configuration file's directory.
  • if [not] env name { ... } — process the block only when the environment variable name is set and non-empty.
  • font name — set the font face used for labels.
  • resizable true|false — allow the window to be resized. the configured grid remains the minimum size; extra width and height are distributed across columns and rows. the default is false.
  • style button.bg colour — set the normal button background colour.
  • style button.bg_pressed colour — set the pressed button background colour.
  • style button.fg colour — set the normal button text colour.
  • style button.fg_pressed colour — set the pressed button text colour.
  • style button.image path — draw a PNG, SVG, or XPM image in command buttons. relative paths are resolved against the configuration file's directory.
  • style button.image_pressed path — draw a PNG, SVG, or XPM image while a command button is pressed.
  • style button.image_size N — set the image size in pixels. the default is 16.
  • style button.image_position left|center|right|fill — set where button images are drawn. the default is left.
  • style button.justify left|center|right — set the default button text justification. the default is left.
  • button label command [property value ...] — create a clickable button. command is sent to cow as its left-click action. supported properties are width, height, span, bg, bg_pressed, fg, fg_pressed, image, image_pressed, image_size, image_position, justify, and the click-action properties described below. 🔥
  • leftclick command, click command, middleclick command, rightclick command — set the single-click action for the specific button. click is an alias for leftclick.
  • doubleclick command, leftdoubleclick command, middledoubleclick command, rightdoubleclick command — set a double-click action. doubleclick is an alias for leftdoubleclick. when both single- and double-click actions exist for the same button, the single-click action is delayed for 300 ms. (yes, 300 ms of suspense 😭)
  • script command interval seconds [property value ...] — create a cell whose label is supplied by an external command. the command is run through the shell immediately after startup and then again the configured number of seconds after each run finishes. runs never overlap. 🦋

the first line written to standard output, limited to 255 bytes, replaces the cell's label when the command exits successfully. empty output clears the label. if the command fails, the previous successful label is retained and an error is written to standard error.

script cells support the same click actions, styling, and geometry properties as button cells.

  • external command [property value ...] — create a panel slot managed by an external command. the command is started when the panel is opened and terminated when it is collapsed. external panels start collapsed. this is a lifecycle hook for cow modules; generic Wayland clients are still separate toplevels. supported properties are width, height, span, bg, bg_pressed, fg, fg_pressed, image, image_pressed, image_size, image_position, and justify.
  • status type [property value ...] — create a live status cell. supported types are: focused-title, focused-app, current-output, current-desk, and desk-list. 👑
  • spacer [property value ...] — create an empty cell.

💖 EXAMPLES 💖

show panel launcher
show panel telephone
show panel pager
show panel statusbar

resizable true

style button.bg 0x39414a
style button.bg_pressed 0x242a30
style button.fg 0x1f2933
style button.fg_pressed 0xffffff
style button.image_size 18

panel launcher {
     cell 118 30
     grid 2 4

     row height 30 {
          button "Terminal" "exec xterm" bg 0xcde7d8 image cowbuttons/svg/terminal.svg
          button "Firefox" "exec firefox" bg 0xffddc8 image cowbuttons/svg/browser.svg
          button "Files" "exec thunar" bg 0xffe4ad image cowbuttons/svg/files.svg
          button "Editor" "exec emacs" bg 0xded7f5 image cowbuttons/svg/editor.svg
     }

     row height 30 {
          button "Next" "focus -n" bg 0xf6e2a6
          button "Prev" "focus -p" bg 0xcfe8db
     }
}

panel telephone left bg 0xf2d6a6 {
     cell 42 28
     grid 5 3

     row height 22 {
          button "Telephone" "nop" span fill bg 0xe8d9f2
     }
}

panel pager right bg 0x3f5b51 {
     external "cowpager" width 420 height 120 bg 0x242a30
}

panel statusbar {
     cell 140 30
     grid 1 2

     row {
          script "~/.local/bin/clock.sh" interval 1 click "exec gsimplecal" justify center
          script "~/.local/bin/battery.sh" interval 30 justify center
     }
}

remove cowbuttons' own window decors using a cow rule:

decor -d cowbuttons-nodecor border.width 0
decor -d cowbuttons-nodecor border.handles false
decor -d cowbuttons-nodecor titlebar.enabled false
rule -g -Ton-map -ncowbuttons-chrome -s %cowbuttons decor -a cowbuttons-nodecor

🍓 FILES 🍓

  • $XDG_CONFIG_HOME/cow/cowbuttons.conf
  • ~/.config/cow/cowbuttons.conf

🧚 SEE ALSO 🧚

cow(1), moocow(1), cowbar(1), cowiconman(1), cowpager(1)

💜 AUTHORS 💜

Thomas Adam <thomas@xteddy.org>

and that's the whole page bestie!! this was cowbuttons version 0.3, dated 2026-09-07 💖 go forth and build the cutest lil button grid, you absolute icon 👑✨🌈

📦 where this page comes from