cowpager(1)

📦 version 0.3, in fedora 44

💖 cowpager(1) 💖

okay bestie, sit down, because this is the cowpager page from the cow manual family and it's genuinely iconic. it's a lil graphical pager. it's cute. it slays. let's go. 🐄✨

✨ SYNOPSIS ✨

cowpager [-f path] [-r rows] [-c cols] [-m mon[,mon...]] [-1] [-h]
[first last]

🌸 DESCRIPTION 🌸

so cowpager is a small graphical pager — a whole vibe check for your desktops — and what it does is display the desks that cow is tracking, plus all the windows sitting on them. by default, each desk gets drawn as one canvas holding the full visible monitor layout. it's giving very much FvwmPager energy, specifically the FvwmPager that isn't tracking one specific monitor.

and if you pass no options at all? it just shows every desk and every window across every output. lowkey generous of it. 🫶

on startup, cowpager goes looking for cowpager.conf at $XDG_CONFIG_HOME/cow/cowpager.conf, or at ~/.config/cow/cowpager.conf if that first one isn't the one — but only when the file actually exists. and heads up: command-line options override whatever settings got loaded from the config file. command line stays the main character. 👑

💅 OPTIONS 💅

  • -f PATH — load the config from PATH instead of the default location. and here's the tea: a missing default file is fine and chill, but a missing explicit file is an error. so if you point at it, it better be there. 😭
  • -r ROWS — arrange the desks in ROWS rows. if you only give -r, then the number of columns gets computed from the number of desks.
  • -c COLS — arrange the desks in COLS columns. if you only give -c, then the number of rows gets computed from the number of desks. and when neither -r nor -c shows up? all desks get arranged in a single row. periodt.
  • -m LIST — restrict the pager to just the listed outputs. LIST is one or more output names or selectors, separated by commas (like -m HDMI-A-1,@2). the selectors are @N, @current, @next, and @prev, and they mean exactly the same thing as they do in cow(1). monitor labels appear in the order you gave them on the command line, so the order you type it is the order you get it. 💅

when -m names a single output, cowpager tracks that output: the page grid gets scaled to that monitor instead of to the full monitor layout.

without -m, all outputs are shown the way cow manages them. go peek at cow(1) -- OUTPUT MANAGEMENT.

  • -1 — display only the currently active desk. that's it. that's the flag. minimalism. ✨
  • first last — display desks first through last, inclusive. for example, cowpager 0 3 shows desks 0, 1, 2, and 3. inclusive, bestie, we don't leave anybody out. 🎀
  • -h — print usage and exit. classic.

🎀 CONFIGURATION 🎀

the config file uses the same simple, whitespace-separated format as cowbuttons. double-quoted strings are supported, and # starts a comment — but only outside quoted strings, so don't come for me when your # inside quotes doesn't comment anything.

top-level options act as defaults. a config may also contain named pager blocks, and those get selected by top-level show pager lines. each top-level show pager line creates one cowpager window:

show pager main
show pager compact

pager main {
     columns 4
     desks 0 3
     monitors HDMI-A-1,DP-1
}

pager compact {
     current-only true
     monitors DP-1
}

when no show pager line is present, only the top-level options are used. when a pager block is selected, the options inside that block override the top-level defaults. and you can list multiple names on one show pager line — the matching blocks get combined into that one instance, in the order they're encountered in the file. iykyk. 🦋

supported layout commands:

rows 2
columns 4
desks 0 3
monitors HDMI-A-1,DP-1
current-only false
desktop-labels true
monitor-labels true
label-highlight true
desktop-scale 32
window-icons true
window-icon-size 16

monitors selects the outputs shown by this pager. use a single output name or selector to track one monitor, or a comma-separated list to show several outputs in the given order. it accepts the same selectors as -m. ✨

desks selects the desks shown by this pager. the range is inclusive, so desks 0 3 shows desks 0, 1, 2, and 3. and it is mutually exclusive with current-only true: setting desks clears current-only mode, and setting current-only true clears the desk range. they cannot both be the main character. pick one. 💅

window-icons controls whether application icons get drawn in window miniatures (default: true). window-icon-size sets their maximum square size in pixels (default: 16). an icon is centred in its window miniature, and it automatically gets reduced even further whenever the miniature is too small for the configured size. shrinking to fit, we love a flexible queen. 🎀

supported colour roles:

style background 0xffffff
style desk.bg 0xffffff
style desk.active.border 0x4d9ef2
style page.bg 0xffffff
style page.active.bg 0x3366b3
style label.bg 0xd8d8d8
style label.active.bg 0x3366b3
style label.fg 0x000000
style label.inactive.fg 0x000000
style window.bg 0x60a0c0
style window.border 0x000000
style window.focused.bg 0xf7c733
style viewport.bg 0x00000000
style viewport.border 0xda70d6

colours may be opaque 0xRRGGBB values, or 0xRRGGBBAA values carrying an alpha component. every background layer has its own colour. for example, this makes the pager's principal backgrounds dark grey at 80 percent opacity:

style background 0x282828CC
style desk.bg 0x282828CC
style page.bg 0x282828CC
style page.active.bg 0x458588CC
style label.bg 0x282828CC
style label.active.bg 0x458588CC

by default, cowpager derives these colours from cow's current configured theme. the output background becomes the pager background when one is configured; otherwise the inactive titlebar or tab colour is used. active/inactive titlebar or tab colours are used for highlights and labels. any style line in cowpager.conf overrides the derived value for that role. so like, it has taste, but you can absolutely overrule its taste. 💖

background is the default colour for the whole pager surface, including desk and page backgrounds. desk.bg, page.bg, and page.active.bg may be set when those areas should differ. desk.active.border controls the frame around the active desk.

window.bg gives every unfocused window miniature the same colour. when it is not set, cowpager retains its default behaviour of deriving a stable colour from each window identifier. window.focused.bg controls the focused window miniature, and window.border controls miniature outlines.

viewport.bg and viewport.border override the monitor-derived fill and outline used to mark the currently visible viewport. a fully transparent viewport.bg, such as 0x00000000, leaves the active page colour unchanged. sneaky but valid. 🙈

🦋 DISPLAY 🦋

DESKTOP AND MONITOR LABELS

each desk cell has a desktop label. when more than one output is shown, a second monitor-label row gets drawn below it. hence:

  • the desktop label identifies the desk;
  • each monitor label identifies an output;
  • a monitor label is highlighted on the desk that output currently views;
  • when only one output is shown, the desktop label itself is highlighted for the active desk.

the monitor label is the output's name when it fits, falling back to its cow-assigned number when the name would overflow the slot. so if your output name is doing too much, it gets a number instead. relatable honestly. 😭

PAGE GRID AND VIEWPORTS

window miniatures are placed on the grid and coloured by their id. when CoW has resolved an application icon, cowpager centres it inside the corresponding miniature. the same effective icon.image is used for desktop icons and the pager, so decoration profiles and rules can override or disable the image for particular windows. the focused window is drawn in yellow by default. 💛

without -m, the page grid is scaled to the bounding box of all shown outputs. window miniatures and viewport rectangles are placed using the physical monitor layout, so adjacent monitors appear adjacent in the pager instead of overlapping. no accidental overlap chaos, we stay organised. 🫶

for every output currently viewing a desk, a translucent rectangle marks that output's viewport position within that desk's page grid.

⭐ EXAMPLES ⭐

show every output and every desk (the default):

cowpager &

limit the pager to two specific outputs, arranged in two rows:

cowpager -r 2 -m HDMI-A-1,DP-1 &

use a custom config file:

cowpager -f ./cowpager.conf &

single-output pager pinned to DP-1, showing only the active desk:

cowpager -1 -m DP-1 &

show desks 0 through 3:

cowpager 0 3 &

🔥 SEE ALSO 🔥

cow(1) — go read it, bestie, it's the whole reason any of this works. 💜

👑 AUTHORS 👑

Thomas Adam

okay so that's the whole page, and as a lil sign-off: this is version 0.3, dated 2026-09-07, and it's the cowpager(1) manual. slay, stay paged, and go arrange some desks. 🐄💖✨

📦 where this page comes from