cow(1)

NAME

cow - Compositor On Wayland

SYNOPSIS

cow [-hv] [-c config]

DESCRIPTION

cow is a window manager using River as the compositor.

A large virtual desktop can be created, effectively splitting the screen into an N x M matrix, called pages. These pages can then be viewed by using the mouse on the edge of the screen, or by using the scroll command.

Desktops provide a means of aggregating open applications into different areas.

cow provides commands which can be used to change settings, setup key/mouse bindings, etc.

OPTIONS

-c config
    Load the configuration from config instead of searching the default locations.

-h
    Print usage and exit.

-v
    Print version and exit.

OUTPUT MANAGEMENT

Neither cow nor River manages outputs (screens/monitors) directly. Instead, applications such as wlr-randr(1), and wdisplays (for something similar to xrandr) can be used instead.

Because cow needs to know information about outputs after it has started, it is recommended that the dedicated file ~/.config/cow/after-start.sh -- which is a shell-script, contains the relevant commands to set the output layout.

NOTE: in this example, it is assumed that $XDG_CONFIG_HOME is set to ~/.config.

cow will assign all outputs a number to a tree with a defined order. That order is top-down, left-to-right, so far example, the following diagram illustrates output configuration and their assigned number:

    out1 (1)
    out2 (2)    out3 (3)    out4 (4)

ANATOMY OF A WINDOW

cow puts a decorative border around windows. This border consists of a bar on each side, and a small L-shaped section on each corner. There is an additional top bar called the titlebar which is used to display the name of the window.

In addition, there are ten titlebar buttons which can be defined and bound to any cow command, such as close, maximize, or iconify.

The diagram below shows an outline of a typical window in cow:

       NW                              N                             NE
       +++──────────────────────────────────────────────────────────+++
       + [1][3][5][7][9]          Titlebar            [2][4][6][8][0] +
       +──────────────────────────────────────────────────────────────+
       │                                                              │
       │                                                              │
       │                                                              │
     W │                                                              │ E
       │                                                              │
       │                                                              │
       │                                                              │
       │                                                              │
       +                                                              +
       +++──────────────────────────────────────────────────────────+++
       SW                              S                             SE

The labels of the window indicate the different components that can be changed.

A window is made up of sides -- and are referenced like that of a compass.

All eight parts of the window border (including corners) can be styled via the decor command.

The titlebar can also be styled or disabled completely via the decor command.

THE VIRTUAL DESKTOP

cow provides up to ten virtual desktops. The screen is a viewport onto a desktop which may be larger than the screen. Several distinct desktops can be accessed (for example, having different desktops for different projects).

Because the desktop can be larger than the physical screen, it can therefore be divided into N x M regions, called pages. This configuration is then applied to all desktops.

For example, the following would define nine pages, arranged in a square:

set desktop_size 3 3

Which would conceptually look like this:

    +----+----+----+
    |    |    |    |
    |    |    |    |
    +----+----+----*
    |    |    |    |
    |    |    |    |
    +----+----+----+
    |    |    |    |
    |    |    |    |
    +----+----+----+

All pages are the same size.

Pages can be moved to/from by enabling edge_scroll by resting the mouse pointer at the screen edges. See the set command.

Windows on pages can be be viewed using the cowpager(1) command.

Windows can also be moved between pages by dragging them to the edge of the output, assuming edge_scroll has been enabled. See the set command.

cow keeps its windows in a Z-ordered stacking order. That is to say, windows can be raised or lowered over one another. This can be controlled via the winops command.

LAYERS

Every window belongs to a numbered layer. The layer range is [0, max_layer] (default 16) and newly mapped windows receive default_layer (default 4).

A window in layer 8 is always above every window in layer 4 regardless of focus, raise, or lower. winops -r and winops -l operate within the window's own layer: they reorder among windows in that layer but never push the window across a layer boundary.

For instance:

•   stay-on-top -- winops -L top (toggles between max_layer and default_layer).
•   stay-on-bottom -- winops -L bottom (toggles between 0 and default_layer).
•   Always-on-top from launch -- bind a rule:

    rule -g -n mpv-pip -T on-map -s %mpv winops -t %mpv -L =top

    Use =top (rather than bare top) inside rules so a re-map event never accidentally toggles the layer back to default.

Iconified windows' icons are pinned to layer 0 regardless of the parent window's layer.

Focus-on-raise (the raise_on_focus setting) is layer-aware: focusing a layer-4 window with a layer-8 window present never visually pops the layer-4 window above the layer-8 one. The titlebar/border colours remain the only cross-layer signal of focus.

The two layer-aware settings are:

•   set default_layer N -- layer assigned to newly mapped windows.
•   set max_layer N -- cap for -L; raising the cap re-permits bigger numbers, lowering it clamps every existing window's layer.

The on-layer-change rule event fires whenever a window's layer changes -- this is the hook for visual cues that depend on layer. For example, to tint the titlebar of any window in the top layer:

    decor -d top-layer titlebar.active_colour 0xC04030
    rule -g -n top-layer-tint -T on-layer-change
        decor -a top-layer

The rule receives the same per-view scope as other view-bearing events, so -s / -t selectors and per-view decor applies all work as expected.

When the rule body is an exec line, the per-firing JSON payload is available to the spawned shell as the COW_EVENT environment variable. For on-layer-change the payload is:

    {"prev": P, "current": N}

so a rule like:

    rule -g -n log-layer -T on-layer-change
        exec sh -c 'printf "%s\n" "$COW_EVENT" >> ~/cow-layer.log'

writes one line per layer transition. jq makes parsing trivial (jq .current <<<"$COW_EVENT"). Other rule events without structured payload leave COW_EVENT unset; the variable is only visible inside the exec'd shell and never affects cow itself or other concurrent rule fires.

SCRIPTING

Beyond the line-oriented command language, cow understands script { ... } blocks: small embedded scripts that can iterate collections, filter them, branch on conditions, and invoke any cow command on the results. A script block is itself a cow command, so it can appear anywhere a command is accepted: the top-level configuration file, or the body of a rule.

  Statements

A block contains zero or more statements; whitespace (including newlines) separates them.

let NAME = EXPR
    Bind NAME to the value of EXPR in the current scope. Names are visible to subsequent statements in the same block and to nested blocks.

for NAME in (SOURCE [where EXPR]) { ... }
    Snapshot SOURCE at loop entry and execute the body once per matching element with NAME bound to the current record. SOURCE is one of windows, desks, outputs (or screens), rules. An optional where clause filters the snapshot with the supplied expression (evaluated per element with NAME in scope). The body sees a fresh sub-scope; let bindings inside the body don't leak out.

if EXPR { ... } [else { ... } | else if ... ]
    Branch on the truthiness of EXPR (numbers are false when zero; strings are false when empty; lists are false when empty; records are always true; nil and false are false).

break
    Exit the nearest enclosing for loop.

continue
    Skip to the next iteration of the nearest enclosing for loop.

COMMAND [ARGS ...]
    Invoke any registered cow command. Each argument is either a raw text chunk (passed verbatim) or an interpolation of the form #{EXPR} which is replaced with the stringified result before the command runs. Commands enqueue on the same queue as the script invocation itself, so their side effects interleave with the rest of cow's command stream.

  Expressions

The expression language has no arithmetic and no string operators in v1; it covers what's needed to choose work to do.

Form | Meaning
N, N.N | numeric literal (double-precision)
"..." | string literal (escapes: \n \t \r \" \\)
true, false | boolean literal
nil | absence of a value; missing record fields also evaluate to nil
[A, B, ...] | list literal, commonly used with in and not in
NAME | variable in the current or enclosing scope
NAME.FIELD.FIELD | record field access (chained for nested records)
A == B | comparison (also !=, <, <=, >, >=); cross-type compares are evaluation errors; ordering on booleans is an evaluation error; nil supports only == and !=
A in [B, C], A not in [B, C] | membership tests; list elements compare with exact scalar equality
not A | unary negation
A and B, A or B | boolean operators (short-circuit)
(EXPR) | grouping

  Sources

Each iterable source yields records whose fields match the matching show topic JSON (see show windows, show desk, show output, show rules). Common window fields include id, app_id, title, desk, output, layer, focused, iconified, circulate_skip, maximized, width, height, page_col, page_row, current_page, current_desk, current_output, sticky_desk, sticky_page, border_width, title_thickness, squeeze, and squeezed_rect. Common desk fields include nr, name, output, current, active, collected, window_count, page_col, page_row, page_cols, page_rows, page_vx, and page_vy. Common output fields include name, nr, number, geometry, usable geometry, current, current_desk, current_desk_name, and page state. Common rule fields include name, type, global, output, desk, match, and body.

For window records, current_page is relative to that window's output. Use current_output and current_page when matching windows only on the current output's current page.

Inside a rule body, the identifier self resolves to a record for the event's target view; outside a rule body it is unbound.

  Examples

Tint titlebars of windows promoted to the top layer:

    decor -d top-tint titlebar.active_colour 0xC04030
    decor -d normal-tint titlebar.active_colour 0x303030
    rule -g -n top-tint -T on-layer-change script {
        if self.layer == 16 {
            decor -a top-tint
        } else {
            decor -a normal-tint
        }
    }

Move every mpv window to the top layer:

    script {
        for w in (windows where w.app_id == "mpv") {
            winops -t #{w.id} -L =top
        }
    }

Iconify every window not on the currently-focused desk:

    script {
        for w in (windows where w.focused != true and w.iconified != true) {
            winops -t #{w.id} -i
        }
    }

When cow starts, for the output (screen) HDMI-A-1, set every desk to start on page 1,1:

    rule -g -T on-start -n startup-pages script {
        let output = "HDMI-A-1"
        for d in (desks where d.output == output) {
            desk -t '#{output}' -d #{d.nr}
            scroll -t '#{output}' -a 1,1
        }
    }

DESKTOP BEHAVIOUR

Desktops can be configured either independently of each output, or desktops are the same across all outputs. See the deskstop_configuration setting.

CONFIGURATION

  Search Order

Unless overridden with -c or $COW_CONFIG, the configuration file is located by searching the following paths in order, stopping at the first that exists:

1.  $COW_CONFIG
2.  ~/cow.conf
3.  $XDG_CONFIG_HOME/cow/cow.conf
4.  ~/.config/cow/cow.conf
5.  /<PREFIX>/etc/cow/cow.conf

  File Format

The configuration file is plain text. Each line is a cow command, using the Lines beginning with # are comments. A backslash (\) at the end of a line continues the command on the next line.

The include command reads additional commands from another file. Absolute paths are used as-is, paths beginning with ~/ are resolved relative to $HOME, and other relative paths are resolved relative to $XDG_RUNTIME_DIR.

Example:

    # This is a comment which cow ignores.
    decor -d default border.width 10
    decor -d default border.style fvwm
    decor -a default
    # This command is split over multiple lines for clarity.
    bind \
        L+Return \
        exec foot

COMMAND REFERENCING

Commands in cow can operate on outputs, desktops, pages, and windows. The commands in cow are therefore pre-disposed to understand that they need one or more of those contexts to operate on.

In some cases that's automatic (such as operating on the focused window, or the current output, etc.) but commands can be told to override that.

  Source and Target Definitions

Most commands have a target on which the command is going to operate on, and for consistency across those commands, that is the `-t` flag. The same concept exists for for a source window, via `-s`.

The format for both is the following:

    output:desk.window

That is to say, there's three components -- the delimiters between the parts are literal and must be specified:

output
    Output name, @N by output number, @next, or @prev.

desk
    Desk number (0-9), @next, or @prev.

window
    One of:

    •   %app_id - match by app_id
    •   /substring/ - match by title substring
    •   #id - match by River identifier
    •   @focused - the currently focused window (default)
    •   @next - next window in stacking order
    •   @prev - previous window in stacking order

In the case of using a substring, this is run through `fnmatch(3)`

COMMAND CHAINING

With any given command, it's possible to chain them together. For example:

    exec xterm ; exec notify-send "xterm executed"

The command divider is `\;` and must be escaped in this way so as not to incur any shell interpretation.

Also, line continuation between changed commands is also possible, and looks like this:

    rule -g -T on-restart -n cleanup
    	exec killall waybar ;
    	exec killall conky ;
    	exec killall pasystray

COMMAND OUTPUT

Certain commands in cow are designed to return information. In such cases, the output is in JSON format.

This may be subject to change in the future.

GLOBAL COMMANDS

The following details those commands which just operate on general settings. Note that the same command might also contain window/output settings, which will be also be added under the relevant section.

  bind [-r] modifier+key action ...

Key bindings are specified as a modifier string immediately followed by + and a keysym name, or - and a numeric keycode:

    bind MODIFIERS+keysym  command
    bind MODIFIERS-keycode command

-r
    Mark the binding as repeatable. While the triggering key is held the action re-fires every repeat_interval_ms milliseconds after an initial repeat_delay_ms dwell (see set).

Modifier characters:

Character | Modifier
L | Logo (Super / Windows key).
S | Shift.
C | Control.
A | Alt (Mod1).
M | Meta (Mod1).
5 | AltGr (Mod5).

Modifiers are combined by concatenation: LS means Logo+Shift, LCA means Logo+Control+Alt, and CM means Control+Meta. Use 0 to specify no modifier.

Key symbols and codes can be determined with wev(1).

Examples:

    bind L+Return     exec xterm
    bind LS+a         winops -c
    bind LCA+q        quit
    bind 0+F1         action-help
    bind -r L+Right   scroll -n           # hold Super+Right to keep paging

  mouse key action ...

Mouse bindings use the same modifier format as the bind command. The button name replaces the keysym:

    mouse MODIFIERS+button command

Button names: left, right, middle, side, extra, forward, back, task.

Bind a pointer button combination to a command. The key format is the same as for bind, but the key name is a button name (see MOUSE BINDINGS).

Example:

    mouse L+left   window-move
    mouse L+right  resize
    mouse L+middle window-move -C

  root-mouse key action ...

Bind an unmodified pointer button on cow's output background surface to a command. This is intended for root-window style menus and does not capture normal clicks on client windows.

Example:

    root-mouse 0+left menu-show RootMenu

See the MENU section for more information.

  bind-decoration [-2] region command ...

Bind a primary-button click on a window's decoration to a command. Each window's frame is divided into regions. See the ANATOMY_OF_A_WINDOW section.

When a bound region of the window is clicked on, the attached action runs against that window.

-2
    Double-click binding (default is single-click). A region can carry one single-click binding and one double-click binding simultaneously.

The region argument is case-insensitive and accepts both the compass shorthands and the long form:

Region | Aliases
N | north
S | south
E | east
W | west
NE | north-east
NW | north-west
SE | south-east
SW | south-west
titlebar | title

The defaults bindings are:

Region | Clicks | Default action
N / S / E / W | single | window-resize -e dir (interactive one-axis resize)
NE / NW / SE / SW | single | window-resize -e dir (interactive diagonal resize)
titlebar | single | window-move (interactive title-drag move)
titlebar | double | window-shade -d titlebar (shade / unshade toward the titlebar)

Double-clicks on edges and corners have no defaults.

Limitation: River does not expose which button was used when clicking on the window decoration, so currently, only mouse button 1 is usable.

Examples:

    # Maximise a window by clicking anywhere on its titlebar
    # (replaces the default window-move).
    bind-decoration titlebar window-maximize -m
    # Re-express the default double-click-shade explicitly.
    bind-decoration -2 titlebar window-shade -d titlebar
    # Maximise on a click on the north edge.
    bind-decoration N window-maximize -m
    # Double-click NE corner closes the window (the single-click default
    # of starting a corner resize still fires on the first click; bind
    # the single-click pair too if you want to suppress it).
    bind-decoration -2 NE    winops -c
    # Chain: start a resize then focus the next window.
    bind-decoration SE       window-resize -e se ; focus -n

  rule -d -n <name> | -g | -t output[:desk] -n <name> -T <event> [-s sel] cmd...

Apply rules (groups of commands) to certain conditions (events).

A rule has a name (via `-n`) which must be specified. Note that rules are globally stored, so any conflicting names will mean that rule is replaced. It also has a type (via `-T`) which specifies when to run the rule. Multiple rules can be defined against the same type as long as their names are distinct.

The following table shows which events are available:

Event | Description
on-map | Fired when a window appears on the screen.
on-move | Fired when a window is moved.
on-resize | Fired when a window is resized.
on-shade | Fired when a window is shaded.
on-unshade | Fired when a window is unshaded.
on-iconify | Fired when a window is iconified.
on-deiconify | Fired when a window is deiconified.
on-layer-change | Fired when a window's layer changes (see LAYERS). Fires per-window for container members. No-op assignments do not fire.
on-new-desk | Fired a new desk is switched to.
on-new-page | Fired when a new page is switched to.
on-start | Fired once after cow has completed startup. Use with -g.
on-restart | Fired when cow is restarted (can also happen via `-USR1` signal.
on-title-change | Fired whenever a window's title changes to something different to what it used to be.
on-outputs-changed | Fired when the set of available outputs changes -- a monitor is plugged in or unplugged, or every output is destroyed and recreated. Fires once per change. Useful to re-apply a monitor layouts.
on-desk | Used to change window styles on a particular desk.

Specificity of rules are such that global rules (via `-g`) run before any specific defined rules. For example:

    # Define a global rule -- this will always run.
    rule -g -Ton-map -ng-on-map exec notify-send "A window has appeared."
    # Define a rule to change a window property when windows appears on desk 2
    decor -d desk2 titlebar.active_colour 0xFF8C00
    decor -d desk2 titlebar.inactive_colour 0xB28E4C
    decor -d desk2 border.inactive 0xB28E4C
    rule -t :2 -Ton-map -ndesk2 decor -a desk2

Rules can be deleted with the `-d` option. Additionally, `-n` is needed to specify the name, example:

    rule -d -ndesk2

Defined rules can be seen with the show command.

  exec command ...

Execute a shell command. During configuration loading, exec commands are deferred until cow has fully connected to River.

  draw-exec [-F expr] command ...

Start an interactive pointer drag. On button release, run command and apply the drawn frame to the first newly mapped window which matches expr. Without -F, the first newly mapped window consumes the frame.

The command is parsed as a CoW command, so launching an application usually uses exec:

    mouse M+left draw-exec exec foot
    mouse M+middle draw-exec -F 'self.app_id == "foot"' exec foot

If the command is a brace-delimited script block, the surrounding braces are removed before the block is evaluated.

  show [-F expr] [topic] [config key]

Query window manager state. The response is a JSON object. When used via moocow(1) the JSON is printed to standard output.

-F expr
    Filter show windows with a DSL expression. self is bound to each candidate window.

Topics:

show windows
    Return an array of all managed windows. Each element contains: id, app_id, title, desk, x, y, width, height, focused, maximized, shaded, iconified, circulate_skip, page_col, page_row, current_page, current_desk, current_output.

    Example: show -F 'self.current_page' windows

show desk
    Return {"current": N} for the current output's active desk.

show rules
    Return an array of all defined rules.

show output
    Return an array of output objects, each with name, x, y, width, height, and a usable sub-object reflecting reserved areas.

show config key
    Return the current value of a configuration key. Supported keys: border.width, step, border.corner_length, border.style, focus. Also accepted as show config.key.

  quit [-r]

Without any options, cow quits. With -r, reload the configuration from the file cow was started with, instead of quitting.

Keybindings and window decorations are updated immediately on reload.

  include _file_

Read and execute commands from file. Absolute paths are used as-is, ~/ is resolved relative to $HOME, and other relative paths are resolved relative to $XDG_RUNTIME_DIR.

  list-commands

Return a JSON array of all registered commands, each with name and usage fields.

  nop

Do nothing.

  decor -d name key value

Define or replace one key in a named, sparse decoration profile. The key is a decoration key without the set prefix.

    decor -d alert border.width 8
    decor -d alert titlebar.active_colour 0xC04030
    decor -d alert border.inactive 0x303030

Theme packs can be split into files and loaded with include, for example:

    include themes/fvwm
    decor -a fvwm

Image values in a profile may name SVG or PNG files. Relative image paths are resolved against the file containing the decor -d command, so a theme directory can keep its config and image assets together.

  decor -a name [-t target]

Apply a named decoration profile. Switching to a different global profile, or applying a profile to an explicit target, resets the target decoration to the base defaults before applying the profile entries. Reapplying the active global profile patches the current decoration in place. Profiles containing only icon.* keys also patch in place. Profiles applied by rules are overlays, so layered rules can compose sparse profiles.

With -t, the target is that window. Without -t, the target is the global decoration defaults and existing windows. Rule bodies use the rule's default window target.

  set [-v] key value

Set a configuration option at runtime. -v prints the resulting value. Window decoration keys are rejected by set; use decor for those.

The specific keys/values for this command are detailed under relevant section in this man page.

WINDOW COMMANDS

The following detail commands which operate on windows directly.

  winops [-Icilrs] [-C on|off|toggle] [-L layer] [-t target]

Operate on a window.

-t target
    Target window (see COMMAND REFERENCING). Defaults to the focused window.

-I
    Identify the window; returns a JSON object with geometry and state.

-c
    Close the window.

-r
    Raise the window to the top of the stacking order within its layer. See LAYERS below for the cross-layer invariant.

-l
    Lower the window to the bottom of the stacking order within its layer.

-s
    Toggle desk-sticky: window appears on all desks.

-S
    Toggle page-sticky: window appears on all pages of the current desk. Combine -s and -S for fully sticky (all desks and pages).

-i
    Toggle the window's iconified (minimised) state. Click an iconified window to restore it; drag it to remember a manual icon position for later iconify operations.

-C on|off|toggle
    Set, clear, or toggle CirculateSkip. Skipped windows are ignored by focus -n, focus -p, @next, and @prev; explicit focus and mouse focus still work.

    CirculateSkip is window state. Once set, it applies to ordinary next/previous circulation regardless of which key binding or command started the focus change. This is useful for panels, pagers, docks, and other utility windows which should generally remain reachable by direct focus, but not appear in normal circulation.

-L layer
    Set the window's layer (see LAYERS). Accepted forms:

    •   N -- absolute layer (clamped to [0, max_layer]).
    •   =N -- absolute layer, explicit (never toggles).
    •   +N / -N -- relative bump, clamped at edges.
    •   top -- shorthand for max_layer; toggles back to default_layer when the window is already at max_layer.
    •   bottom -- shorthand for 0; toggles back to default_layer when the window is already at 0.
    •   =top / =bottom -- non-toggling variants, useful inside a rule command.

    Container members share a single layer: setting -L on any member updates every member of the container.

  window-move [-C] [-t target] [-d dir [-n]] [-o output] [-c] [-k 0-9] [-x X] [-y Y]

Move a window. With no flags, begin an interactive move using the mouse.

-t target
    Target window.

-d dir
    Move one step in direction dir (up, down, left, right).

-n
    With -d, snap to the nearest edge instead of stepping.

-o output
    Move the window to the named output. May be combined with -k to land the window on a specific desk of that output; other flags (-d, -c, -x, -y, -P) are rejected when given with -o.

-C
    Enable container-formation on drop. When the interactive move ends with the pointer over another window's titlebar, the two windows are grouped into a container instead of completing a normal move. Releasing over empty space performs a normal move. The target window's titlebar highlights in orange while the pointer is over it.

-P col [row]
    Move the window to the page at column col, row row (0-indexed), preserving its within-page position. row defaults to 0. Only meaningful when desktop_size is larger than 1×1.

-c
    Centre the window on its current output.

-k 0-9
    Move the window to desk number 0-9.

-x X
    Set the window's X position. A leading + or - makes the value relative to the current position.

-y Y
    Set the window's Y position. A leading + or - makes the value relative to the current position.

  window-resize [-t target] [-gs] [-d dir] [-e edges] [-w width] [-h height]

Resize a window. With no flags, begin an interactive resize operation with the mouse, from the bottom-right corner.

-t target
    Target window.

-g -d dir
    Grow the window in direction dir (up, down, left, right) by one step.

-s -d dir
    Shrink the window in direction dir by one step.

-e edges
    Begin an interactive resize anchored on the named edges -- a compass spec built from the letters n, s, e, w. Single letters select an edge (n, s, e, w); two-letter combos select a corner (ne, nw, se, sw). Used by bind-decoration to express per-edge / per-corner resize defaults as ordinary commands; default if -e is omitted is the historic se (bottom-right) corner.

-w width
    Set the window width in pixels.

-h height
    Set the window height in pixels.

  window-tile [-t target] [-e edges] [-u]

Set or clear the tiled-edge hint for a window. This is mainly useful for scripts which place and size windows exactly, because some clients use the tiled state to ignore normal resize increments.

-t target
    Target window.

-e edges
    Set the tiled edges. edges may be all, none, or any combination of n, s, e, and w. The default is all.

-u
    Clear the tiled-edge hint.

  focus [-npwL] [-F expr] [-l N] [-t target] [-d dir] [-o output] [-A app_id] [-T title] [-i id]

Move keyboard focus.

-n
    Focus the next window in stacking order.

-p
    Focus the previous window in stacking order.

-F expr
    Restrict -n and -p circulation with a DSL expression. self is bound to each candidate window. CirculateSkip still applies, so utility windows marked with winops -C on are skipped independently from the expression.

    The filter is local to this focus invocation. Use it for predicates which are part of a particular focus action, such as limiting circulation to the current output and page. Use winops -C instead when a window should be skipped by normal circulation in general.

    Examples:

    •   focus -nw -F 'self.current_output and self.current_page'
    •   focus -nw -F 'self.current_desk'
    •   focus -nw -F 'self.current_output'
    •   focus -nw -F 'self.current_output and self.current_page and self.app_id not in ["cowpager"]'
    •   focus -nw -F 'self.current_output and self.current_page and self.app_id not in ["cowpager", "appA", "appB"]'

-w
    Warp the pointer to the centre of the focused window after focus is applied. May be combined with any other focus flag. When used alone, warps to the currently focused window without changing focus.

-d dir
    Focus the nearest window in direction dir (up, down, left, right).

-o output
    Warp the pointer to the named output. The -w flag is ignored when -o is given, as -o performs its own pointer movement.

-A app_id
    Focus the window with the exact app_id app_id.

-T pattern
    Focus the window whose title contains pattern.

-i id
    Focus the window with River identifier id.

-L
    Restrict traversal to the focused window's layer (see LAYERS). Combine with -n, -p, or -d; standalone -L is an error. When no window is focused, the current layer is taken as default_layer.

-l N
    Restrict to layer N. Without -n or -p, focuses the topmost focusable window in layer N; if the focused window is already in layer N, cycles to the next focusable window in that layer. Combine with -n/-p to walk only within N. Mutually exclusive with -L.

  window-expand [-t target] [-d dir] [-T]

Expand a window to fill available space between windows, or the whole monitor if the window is the only window on that monitor.

Use window-maximize -k after expanding if the current geometry should become maximized state.

-t target
    Target window.

-d dir
    Expand in direction dir (up, down, left, right). Omit to expand in all directions.

-T
    Toggle: restore original geometry if the window is already expanded.

  window-maximize [-t target] [-T] [-m] [-u] [-h] [-v] [-k]

Maximize or restore a window.

-t target
    Target window.

-T
    Toggle between maximized and restored. Combined with -h / -v, toggles only that axis; toggling an unmaxed axis maximises it.

-m
    Maximize the window (default if no flag is given).

-u
    Restore (unmaximize) the window. Combined with -h / -v, restores only that axis; a window can stay maximised on the other axis.

-h
    Maximize horizontally only -- the window's width grows to the output's usable area.

-v
    Maximize vertically only -- the window's height grows to the output's usable area.

-k
    Keep the current geometry while marking the window as maximized. Combined with -T, restore if the requested axis is already maximized; otherwise mark it maximized without changing size.

Per-axis maximised state is independent: window-maximize -h followed by window-maximize -v leaves the window maximised on both axes, and each axis can be restored separately with -T -h and -T -v.

Examples:

    window-maximize        # full maximise
    window-maximize -T     # toggle full maximise
    window-maximize -h     # horizontal only
    window-maximize -v     # vertical only
    window-maximize -T -h  # toggle horizontal maximised state only
    window-maximize -u -v  # un-maximise vertical only, keep horizontal
    window-maximize -k     # mark maximised without changing size

  pick-window [-F expr] command ...

Pick a window with the mouse and run command targeting that window. The cursor changes to a crosshair icon, indicating a target window should be selected. Right-click or Escape cancels.

The picked window is passed to command as the default target, so a command without an explicit -t operates on the picked view. Any explicit -t in command takes precedence.

-F expr
    Only allow matching windows to be picked. self is bound to each candidate window.

Examples:

    bind Super+p pick-window winops -c
    bind Super+P pick-window { winops -c ; focus -L }
    bind Super+o pick-window -F 'self.current_output' focus

  window-shade [-t target] -d dir

Shade (roll up) a window in a given direction, hiding its content but leaving its border visible.

-t target
    Target window.

-d dir
    Shade direction: north, south, east, west, nw, ne, sw, se. Required.

WINDOW DECORATION SETTINGS

The following tables show which settings are available to control the look and feel of a window. All of these can be used with decor -d.

General Decoration Settings:

Key | Description
border.width | Border thickness in pixels (default: 1).
border.corner_length | Length of border corner handles in pixels (default: 20).
titlebar.font | Pango font string for titlebars.
border.handles | true | false | Draw handle marks on border corners.

Border Colour Settings (values are hexadecimal RGB, e.g. 0xFF0000):

Key | Description
border.active | Active (focused) window border colour.
border.active.gradient | Border gradient. Value is HGradient colour colour, VGradient colour colour, or none.
border.active.image | SVG or PNG image painted over the active border. Use none to clear.
border.active.n | Active border: north edge.
border.active.n.gradient | Active north edge gradient. The same .gradient suffix is available for s, e, w, nw, ne, sw, and se.
border.active.n.image | Active north edge image. The same .image suffix is available for s, e, w, nw, ne, sw, and se.
border.active.s | Active border: south edge.
border.active.e | Active border: east edge.
border.active.w | Active border: west edge.
border.active.nw | Active border: north-west corner.
border.active.ne | Active border: north-east corner.
border.active.sw | Active border: south-west corner.
border.active.se | Active border: south-east corner.
border.inactive | Inactive (unfocused) border colour.
border.inactive.gradient | Inactive border gradient.
border.inactive.image | SVG or PNG image painted over the inactive border. Use none to clear.
border.inactive.n | Inactive border: north edge.
border.inactive.n.gradient | Inactive north edge gradient. The same .gradient suffix is available for s, e, w, nw, ne, sw, and se.
border.inactive.n.image | Inactive north edge image. The same .image suffix is available for s, e, w, nw, ne, sw, and se.
border.inactive.s | Inactive border: south edge.
border.inactive.e | Inactive border: east edge.
border.inactive.w | Inactive border: west edge.

Titlebar Colour Settings (values are hexadecimal RGB, e.g. 0xFF0000):
Key | Description
titlebar.active_colour | Titlebar background when focused.
titlebar.active_gradient | Titlebar gradient when focused. Value is HGradient colour colour, VGradient colour colour, or none. Gradients are painted over the titlebar colour.
titlebar.active_image | SVG or PNG image painted over the focused titlebar. Use none to clear.
titlebar.inactive_colour | Titlebar background when unfocused.
titlebar.inactive_gradient | Titlebar gradient when unfocused. Use none for a solid colour.
titlebar.inactive_image | SVG or PNG image painted over the unfocused titlebar. Use none to clear.
titlebar.fg_active | Titlebar foreground (text) when focused.
titlebar.fg_inactive | Titlebar foreground (text) when unfocused.

Titlebar and Frame Settings:

Key | Values | Description
border.style | fvwm | mwm | none | Border rendering style. Default: none.
focus | sloppy | click | Focus model. Default: click.
geometry_window | both | move | resize | none | Show the geometry overlay while interactively moving or resizing windows. Default: both.
placement | cascade | undermouse | centre | center | New window placement. Default: cascade.
titlebar.enabled | true | 1 | Show titlebars.
titlebar.height | integer (pixels) | Fix the titlebar height in pixels. When set to 0 (the default) the height is derived from the font size.
titlebar.position | top | bottom | left | right | Set where the titlebar is drawn. Default: top.
titlebar.button.N.vector | vector string | Geometry of titlebar button N, where N is 0 through 9. Odd buttons are placed on the left; even buttons are placed on the right, with button 0 nearest the right edge. Use none to hide a button slot unless it has an image configured.
titlebar.button.N.action | command string | Command run when titlebar button N is clicked. The clicked window is the default command target. Quote commands that contain spaces, for example 'window-maximize -T'.
titlebar.button.N.image | SVG or PNG image | Image drawn inside titlebar button N instead of its vector glyph.
titlebar.squeeze | none | natural | fixed | Shrink the titlebar down to a minimum size. Remaining pixels of the titlebar strip are transparent and pass clicks through. none is the default (full-width titlebar); natural sizes the titlebar to the title text + buttons; fixed uses titlebar.squeeze.width.
titlebar.squeeze.justify | left | centre | right | Horizontal alignment of the squeezed titlebar within the full-width strip. Default: left. center is accepted as a synonym for centre.
titlebar.squeeze.width | integer (pixels) | Width of the squeezed titlebar when titlebar.squeeze is fixed. Default: 300.
titlebar.squeeze.offset | integer (pixels; may be negative) | Horizontal nudge applied after justify. Useful for e.g. positioning the titlebar 40px in from the left edge. Default: 0.
titlebar.squeeze.min_width | integer (pixels) | Minimum width for natural mode (floor applied after measurement). Default: 80.
title_format | string | Controls the display title used in the titlebar. Default is: '[%t] %n' Supported escapes are %n for the raw window title, %t for cow's unique short window id, %I for the full window id, %c for app_id, and %% for a literal percent. The default is [%t] %n.

Button vector format: N x1Xy1@c1 x2Xy2@c2 ... where N is the number of points, coordinates are 0-100 (percentages of the button area), and @c is a colour index (0 or 1).

WINDOW CONTAINERS

Group windows into a tabbed container. A container is a meta-window that holds multiple application windows as tabs. Only the active tab's content is visible; all tabs share the container's position, size, and frame. The titlebar shows a clickable label for each member. Clicking a label activates that tab.

  window-container [-t target] [-s source] [-arnpNP]

window-container -a
    Add source to target's container. If neither window is already in a container, a new container is created.

    source defaults to the focused window. target defaults to the focused window when -t is given explicitly.

    When neither -t nor -s is given, source is the focused window and target is the next focusable window in stacking order. This means container add with no arguments is a self-contained keyboard-only action: it groups the focused window with the one below it in the stack. This is useful in environments where mouse modifier combinations are unavailable (e.g. VNC).

window-container -r [-t target]
    Remove target from its container. The detached window reappears offset from the container position. If the container drops to one member, the container is dissolved.

window-container -n [-t target]
    Activate the next tab in the container that holds target.

window-container -p [-t target]
    Activate the previous tab in the container that holds target.

window-container -N [-t target]
    Move the tab containing target one position to the right in the tab strip. The tab remains active. No-op if it is already the last tab.

window-container -P [-t target]
    Move the tab containing target one position to the left in the tab strip. The tab remains active. No-op if it is already the first tab.

See also window-move -C, which allows containers to be formed interactively by dragging a window's titlebar onto another. In environments where mouse modifier combinations are unreliable (e.g. VNC), bind container add to a key instead:

    bind L+g   window-container -a
    bind LS+g  window-container -r
    bind L+Tab window-container -n

  Container Settings

The following options can be used inside decor -d profile blocks to style container tabs:

Key | Values | Description
container.tab.active_colour | hex colour (0xRRGGBB) | Background colour of the active tab label. Default: 0xC0C0C0.
container.tab.active_gradient | HGradient colour colour | VGradient colour colour | none | Background gradient of the active tab label.
container.tab.active_image | SVG or PNG image | Image painted over the active tab label. Use none to clear.
container.tab.inactive_colour | hex colour (0xRRGGBB) | Background colour of inactive tab labels. Default: 0x808080.
container.tab.inactive_gradient | HGradient colour colour | VGradient colour colour | none | Background gradient of inactive tab labels.
container.tab.inactive_image | SVG or PNG image | Image painted over inactive tab labels. Use none to clear.
container.tab.fg_active | hex colour (0xRRGGBB) | Foreground (text) colour of the active tab label. Default: 0x000000.
container.tab.fg_inactive | hex colour (0xRRGGBB) | Foreground (text) colour of inactive tab labels. Default: 0x202020.
container.tab.sunken | true | 1 | false | 0 | Draw inactive tabs with a sunken (depressed) bevel. Default: false (flat).

Icons

Minimised windows can be represented as icons on the root window. These can have an image associated with them, or not. If there's no image associated with an icon, a blank rectangle is drawn, and the window's title appears underneath it.

Icons can be moved around the screen with the mouse. In doing so, a window will continue to iconify to that dragged position. Icons which are not moved manualky will be placed automatically along the bottom of the output.

The following commands control icons:

  icon-reset [-F expr] [-t target]

Reset manual icon positions. Without -t, all saved icon positions are cleared and iconified windows are returned to automatic placement. With -t, the target may be a window, output, or desk; for example -t #id, -t @1, or -t :2.

-F expr
    Only reset matching windows. self is bound to each candidate window. With a single target window, the expression is a guard.

Example:
    icon-reset -F 'self.current_desk and self.iconified'

  ICON SETTINGS

The following table shows which settings can be applied to a given (named) decor to change aspects of how icons are controlled:

Key | Description
icon.enabled | true | false. Show desktop icons for iconified windows. If disabled, windows can still be iconified, but no desktop icon is created.
icon.size | Iconified window icon size in pixels (default: 64).
icon.image | SVG or PNG image drawn inside the iconified window icon box. Defaults to CoW's installed icon. Use none to clear it.
icon.background | Iconified window icon box background colour.
icon.foreground | Iconified window label colour.
icon.title_relief | true | false. Draw a 3D-relief panel behind the icon label.

MENUS

cow supports named popup menus. A menu is defined by appending items with menu-add, then opened with menu-show. Items may be cow commands, titles, separators, or links to sub-menus.

  Defining menus

menu-add NAME LABEL ACTION
    Append an item to menu NAME, creating the menu on first reference. Special ACTION values:

    •   title -- LABEL becomes a non-selectable title row.
    •   - (with LABEL also -) -- adds a separator.
    •   popup OTHER -- the item opens sub-menu OTHER.
    •   popup-pick OTHER -- the item opens sub-menu OTHER; when no window context is known, the selected child action first picks a target window.
    •   anything else -- a cow command line run when the item is selected.

menu-clear NAME
    Empty the named menu without destroying it.

menu-destroy NAME
    Remove the named menu and close any open popup of it.

  Showing menus

menu-show NAME [-x N] [-y N]
    Open the menu as a popup. Without explicit coordinates, the menu is centred horizontally on the current pointer location, with the pointer placed over the top/title row. With -x and -y, those coordinates are used directly. The command queue's explicit target window is captured as the menu's "context view" so window-operation items target the right window even if focus drifts during navigation.

menu-key DIRECTION|HOTKEY
    DIRECTION is one of up, down, left, right, select, close; a single alphanumeric HOTKEY activates the matching item. A no-op when no menu is open, so the same keybinding can be left in place at all times.

Additionally, the root-mouse command can specify a binding to open a menu:

    root-mouse 0+left "menu-show RootMenu"

  Styling

menu-style KEY VALUE

Sets the style of a menu. This can be used to set the colours of the background, foreground, whether a menu should use gradient, etc.

The table below shows the possible values:

Key | Default
bg | 0xbebebe
bg.gradient | none
fg | near-black
title.bg | 0xbebebe
title.bg.gradient | none
title.fg | near-black
separator | mid-grey (title underline colour)
border.width | 2 (outer relief thickness)
padding.x | 6 (horizontal item padding)
padding.y | 2 (vertical item padding)
title.underlines | 2
automatic.hotkeys | true

Gradient values use the same syntax as decoration gradients: none, HGradient COLOUR COLOUR, or VGradient COLOUR COLOUR.

For hotkeys, a literal & before a label character marks that character as the item hotkey and underlines it. Use && for a literal ampersand.

When automatic.hotkeys is enabled, cow assigns unique alphanumeric hotkeys to selectable items that do not have an explicit & marker.

Menus automatically use the font_name setting, used globally in cow.

  Example

    # A "send to desk" sub-menu and a window-ops menu that uses it.
    menu-add SendToDesk "Send to Desk" title
    menu-add SendToDesk "Desk 1"       "desk 1"
    menu-add SendToDesk "Desk 2"       "desk 2"
    menu-add WindowOps  "Window"        title
    menu-add WindowOps  "Move"          "window-move"
    menu-add WindowOps  "Maximise"      "window-maximize"
    menu-add WindowOps  -               -
    menu-add WindowOps  "Send To Desk"  "popup SendToDesk"
    menu-add WindowOps  "Close"         "winops -c"
    menu-add RootMenu "Window Ops" "popup-pick WindowOps"
    root-mouse 0+left "menu-show RootMenu"
    # Arrow + Enter + Esc navigation while a menu is open.
    bind 0+Up     menu-key up
    bind 0+Down   menu-key down
    bind 0+Left   menu-key left
    bind 0+Right  menu-key right
    bind 0+Return menu-key select
    bind 0+Escape menu-key close
    bind 0+m      menu-key m
    bind 0+c      menu-key c

DESKTOP / OUTPUT COMMANDS

This section details commands which affect desktops/pages often per-output.

  scroll [-t output] [-w] [-p] _H_ _V_

  scroll [-t output] [-a] _col_,_row_

  scroll [-t output] -d _left_|_right_|_up_|_down_

  scroll [-t output] -n

  scroll [-t output] -P

  scroll [-t output] [-R] -r

Pan the virtual page viewport for the current desk.

Pages can be scrolled in either full pages, or part increments. Additionally, it's possible to in-effect, "drag" the viewport with the mouse to any position.

In the deltas form (H V), H is the horizontal scroll and V the vertical. By default each value is a percentage of one page in that axis: 100 is one full page right (or down), -100 one page left (or up), 50 is half a page, and so on. With -p the values are raw pixels instead.

Options are:

-t output
    Target the named output instead of the current one.

-w
    Wrap at the desk edges. Without -w, the viewport is clamped to the desk extent. The legacy fvwm idiom of multiplying the percentage by 1000 (e.g. scroll 100000 0) is also recognised as an implicit -w.

-p
    Treat H and V as pixels rather than percent of a page.

-a col,row
    Page jump: land the viewport at page col,row. The pair are a single comma-separated token. Each axis accepts an absolute page index (0-indexed), a negative absolute index from the end (-1 is the last page in that axis), or a signed relative page offset with a p suffix (+0p means the current page in that axis). The -a flag may be omitted when the command has a single comma-separated argument.

-d dir
    Jump one page in direction dir: left, right, up, or down, wrapping at desk edges.

-n
    Next page (right, wrapping at the end of a row to the start of the next row). Shorthand for scroll -w 100 0.

-P
    Previous page (left, wrapping).
-r
    Start an interactive drag-the-viewport pan. The viewport follows the pointer until the triggering mouse button is released. Only valid when invoked from a mouse or key binding. Bind it to a mouse button to "grab and drag" the desk. The -w and -p flags are ignored with -r since interactive drag works in raw pixels and never wraps.

-R
    Paired with -r, makes the viewport follow the pointer in the same direction instead of opposite.

Pages exist only when desktop_size N M is configured with N > 1 or M > 1.

Examples:

    # One full page right (clamps at the last column).
    scroll 100 0
    # Half a page right, a quarter page down.
    scroll 50 25
    # 200 pixels right.
    scroll -p 200 0
    # One page right, wrapping at the desk edge.
    scroll -w 100 0
    # Jump straight to page (col=2, row=0).
    scroll -a 2,0
    # Jump to the last column in the current row.
    scroll -a -1,+0p
    # One page right, wrapping; convenient for keybindings.
    scroll -d right
    # Next / previous page with wrap.
    scroll -n
    scroll -P
    # Bind Ctrl+Meta+Button1 to grab and drag the viewport.
    mouse CM+left scroll -r

  desk [-t output] [-d N] [-c N] [-np]

Switch or manipulate virtual desks.

-t output
    Target the named output instead of the current one.

-d N
    Switch to desk number N.

-n
    Switch to the next desk, wrapping around.

-p
    Switch to the previous desk, wrapping around.

-c N
    Toggle collection of desk N: overlay its windows on top of the current desk without switching.

  desk-name [-t output] N NAME | -d N | -l | -r

Manage the naming of virtual desktops. By default, cow sets ten desktops, whose names default to '0'..'9'. With this command it is possible to change that, either by increasing or decreasing the number of desktops, and/or renaming existing desks.

-t output
    Target the named output instead of the current one. In global desktop mode the operation is mirrored across every output.

N NAME
    Ensure desk N exists and set its name to NAME. Gaps below N are auto-filled with default-named desks. Names must be non-empty, printable, and contain no whitespace or :; duplicates within one set are rejected.

-d N
    Delete desk N. Refused if any window is on it.

-l
    List the current desks as JSON, per output.

-r
    Reset every desk set to the default set, as if no manipulation had ever occurred.

The following examples show how this command can be used:

    # Three named desks instead of the default ten.
    desk-name 0 main
    desk-name 1 web
    desk-name 2 dev
    # Now both forms select the same desk.
    focus -t :main
    focus -t :0

The minimum number of desks can be set with desks.count. Note that it is possible with the desk-name command to name desks greater than desks.count number, and that this will effectively create this desk.

  Desktop / Page Settings

The following options can be used with the set command to change the behaviour of desktops and pages:

Key | Values | Description
desktop-configuration | global | per-output | shared | Desk layout mode.
desktop_size N M | N × M integer | Virtual page grid: N columns × M rows per desk. Default: 1 1 (no pages). Set e.g. 3 2 for three columns and two rows.
desks.count | 0-32 | Sets the number of available virtual desktops. Defaults: 10.
page_scroll_animate | true | false | Animate page transitions. Default: false (instant cut).
page_scroll_ms | integer (ms) | Page scroll animation duration. Default: 200.
edge_scroll | true | false | Enable edge scroll: hovering the cursor at a screen edge switches the page after edge_scroll_delay_ms milliseconds. Default: false.
edge_scroll_delay_ms | integer (ms, 50..5000) | Cursor hover time at an edge before the page switches. Default: 300.
output.colour.background | hex colour (0xRRGGBB) | Background colour for all outputs.
output.colour.background.name | hex colour (0xRRGGBB) | Background colour for the named output.
reserved.top | integer (default: 0) | Pixels reserved at the top of each output.
reserved.bottom | integer (default: 0) | Pixels reserved at the bottom of each output.
reserved.left | integer (default: 0) | Pixels reserved at the left of each output.
reserved.right | integer (default: 0) | Pixels reserved at the right of each output.

NOT£: The reserved. settings are akin to X11's concept of a working-area. That is to say, these settings will reserve parts of the screen to be able to put taskbars, etc.

  Keyboard Settings

The following options can be used with the set command to tune keybinding behaviour:

Key | Values | Description
repeat_delay_ms | integer (ms) | Time the user must hold a bind -r repeatable key before the action starts repeating after its first fire. Default: 400.
repeat_interval_ms | integer (ms, >= 1) | Gap between consecutive repeats of a held bind -r binding once the initial dwell has elapsed. Default: 40 (= 25 fires / s).

A binding registered without -r fires exactly once per press, regardless of either setting.

SIGNALS

SIGTERM, SIGINT
    Save state and exit cleanly.

SIGUSR1
    Restart: execute the rule restart hook command (if configured), then re-execute cow itself via execvp(3) without tearing down the River session.

SIGPIPE
    Ignored.

ENVIRONMENT

COW_CONFIG
    If set, use this path as the configuration file, bypassing the default search order.

XDG_CONFIG_HOME
    Base directory for the user configuration search ($XDG_CONFIG_HOME/cow/cow.conf). Defaults to ~/.config.

XDG_RUNTIME_DIR
    Directory in which the IPC command and status sockets are created.

FILES

~/cow.conf
    User configuration (second search location).

$XDG_CONFIG_HOME/cow/cow.conf
    User configuration in XDG base directory (third search location).

~/.config/cow/cow.conf
    Fallback user configuration (fourth search location).

/etc/cow/cow.conf
    System-wide configuration (fifth search location).

$XDG_RUNTIME_DIR/cow-$WAYLAND_DISPLAY-cmd.sock
    IPC command socket. Accepts one command per connection; returns JSON. If WAYLAND_DISPLAY is unset, the fallback path is $XDG_RUNTIME_DIR/cow-cmd.sock.

$XDG_RUNTIME_DIR/cow-$WAYLAND_DISPLAY-status.sock
    Status broadcast socket. Emits a JSON state snapshot on each change. If WAYLAND_DISPLAY is unset, the fallback path is $XDG_RUNTIME_DIR/cow-status.sock.

SEE ALSO

moocow(1), cowbar(1), cowiconman(1), cowpager(1), river(1), wev(1), xdg-desktop-portal(1), xdg-desktop-portal-wlr(1), pipewire(1), wl-clip-persist(1)

AUTHORS

Thomas Adam <thomas@xteddy.org>

Parts of cow were derived from code under copyright by:

Nicholas Marriott