.TH MOUSEBOARD 1 "2026" "mouseboard" "User Commands"
.SH NAME
mouseboard \- keyboard-driven virtual pointer for Wayland
.SH SYNOPSIS
.B mouseboard
.RI [ options ]
.SH DESCRIPTION
.B mouseboard
draws a labelled grid over every monitor. Type a cell's label to warp the
pointer there, refine the position by repeatedly bisecting the cell, then press
a key to click. It performs one action and exits.
.PP
Wayland does not allow a client to grab a global hotkey, so bind
.B mouseboard
to a key inside your compositor. It requires a wlroots-based compositor that
implements the
.B wlr-layer-shell
and
.B wlr-virtual-pointer
protocols.
.SH OPTIONS
.TP
.BI \-\-config " PATH"
Read configuration from
.IR PATH
instead of the default
.IR $XDG_CONFIG_HOME/mouseboard/config .
.TP
.BI \-\-cell\-size " N"
Target coarse-cell size in pixels (cols/rows are derived per monitor).
.TP
.BI \-\-cols " N" "\fR, \fP" \-\-rows " N"
Use an explicit grid instead of
.BR \-\-cell\-size .
.TP
.BI \-\-alphabet " STR"
Characters used to build cell labels.
.TP
.BI \-\-opacity " N"
Backdrop opacity, 0 to 100; 100 is a solid backdrop. Default 33.
.TP
.BI \-\-opacity\-fg " N"
Opacity of the labels, grid and crosshair, 0 to 100. Default 65.
.TP
.B \-\-dry\-run
Print "x y action" to standard output instead of moving or clicking.
.TP
.B \-\-selftest
Run offline checks of the label, bisection and config logic, then exit.
.TP
.BR \-h ", " \-\-help
Print usage and exit.
.TP
.BR \-V ", " \-\-version
Print the version and exit.
.SH KEYS
Defaults; see
.B config.example
for how to change them.
.TP
.B labels
type a cell label to select it
.TP
.B u i j k
keep the top-left, top-right, bottom-left, bottom-right quadrant
.TP
.B "m , . ; v"
left, middle, right, double-click, drag
.TP
.B Enter
left click (once a cell is selected)
.TP
.B Backspace
undo the last split, or return to the grid
.TP
.B Esc
cancel without clicking
.SH EXIT STATUS
.TP
.B 0
an action was performed (or printed, with
.BR \-\-dry\-run ).
.TP
.B 1
cancelled by the user.
.TP
.B 2
error (no display, unsupported compositor, bad arguments).
.SH FILES
.TP
.I $XDG_CONFIG_HOME/mouseboard/config
Per-user configuration.
.SH EXAMPLES
Bind it in sway:
.PP
.RS
bindsym $mod+g exec mouseboard
.RE
.SH SEE ALSO
.BR warpd (1),
.BR wl-kbptr (1)
.SH BUGS
On Linux only the wlroots Wayland backend exists; GNOME, KDE and X11 are not
yet supported. Windows is covered by a native Win32 backend.