Command line & debug options
Mouseless accepts command line flags that give extra visibility into what’s happening under the hood, or override how the overlay is rendered on Linux.
Running from the command line
macOS
The only recommended way to run Mouseless from a terminal is with the open command, e.g.:
open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app --args -d
Flags for Mouseless go after --args.
Security advisory
Important: If you have ever run the internal binary directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please ensure you have revoked the Accessibility permission from your terminal app, otherwise any program launched from that terminal could potentially read screen content or log keystrokes.
To check your settings:
- Go to
System Settings > Privacy & Security > Accessibility. - Review the list. If your terminal application (e.g., Terminal, iTerm2) is present, select it and click the minus (-) button to revoke the permission.
Windows
Using PowerShell, single-user install (the default):
& "$env:LOCALAPPDATA\Programs\Mouseless\mouseless.exe" -d
All-users install:
& 'C:\Program Files\Mouseless\mouseless.exe' -d
Linux
flatpak run net.sonuscape.mouseless -d
Flags
| Flag | debug_options key | Description |
|---|---|---|
-d, --debug | — | Enables verbose debug output, visible in both the log file and the terminal. |
-p, --print-hid-events | — | Prints keyboard input and mouse output to the terminal (not logged to file). |
-P, --print-hid-events-verbose | — | Like -p, but also prints high-frequency mouse move, drag, wheel, and key repeat events. Implies -p. |
--diagnostics | — | Prints system graphics and display info, then exits. |
--links | — | Prints the supported deep link urls, then exits. |
--main-machine-hash, --trial-machine-hash | — | Prints the machine hash used for license / trial activation, then exits (useful in support contexts). |
--list-input-devices | — | (Linux) Prints /dev/input devices with their identity and how Mouseless classifies them (grab, exclude, ignore), then exits. Useful for filling in the excluded input devices config field. |
--overlay-renderer cairo | overlay_renderer | (Linux) Forces the cairo-backed overlay instead of the webview-backed one. Default when an NVIDIA GPU is detected. |
--use-dmabuf false | use_dmabuf | (Linux) Disables DMABUF rendering for webviews. Default when an NVIDIA GPU is detected. |
--use-layer-shell false | use_layer_shell | (Linux) Forces wlr-layer-shell on or off on Wayland. By default it is used when the compositor supports it; false forces the XWayland fallback. |
| — | overlay_offset | Shifts the overlay position by a pixel amount, e.g. { "x": 100, "y": -50 }. |
Notes:
--print-hid-eventsgives visibility into whether Mouseless is receiving certain keyboard events and how it’s interpreting them. To prevent accidental exposure, the printing will automatically disable after 5 minutes.- Most Linux rendering-related flags have an equivalent
debug_optionsconfig field, so they can be set persistently without launching from a terminal. - The cairo-backed overlay does not yet have the following features: highlight_animation, dots and dashed grid_line_styles, and always_show_subgrid.
- On macOS,
--standardand--compatibility(--compat) select the internal operating mode. Compatibility Mode is the default on Intel Macs and macOS < 14; Standard Mode is not supported on Intel hardware. These can also be set with theMOUSELESS_MODEenvironment variable.
Debug options
The debug_options field at the bottom of the config editor accepts a JSON object, and persists across restarts. For example:
{ "overlay_renderer": "cairo", "use_dmabuf": false }
{ "overlay_offset": { "x": 100, "y": -50 } }
See the table above for the available keys. For when to reach for these, see Troubleshooting.