cowpager(1)
cowpager(1) cowpager - cow pager cowpager(1)

cowpager - FvwmPager-style visual pager for the cow window manager

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

cowpager is a small graphical pager that displays desks tracked by cow and the windows on them. By default, each desk is drawn as one canvas containing the full visible monitor layout, similar to FvwmPager when it is not tracking a specific monitor.

Without any options, cowpager will show all desks and windows across all outputs.

On startup, cowpager reads cowpager.conf from $XDG_CONFIG_HOME/cow/cowpager.conf or ~/.config/cow/cowpager.conf when that file exists. Command-line options override settings loaded from the config file.

-f PATH

Load configuration from PATH instead of the default location. Unlike a missing default file, a missing explicit file is an error.

-r ROWS

Arrange desks in ROWS rows. If only -r is given, the number of columns is computed from the number of desks.

-c COLS

Arrange desks in COLS columns. If only -c is given, the number of rows is computed from the number of desks. When neither -r nor -c is given, all desks are arranged in a single row.

-m LIST

Restrict the pager to the listed outputs. LIST is one or more output names or selectors separated by commas (e.g. -m HDMI-A-1,@2). Selectors are @N, @current, @next, and @prev, with the same meaning as in cow(1). Monitor labels appear in the order given on the command line.

When -m names a single output, cowpager tracks that output: the page grid is scaled to that monitor rather than to the full monitor layout.

Without -m, all outputs are shown in the way cow manages them. See cow(1) -- OUTPUT MANAGEMENT.

-1

Display only the currently active desk.

first last

Display desks first through last, inclusive. For example, cowpager 0 3 shows desks 0, 1, 2, and 3.

-h

Print usage and exit.

The config file uses the same simple, whitespace-separated format as cowbuttons. Double-quoted strings are supported, and # starts a comment outside quoted strings.

Top-level options act as defaults. A config may also contain named pager blocks, 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 top-level options are used. When a pager block is selectd, options inside that block override the top-level defaults. Multiple names may be listed on one show pager line; those matching blocks are combined into that one instance as they are encountered in the file.

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. It is mutually exclusive with current-only true: setting desks clears current-only mode, and setting current-only true clears the desk range.

window-icons controls whether application icons are 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 automatically reduced further when the miniature is too small for the configured size.

Supported colour roles:

style background 0xffffff
style desk.bg 0xffffff
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.focused.bg 0xf7c733

Colours may be opaque 0xRRGGBB values or 0xRRGGBBAA values carrying an alpha component. Each background layer has its own colour. For example, the following 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.

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.

Each desk cell has a desktop label. When more than one output is shown, a second monitor-label row is 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.

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.

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

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 &

cow(1)

Thomas Adam

2026-08-28 0.2-34-ge7151ab