cowiconman(1)

📦 version 0.3, in fedora 44

💖 cowiconman(1) — the CoW Icon Manager, bestie edition 💖

okay so real talk: cowiconman is the icon manager for cow(1), and it's genuinely one of those little tools that eats. It shows you a clickable list of every window cow knows about, and once you get the config right it's iconic. Let me put you on. 🫶

✨ NAME ✨

cowiconman — CoW Icon Manager. That's it, that's the name, no notes. 💅

🎀 SYNOPSIS 🎀

cowiconman [-c config] [-h]

🌸 DESCRIPTION 🌸

So cowiconman puts up a clickable list of the windows that cow(1) knows about. That's the whole vibe. ✨

If you don't hand it a configuration file, it just makes one icon manager using the built-in defaults — every window in a single column, sorted by title. Simple, clean, no drama.

But here's where it gets good: your configuration can define several named icon managers, and every top-level show iconman line spins up its own separate cowiconman window. One config, many windows, main character energy. 👑

And the window size? It follows the visible button grid — growing and shrinking as windows enter or leave the list, like it's breathing. It's capped to the usable area of the selected output, so it never gets too big for its lane. 💀

💅 OPTIONS 💅

-c config — load config instead of the default configuration file. Your config, your rules.
-h — show usage. The "help me bestie" flag.

🦋 CONFIGURATION 🦋

The format is line-oriented. Blank lines and lines starting with # are ignored — comment away, nobody's judging. And if a value has whitespace in it, it must be double quoted. Non-negotiable, fr fr.

By default, cowiconman reads cowiconman.conf from $XDG_CONFIG_HOME/cow/cowiconman.conf or ~/.config/cow/cowiconman.conf.

Top-level settings are the shared defaults. Named iconman blocks override those defaults, but only for the instances that actually select them. Like, only the girlies who asked. For example:

show iconman current
show iconman applications

sort title
button-width 240

iconman current {
     output current
     desk current
     page current
}

iconman applications {
     group-by app
     icons true
}

Every show iconman line creates one window. And if you put multiple names on the same line, it combines those blocks into one single instance, in the order in which their definitions occur:

show iconman common current-output

The supported commands are all down below, let's go. ⬇️

output VALUE — limits the list to one output. VALUE can be an output name, @N, @current, @next, or @prev. The existing current alias picks cow's current output, while self picks the output that contains the cowiconman window itself (very meta, obsessed). Use all to clear an inherited output filter. Default is to show all outputs.
desk VALUE — limits the list to a desk. VALUE can be a desk number or current. Use all to clear an inherited desk filter. Default is to show all desks.
page VALUE — limits the list to a page. VALUE can be X,Y or current. Use all to clear an inherited page filter. Default is to show all pages.
sort MODE — sorts rows by title, app, id, or just leaves them in cow's order with none. Default is title.
group-by MODE — groups matching windows into one row. MODE can be none, app, title, output, or desk. Default is none.
match FIELD=TEXT — only shows windows whose FIELD contains TEXT. FIELD can be title, app, or id. Matching is case-insensitive (slay). Repeat the command to stack up more filters. And if you prefix TEXT with !, it excludes matching windows instead.
format FMT — sets the row label format. The supported escapes are %t for title, %a for app_id, %i for short window id, %o for output, %d for desk, and %%. Default is %t.
rows N — arranges buttons into at most N rows before starting a new column.
columns N — arranges buttons into N columns. The number of rows gets computed from the visible window count.
anchor none|top|bottom — moves the cowiconman window to the top or bottom usable edge of the selected output. Default is none.
button-width N — sets the preferred button width in pixels. Default is 300.
button-height N — overrides the row height that's derived from cow's current titlebar theme.
button-relief auto|raised|sunken|flat — sets the relief drawn around each row. auto raises normal rows and sinks focused or iconified rows, and it's the default. flat disables the relief entirely — combine it with style border for a solid outline. ✨
style element colour — overrides a palette colour. element is one of background, active.bg, active.fg, inactive.bg, inactive.fg, or iconified.bg, or border. That optional border gets drawn around every row. Colours use CoW's RGB or RGBA syntax. Styles can be shared at top level or set separately inside an iconman block — your call, bestie.
min-button-width N — sets the minimum button width used when the preferred grid would exceed the output's usable width. Default is 80.
icons true|false — shows each window's application icon before its label. cowiconman uses the icon resolved by cow. Default is false.
icon-size N — sets the application icon size in pixels. Default is 16 and the maximum is 20.
iconified-marker true|false — reserves space before each label and draws a small square there for iconified windows. Default is false.
show-self true|false — includes cowiconman windows in the list. Hidden by default. It's shy. 🙈
frame-padding N — adds a border of N pixels around the window list. Default is 4.

🌈 APPEARANCE 🌈

If you don't set any explicit styles, focused and unfocused rows use CoW's active and inactive titlebar colours. The empty background follows the selected output, and an iconified row uses a darkened inactive background. Explicit styles override all these inherited colours, and an unset iconified.bg gets derived from the effective inactive.bg colour. So it always looks intentional, even when you didn't do anything. 💅

👑 USAGE 👑

Left-click a row to focus the window. If that window is iconified, it gets restored and focused. Two birds, one click.
Left-click a grouped row to open a selector for the windows in that group. The selector is a native cow menu using the current menu style, and its rows include the short window id, the output, and the desk. Picking a window switches to its output, desk, and page, activates its container member when necessary, restores it when iconified, and focuses it. That's a lot of steps and it does all of them for you, periodt.

Heads up: type-ahead is disabled for these selectors. Number keys, arrows, Enter, and Escape still work though. 🫶

Middle-click a row to toggle the window's iconified state.
Use the pointer wheel to scroll when a fixed row layout has more entries than fit on screen.
An anchored rows 1 layout behaves like a bar — it spans the selected output's usable width and divides that space evenly between entries. Chef's kiss. 🎀

⭐ EXAMPLES ⭐

Show windows on the current output, desk, and page in a top task bar:

show iconman taskbar

iconman taskbar {
     output current
     desk current
     page current
     rows 1
     anchor top
     icons true
}

Create a separate grouped list for each of two outputs:

show iconman left
show iconman right

group-by app
format "%a (%t)"

iconman left {
     output HDMI-A-1
}

iconman right {
     output eDP-1
     style active.bg 0x458588
     style active.fg 0xffffff
     style inactive.bg 0x83a598
     style inactive.fg 0x000000
}

Show xterm windows but exclude titles containing "logs":

show iconman terminals

iconman terminals {
     match app=xterm
     match title=!logs
}

Remove cowiconman's own window decors while preserving the active decor theme:

decor -d cowiconman-nodecor border.width 0
decor -d cowiconman-nodecor border.handles false
decor -d cowiconman-nodecor titlebar.enabled false
rule -g -Ton-map -ncowiconman-nodecor -s %cowiconman decor -a cowiconman-nodecor

🍓 FILES 🍓

$XDG_CONFIG_HOME/cow/cowiconman.conf ~/.config/cow/cowiconman.conf

🧚 SEE ALSO 🧚

cow(1), moocow(1), cowbuttons(1), cowpager(1) — the whole friend group. Go say hi. 💜

💜 AUTHORS 💜

Thomas Adam <thomas@xteddy.org>

okay that's the whole page!! This one's version 0.3, dated 2026-09-07 — so if you're reading this, hi from the future, drink some water, and go configure your icon manager bestie. 💖✨🎀

📦 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