Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Mouseless is a productivity / utility app that allows users to efficiently control the mouse with just the keyboard.

How to use these docs

The sidebar on the left lists all chapters. Click the hamburger menu (☰) to show or hide it.

To navigate to the next or previous chapter, use the arrow buttons at the side or bottom of the page or the Left and Right arrow keys on the keyboard.

Top menu bar

IconAction
Toggles the sidebar.
Opens the color theme picker.
Opens the search bar.
Prints the entire book.

Tapping the menu bar will scroll the page to the top.

Press the S key (or click the search icon () in the menu bar), to open the search bar.

Results are shown in real time. The Up and Down arrow keys can be used to navigate the results, and Enter will open the highlighted section.

Matched search terms will be highlighted in the text. Clicking a highlighted word or pressing the Escape key will remove the highlighting.

Single-page view / AI-assisted help

To view the docs in a single page, click the print icon in the menu bar, then cancel the print operation.

The content can then be copied and pasted into any AI chat for interactive Q&A about Mouseless.

Getting started

MacOS

To install (or update):

  • Download the .dmg file from https://mouseless.click
  • Open the .dmg file
  • Drag Mouseless.app into the Applications folder
  • If updating: choose “Replace” instead of “Keep both” when prompted

You can also install in the terminal via Homebrew:

  • brew install --cask mouseless (stable channel)
  • brew install --cask mouseless@preview (prerelease channel)

First time usage:

  • Open Mouseless (e.g. via spotlight search)
  • Read/agree to the terms of service
  • Start trial or activate
  • Give Mouseless the Accessibility permission when prompted
  • Restart the application for permissions to take effect
  • Enjoy!

Windows

To install (or update):

  • Download the latest Windows installer (.exe) or portable (.zip) file from https://mouseless.click
  • Run the installer (or extract the .zip)
  • If installing, choose whether to install for current user (no admin privileges required) or for all users (admin privileges required)
    • On subsequent installations / updates, the installer will use the previously chosen option. To override this, run the installer from the command line with the /ALLUSERS or /CURRENTUSER argument, e.g.: .\mouseless-installer_v0.4.2.exe /CURRENTUSER

First time usage:

  • Open Mouseless, e.g. via the start menu if installed, or if using the portable, by running the mouseless\mouseless.exe file in the extracted folder/location
  • Read/agree to the terms of service
  • Start trial or activate
  • Enjoy!

Linux

Wayland users: Please see the ‘Enabling keyboard/mouse access on Wayland’ section below before running Mouseless. If you’re unsure if you’re on Wayland or X11, run echo $XDG_SESSION_TYPE in a terminal.

  • From https://mouseless.click, download the .AppImage and .sha256sum file for your OS and architecture
  • Verify the download integrity: sha256sum -c <file>.sha256sum
  • Make the AppImage executable: chmod +x <file>.AppImage
  • Run the application: ./<file>.AppImage
  • Start a trial or activate with a license key
  • Enjoy!

Not working right? See this section for troubleshooting common issues.

Enabling keyboard/mouse access on Wayland

⚠️ Security Note / Context

Wayland’s security model prevents apps from having low-level access to keyboard and mouse devices. However, Mouseless requires this low-level access to: utilize global hotkeys; suppress input to apps without stealing focus; and generate mouse events.

This means you must disable Wayland’s extra restrictions around keyboard/mouse access for Mouseless to work, i.e. adopt a security model equivalent to X11’s. This affects all programs run by your user, not just Mouseless, though there are some alternatives for advanced users mentioned at the bottom.

Method 1 (udev rules)

  1. Add these rules to allow your user to access input devices:
sudo tee /etc/udev/rules.d/99-mouseless-input.rules <<EOF
# Output: Virtual device creation
KERNEL=="uinput", GROUP="$USER", MODE:="0660"

# Input: Physical device reading
KERNEL=="event*", GROUP="$USER", NAME="input/%k", MODE:="0660"
EOF
  1. Reload the system rules:
sudo udevadm control --reload-rules && sudo udevadm trigger

Method 2 (fallback)

If you still see udev-related errors or ‘no keyboards detected’ errors when starting Mouseless, this method should work for you.

  1. Undo rule creation from step 1:
sudo rm /etc/udev/rules.d/99-mouseless-input.rules
  1. Create a systemd temporary file configuration:
# Forces current user/group ownership on input devices
sudo tee /etc/tmpfiles.d/mouseless-input.conf <<EOF
z /dev/uinput       0660 $USER $(id -gn) - -
z /dev/input/event* 0660 $USER $(id -gn) - -
EOF
  1. Apply the permissions:
sudo systemd-tmpfiles --create /etc/tmpfiles.d/mouseless-input.conf

Hotplugging note: The changes made in method 2 persist across reboots, but if you plug in any keyboards after startup, you may need to run the systemd-tmpfiles command (step 3) again to apply permissions to them.

Alternatives (advanced)

Run as root

Instead of changing Wayland’s input security, you can simply run Mouseless with sudo. The security implication here is that if a malicious process hijacks the Mouseless process, it will have root access to your system.

Create a dedicated user

You can create a separate system user and assign the needed permissions, then run Mouseless as that user. However, running a GUI app as a different user on Wayland is complex and requires manual configuration to allow the app to connect to your display session.

If you figure out a reliable configuration for this, please share! I’d be happy to post community-contributed guides, even if they are specific to certain distros or compositors.

Using Mouseless

Note: these docs currently show the default keybindings. If a command is unassigned by default, the command name is used instead.

To view/edit the keybindings and other options, press Tab (edit config command) while the overlay is showing, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux).

Clicking, moving, and dragging

With free mode

Free mode allows for relative movement, with no overlay needed to move, click, or drag.

Activating / deactivating

To activate free mode, use the enter free mode command or toggle free mode command (OptionLeft tap on Mac, ControlLeft tap on Windows and Linux).

To exit free mode, use the exit free mode or toggle free mode command.

Auto-off

By default, free mode turns off automatically after 10 seconds without usage (adjustable via the Free mode auto off option; set to 0 to disable).

Actions in free mode

While free mode is on:

  • to move, use I, K, J, and L
  • to click or click+drag, use Space (left mouse button), R (right), E (middle), Q (back), and W (forward) as if they were mouse buttons
  • to increase movement (or wheel) speed, use S, D, and F – the more of them you hold, the greater the increase
  • to decrease movement (or wheel) speed, hold A

With the overlay

Showing/hiding the overlay

  • To show the overlay, tap the CommandLeft (ShiftLeft on Windows and Linux) key (show overlay command)
    • Note: this is a tap command by default, so you must press and release the key relatively quickly for it to register (< 0.2 seconds by default, see Tap vs keydown for more info)
  • To hide the overlay press the Escape key (hide overlay command)

Actions in overlay mode

  • To click:

    • while the overlay is showing, type the two characters of any given cell to choose that cell
    • then press Space to click at the center of the cell, where the virtual cursor is (execute mouse action command)
      • OR press any character you see in a sub-cell to click at that sub-cell
    • you can press Space any time the overlay is up to click where the virtual cursor is (or where the system cursor is if no cell has been selected and Initial action location is set to system_cursor)

  • To right click:

    • hold the Shift key (CommandRight on Mac) key while pressing the final key of a click action (hold for right button command)
    • use the cycle mouse button command to choose right, then execute a mouse action

  • To use other mouse buttons, use the appropriate hold for command, or the cycle mouse button command, in the same way as described above for right clicking

  • To double-click or triple-click, either:

    • press the final key of a click action multiple times within the multi-click threshold
    • use the cycle click count command

  • To click-and-drag / drag-and-drop, use the hold for drag command, i.e.:

    • to begin the drag: hold the AltLeft key (CommandLeft on Mac) key while pressing the execute mouse action hotkey or a subgrid key
      • the overlay will remain up for you to choose the point you want to drag to or drop at
      • to drag to a point (without releasing the drag), hold the AltLeft key (CommandLeft on Mac) on subsequent execute mouse action / subgrid key presses
      • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)
    • to release/drop: enter in a click-coordinate as normal, without holding the hold for drag hotkey

  • Click-and-drag alternative: you can also use the cycle mouse action command to set the action to be performed. During a drag, it cycles between drag and drop.

  • To move the mouse cursor:

    • tap AltLeft (OptionLeft on Mac) while the overlay is up (execute mouse move command)
    • hold the key assigned to the hold for move command during the final keypress of a a mouse action
    • use the cycle_mouse_action command to set the action to move

  • To repeat the last action executed, use the repeat last mouse action command

Extra precision: Cursor nudges

If you need to click or move to small targets in between subgrid points, you can use ‘nudges’ as follows.

  1. Ensure the hold subgrid key for nudge setting is ON in each grid config in the Grid Options section of the config editor.
  2. Ensure the Subgrid nudge commands are assigned keys in the Keymap section. The default values give each command both a left-hand keybinding and a right-hand keybinding (assuming a QWERTY layout), so that nudges can be executed regardless of which subgrid key is held.
  3. To execute a nudge:
  • Activate the overlay, and select a cell to bring up the subgrid.
  • Instead of tapping a subgrid key to immediately execute a click, hold the subgrid key nearest to your target.
  • While this key is held, use the subgrid nudge hotkeys to move the cursor.
  • When the cursor is in the desired location, simply release the subgrid key you’ve been holding to execute the click.
  1. The nudge size / precision can be adjusted with the nudges per cell setting in the Grid Options section.

Global mouse buttons

These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.

Use cases include:

  • clicking while maintaining precise cursor position/movement
  • preventing/alleviating repetitive strain injury
  • user preference over other clicking mechanisms

To use these commands, in the Keybindings -> Global mouse buttons section of the config editor, assign a key or key combo that won’t interfere with your regular keyboard usage. All five mouse buttons (left, right, middle, back, and forward) can be assigned to. After assigning, you should then be able to use keyboard keys as mouse buttons, without having to bring up the overlay or activate free mode.

Modifier clicks (or other actions)

Modifier clicks are available in both overlay and free mode.

If a modifier key is held during a mouse action, and isn’t assigned to a hold for command, a native mod+mouse event will be simulated. In other words, to execute a shift+click (e.g. to select a group of items in file explorer):

  • Select a cell in the overlay, or position the mouse cursor in free mode
  • Hold shift
  • Execute the mouse action (e.g. by pressing Space or a subgrid char)
  • Then release shift

Note: Some Linux distros may have only partial or no modifier click functionality. More testing to come, and reports are welcome.

Wheel / scrolling

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows and Linux (toggle free mode command) to enter and exit free mode.

While in free mode, use:

  • M, ,, ., and / to scroll up/down/left/right
  • S, D, and F to increase the speed (the more pressed, the greater the increase)
  • A to decrease the speed

There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, and on Mac and Windows there are jump to top/bottom/left/right to jump to the edge of a scrollable area.

To adjust scrolling speed / step sizes, as well as auto off duration, see the Free mode subsection of the Behavior section in the config editor.

See here for the rest of the free mode controls / capabilities.

Multiple monitor usage

  • To move the overlay between monitors, tap the ShiftLeft or ShiftRight keys while the overlay is visible.

  • To assign different grid configs to different monitors:

    • In the Grid Options section of the config editor, use the + and - buttons to add/remove grid configs
    • With monitor assignment mode set to auto, the first grid config will be assigned to monitors with a horizontal aspect ratio, and the second will be assigned to monitors with a vertical aspect ratio
    • For more customized assignment, set monitor assignment mode to custom, and use the custom monitor assignments field to assign grid_config names to specific monitors
  • To open the config editor, press the Tab key while the overlay is up (edit config command)
  • To close dialogs, tooltips, etc, press the the Escape key (close ui element command)

Customizing Mouseless

The config editor

  • To open the config editor, press Tab while the overlay is visible, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux),
  • Many tooltips are available for in-context guidance. To see them, hover over:
    • The label on many fields
    • Some built-in presets
    • The info icons next to some sections
    • The info icon at the bottom-left of the config editor
  • Changes you make are applied automatically
  • The config editor is searchable via ctrl+F (cmd+F on Mac)
  • To save, hit the save button (or press cmd+S on Mac)
  • To save/load presets, or restore saved or defaults use the kebab menus in the section/subsection headers
    • To update or delete a user preset, right-click it to show a context menu
  • To restored saved or default values for a single field, right-click the field to show a context menu
  • Use the kebab menu at bottom to import a config file, export a config file, or restore defaults for the entire config

Field editing tips

  • You can press Enter in a text field to make it validate / take effect. Leaving the text field with Tab or the mouse also works.
  • Colors can be copied and pasted (with ctrl+C and ctrl+V (command on Mac)) while focused, or by dragging and dropping from one to another. The copied format is hex (e.g. #4e6c95).

Manually managing config files

  • You can choose Open config folder from the Mouseless menu, and edit/duplicate/delete files at will. config.yaml is the one loaded at app startup.

    • NOTE: if the config.yaml file is removed, or modified in such a way that it has invalid syntax or values, the default config values will be used the next time the app is started.

  • The location of the config file is:

    • Mac:
    ~/Library/Containers/net.sonuscape.mouseless/Data/.mouseless/configs/config.yaml
    • Windows:
    ~/AppData/Local/Mouseless/configs/config.yaml
    • Linux:
    ~/.mouseless/configs/config.yaml

NOTE: the information for each field that follows is largely the same as is found in the in-app tooltips

Grid (overlay) options

The dimensions and content of an overlay is determined by a ‘grid config’.

  • To add or remove a grid config, use the + / - buttons under the lowest grid config.

Grid config fields

  • Level _ columns: The number of cells across the X dimension at this level.
  • Level _ rows: The number of cells along the Y dimension at this level
  • Level _ keys: The keys you press to select a cell at this level. They wrap to multiple rows if necessary. Note: If left blank for level 2 or subgrid, the keys from level 1 will be used.
  • Always show subgrid: Shows a subgrid in every cell, all the time, which can make it easier to know ahead of time which sub-cell you’ll want to click. This comes at the cost of more visual noise, however. Currently only available whengrid line style is set to lines.
  • Hold Subgrid Key For Nudge: When on, holding a subgrid key allows you to use the subgrid nudge commands to move the cursor, then release the subgrid key to execute the action.
  • Nudges per cell: Determines nudge size. I.e. if set to 4, then 4 nudges will move the cursor to the same point in next subgrid cell.

Monitor assignment fields

  • Monitor assignment mode: Controls how grid configs are assigned to monitors.
    • auto: the first grid config gets assigned to horizontal monitors, and the second gets assigned to vertical monitors.
    • single: the first grid config gets assigned to all monitors.
    • custom: grid configs are mapped by name, via the custom monitor assignments field.
  • Custom monitor assignments: List of grid config names, separated by comma+space (e.g. A, B). The first is assigned to the primary monitor, the second to the second monitor, and so on.

Behavior options

Overlay / cursor

  • Initial overlay monitor: The monitor that the overlay will appear on when shown.
  • Initial action location: Determines where mouse actions are executed (via execute mouse action) when no cell is selected.
  • Grid action level: Determines the grid level that mouse actions get executed at (i.e. how many keypresses it takes). Use the cycle grid action level command to change this value while the overlay is up.
    • subgrid: When a leaf cell is selected, a subgrid is shown and Subgrid keys are used to execute an action.
    • 2 or 1: When a cell at the given level is selected, a mouse action is executed immediately, at its center.
  • Hide cursor on click: When on, the cursor moves out of the way after a click is executed.
  • Hide location: The corner or edge of the clicked screen that the cursor will move to. You can choose any edge (top/bottom/left/right) or corner (top_left/top_right/bottom_left/bottom_right).

Movement / timing

  • Move duration (ms): The time taken to move the mouse cursor during move and drag actions.
  • Move system cursor with virtual: When this is on, the system cursor will smoothly move as you select a cell, following the virtual cursor.
  • Multi-click threshold (ms): For double and triple clicks, this sets the maximum time that can pass between keypresses before it no longer triggers a native double or triple click.
  • Tap threshold (ms): For tap-triggered keybindings, this is the maximum time a key can be down before its no longer considered a tap.

Free mode

  • Base move speed (px): The amount the mouse cursor moves each tick during move up/down/left/right commands.

  • Move speed multiplier: Movement speed is multiplied by this amount for each hold for speed increase hotkey held.

  • Movement easing factor: Controls the smoothness / acceleration of cursor movement. 0.1 = loose, 0.2 = natural, 0.3 = snappy, 0.9 = instant.

  • Base wheel speed: The amount scrolled each tick during wheel up/down/left/right commands. Measured in pixels on Mac, lines on Windows.

  • Wheel speed multiplier: This multiplier gets applied:

    • to the fast mouse wheel actions
    • when hold for speed increase is active
    • when multiple keys for the same direction are pressed.

  • Wheel easing factor: Controls the smoothness / acceleration of wheel movement. 0.1 = loose, 0.2 = natural, 0.3 = snappy, 0.9 = instant.

  • Wheel step size: The amount scrolled each time a wheel step command is executed.

  • Wheel step size large: The amount scrolled each time a wheel step _ large command is executed.

  • Free mode auto off (seconds): If no actions are done for this many seconds, free mode will turn off. Set to0 to disable.

Misc

  • Send escape after global alt tap (Windows): Simulates a press of the Escape key after certain global commands (e.g. show overlay, enter free mode) are triggered by an AltLeft/Right tap. Helps to deactivate the focused app’s menu bar (which typically activates when Alt is tapped).,

Style / Appearance options

  • Master opacity: Overall opacity of the overlay. Multiplicative with other opacities – e.g. if master opacity is 0.5 and and background opacity is 0.8, the final background opacity will be 0.4 (40%).
  • Color input mode: The extra text input to show for editing color values. Note that rgb hex values (e.g. #ff0000) can always be copied/pasted while the color picker element is focused.

Background

Note: These fields are available in the v0.5 preview. Only background color is present in v0.4.

See this youtube video for an explanation / demonstration of the multi-color system.

  • Background colors: The colors/opacities of the top-level cells, including underneath the highlight.
  • Color block size: Number of level 1 cells each background color is applied to, before cycling to the next. If set to 0, the colors are distributed evenly; e.g. if there are 30 top level cells and 3 colors, each color block will be 10 cells across.
  • Use color transforms Allows you to create variations of the base background colors across top-level cells, as well as create visually distinct regions within top-level cells.
  • BG Color Transforms - Level 1: Use these to transform the cells within each color block by adding or multiplying HSLA values (hue, saturation, lightness, alpha). Use “hsla_add” or “hsla_mult”, respectively. This can be convenient for distinguishing columns and/or rows within each color block. Editing the base background color(s) will shift all the transformed colors accordingly.
  • BG Color Transforms - Level 2: Use these to transform the background colors of 2nd-level cells. This allows you to create visual blocks within each top-level cell, e.g. to distinguish left hand keys from right hand keys in the subgrid, and/or top/middle/bottom keyboard rows.

Highlight

  • Highlight color: The color given to the currently active cell(s) of the overlay.
  • Highlight animation (ms): The time it takes (in milliseconds) for the highlight to move/scale to its new location and size. Set to 0 for instant movement.
  • Show initial highlight: When on, the highlight will be shown before any cells are selected, covering the entire overlay. Useful when background opacity is zero.

Grid

  • Grid line style: Note: Currently, Always show subgrid is only available for the lines style.
  • Grid line width (px): Note: Subgrid lines use this value only if grid line style is dots, otherwise they are assigned 1.
  • Grid line color: The color/opacity of the main grid lines.
  • Subgrid line color: The color/opacity of the subgrid lines.

Text

  • Font: The font used in the overlay. You can use the cycle font command to change this while the overlay is up.
  • Font weight: Controls the boldness/lightness of the text. The actual effect varies by font.
  • Y offset: Moves the text up/down, by an amount scaled to the font size. This helps correct positioning for fonts that are not vertically centered.
  • Font size multiplier: Scales the size of the characters within the main grid.
  • Subgrid font size multiplier: Scales the size of the characters within the subgrid.
  • Char display: Controls which characters are shown in each cell.
  • Char spacing strategy: Sets how the spacing of characters within a cell is adjusted: cell_width_relative, font_size_relative, or evenly_spaced.
  • Char spacing cell width ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be evenly spaced across cells
  • Char spacing font size ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be about as far apart as an uppercase character is tall
  • Text color: The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn’t show through the text.
  • Subgrid text color: “The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn’t show through the text.
  • Text shadow rgba: The opacity value here is in addition to what gets applied by the text color opacity (e.g. if both are 0.5, the shadow opacity is effectively 0.25).

Cursor

  • Cursor size: The size (width and height) of the virtual cursor, in pixels.
  • Cursor color: The color/opacity of the virtual cursor in its default state.
  • Cursor right button color: The color/opacity of the virtual cursor when hold for right button is active or cycle button has been used to set the button to right.
  • Cursor move color: The color/opacity of the virtual cursor when hold for move is active or cycle action has been used to set the action to move.
  • Cursor drag color: The color/opacity of the virtual cursor when hold for drag is active or cycle action has been used to set the action to drag.
  • Cursor other color: The color/opacity of the virtual cursor when not in one of the states above.

Keybindings / command reference

The Keymap section of the config editor allows you to customize program keybindings

A condensed form of much of this info is available in-app in the Keymap section’s info icon tooltip.

Note: if a key is present in the overlay at the current grid level, as well as a keybinding in the keymap, the overlay will take precedence.

Key names

The key names used/accepted mostly follow web conventions, with some exceptions, and some allowances for aliases.

  • Printable non-whitespace characters just use the literal character
    • A through Z, 0 through 9, -=`[]\;',./
      • Note: the non-shifted version of non-alpha characters should be used (e.g. 1 instead of !), and the uppercase version of alpha characters should be used (A instead of a, to avoid ambiguity with modifier shorthands (upcoming feature))
  • Whitespace characters are named:
    • Space, Tab, Enter
  • Modifier keys
    • Allowed aliases:
      • Command/Cmd/Meta/Win/Gui
      • Alt/Option/Opt
      • Control/Ctrl
    • Left/right-specific, or universal versions
      • e.g. Shift, ShiftLeft, or ShiftRight
      • Note: side-specific modifier keys are not yet supported as modifiers, only as main keys.
  • Other named keys list
    • ArrowLeft, ArrowRight, ArrowUp, ArrowDown
    • Numpad0 through Numpad9, NumpadAdd/Subtract/Multiply/Divide/Decimal/Equal/Comma/Enter
    • F1 through F20, Fn
    • Backspace, Delete, Escape, PageUp, PageDown, Home, End, Insert
    • NumLock, CapsLock
    • ContextMenu, VolumeUp/Down/Mute
    • Lang1, Lang2, IntlYen (¥), IntlRo (ろ), IntlBackslash

Assigning multiple keybindings to a command

To assign multiple keybindings to a single command, separate them with , (note the space). E.g. Escape, CommandLeft tap.

Tap vs keydown

Actions can be triggered either by a keydown event, or by a tap – a downstroke and upstroke of the same key within tap_threshold milliseconds, uninterrupted by other keys.

To specify a tap keybinding, simply add tap (with a space) after the keyname, e.g. CommandLeft tap. CommandLeft on its own as a keybinding will cause the action to be triggered on the key downstroke (which can make interaction a bit snappier).

Double and triple taps

To assign a double or triple tap, use double tap or triple tap at the end of the hotkey, e.g. CommandLeft double tap or alt+R triple tap

Using modifiers as…modifiers

To add a modifier to a keybinding in the usual way (like it is used for cmd+C for copy, cmd+S for save, etc), put them before the main keypress with a +, e.g.:

  • cmd+Tab
  • cmd+Tab tap
  • cmd+alt+shift+ctrl+Tab

The same aliases (see Key names) are allowed as when the modifier is used as the main key.

Key order

Note that the main key in a keybinding must be the one that is pressed last, and if it’s a tap key binding, it must also be released first.

E.g. cmd+Ctrl tap requires: cmd down -> ctrl down -> ctrl up

QMK and similar firmware often have hyper key macros that have a first-in first-out press/release order (e.g. cmd down -> ctrl down -> cmd up -> ctrl up), which does not work with tap commands that have a modifier as the main key (though the non-tap command should work with the right modifier as the main key).

Command reference

Note: This information is largely the same as the in-app tooltips when you hover over the command name.

Overlay

  • Show overlay: Shows the overlay.
  • Hide overlay: Hide the overlay, without executing any mouse action.
  • Move to next monitor: Moves the overlay to the next to the next monitor.
  • Move to previous monitor: Moves the overlay to the previous monitor.
  • Increase master opacity (currently Mac-only): Increases the master opacity value.
  • Decrease master opacity (currently Mac-only): Decreases the master opacity value.
  • Toggle overlay lock (beta): When locked, the overlay will not respond to keypresses, and keypresses will pass through to focused app. May be useful while editing the config. This is a beta feature, and not fully implemented – some commands will still affect the overlay.
  • Toggle continuous mode: When continuous mode is on, the overlay stays up after executing a mouse action.
  • Toggle continuous mode until closed: Continuous mode will be turned off after the overlay is hidden.
  • Cycle grid action level: Cycles the value of the Grid action level field.
  • Cycle font: Cycles the value of the Font field.

Mouse actions

  • Execute mouse action: In the default state, executes a left click at the virtual cursor. Can execute other actions/buttons/click_counts if hold for or cycle commands are used. Double and triple clicks can be executed by pressing multiple times.
  • Execute mouse move: Moves the system cursor to the virtual cursor.
  • Undo last key: Undoes the last key when selecting a cell.
  • Release hold/drag: During a drag action, ‘drops’ at the system cursor.
  • Repeat last mouse action: Repeats the last mouse action, at the same location it was executed at.
  • Hold for move: When held, execute mouse action will move the system cursor to the virtual cursor.
  • Hold for drag: When held, execute mouse action will start (or continue) a drag operation (i.e. moving the mouse while mouse button is held down).
  • Hold for right/middle/back/forward button: When held, execute mouse action will execute a right/middle/back/forward click at the virtual cursor.
  • Cycle mouse action type: Sets the action (click, move, drag) that execute mouse action will trigger.
  • Cycle mouse button: Sets the mouse button (left, right, middle, back, forward) that execute mouse action will use.
  • Cycle click count: Sets the click count (single click, double click, triple click) that execute mouse action will trigger.

Subgrid nudge

  • Subgrid nudge up/down/left/right: These commands move the cursor when hold subgrid key for nudge is on and a subgrid key is held.
    • Note: If you use keys that are also present in the subgrid, you should give each command a key for the left hand and the right hand.

Dialog / menu

  • Edit config: When the overlay is up, opens this config editor.
  • Close UI element: Closes the currently open dialog, color picker, context menu, etc.

Global mouse buttons

  • left/right/middle/back/forward: These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.
    • Use cases include:
      • clicking while maintaining precise cursor position/movement
      • preventing/alleviating repetitive strain injury
      • user preference over other clicking mechanisms

Free mode

  • Toggle free mode: Toggles free mode.
  • Enter free mode: Activates free mode.
  • Exit free mode: Deactivates free mode.
  • Hold for speed increase: Multiples the scroll speed by the wheel speed multiplier value. The more keys assigned to this and held, the greater the increase.
  • Hold for speed decrease: Divides the scroll speed by the wheel speed multiplier value. The more keys assigned to this and held, the greater the decrease.
  • Move up/down/left/right: Moves the system mouse cursor.
  • Wheel up/down/left/right: Executes smooth/continuous scrolling while held.
  • Wheel up/down/left/right fast: Executes smooth/continuous scrolling while held, with the wheel speed multiplier applied.
  • Wheel step up/down/left/right: Executes a discrete scroll event, the amount determined by the wheel step size setting. Responds to system ‘autorepeat’ when a key is held.
  • Wheel step up/down/left/right large: Executes a discrete scroll event, the amount determined by the wheel step size large setting. Responds to system ‘autorepeat’ when a key is held.
  • Jump to top/bottom/left/right edge (experimental) (Mac/Windows-only): Executes a very large wheel event, to move the scrollable view to the given edge.

Troubleshooting

Debug modes

Running Mouseless from the command line with certain flags provides extra visibility into what’s happening under the hood.

-d: enables verbose debug output, visible in both the log file and the terminal.

-p: prints keyboard input and mouse output to the terminal (not logged to file). To prevent accidental exposure, the printing will automatically disable after 5 minutes. This mode gives visibility into whether Mouseless is receiving certain keyboard events and how it’s interpreting them.

Examples:

macOS

open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app --args -d

Windows (using Powershell)

& 'C:\Program Files\Mouseless\mouseless.exe' -d

Linux

./<filename>.AppImage -d

macOS Input Issues

Important Security Advisory

On 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).

If you have ever run Mouseless from the terminal by executing the file inside the .app bundle directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please take a moment to ensure you have revoked the Accessibility permission from your terminal app(s). Leaving this permission enabled for a terminal app presents a security risk, as 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.

Password fields

The overlay (and keybindings involving printable characters generally) will not respond when in a password field or other field marked as sensitive. This is not a bug, but a result of MacOS’s ‘Secure Input’ mode, which prevents applications from reading keyboard input while in these fields. To continue using Mouseless, simply leave the field (e.g. by pressing Tab).

Hotkeys don’t work on app startup

If you ever encounter an issue where hotkeys don’t work on app startup, these steps have proven to help in most cases:

  1. exit Mouseless
  2. delete the Accessibility permission for Mouseless
    • make SURE Mouseless isn’t running while you do this – MacOS tends to lock you out of keyboard and mouse input if you delete this permission from a running process / active event tap
    • System Settings > Privacy and Security > Accessibility > select Mouseless and click the - button
  3. Re-add the permission (either via the + button or by restarting Mouseless)
  4. Restart Mouseless

Hotkeys stop working during app usage

There may be a chance that this happens due to MacOS getting stuck in ‘Secure Input’ mode. There is a Check Secure Input Status button at the bottom of the config editor to check if this is the cause.

Espanso has a good explainer on this issue, as well as some potential workarounds to get un-stuck (the last resort is to log out your MacOS user and log back in).

BetterTouchTool conflicts

If you’re having issues with BTT hotkeys erroneously triggering the Mouseless overlay, a user has kindly provided this config / example, which may help you keep the same BTT hotkey, but without triggering Mouseless.

General conflicts with other keyboard utility apps

Apps like Mouseless, Karabiner, etc. can suppress keypresses from being dispatched to the rest of the system. Depending on the configuration of other apps, some hotkeys may cause Mouseless keybindings to trigger when not expected.

For example, if alt+F is assigned an action in Karabiner, and Alt tap is assigned to show overlay in Mouseless, karabiner might allow the alt press and release through to the rest of the system, but block the F press/release. If it’s all pressed quickly enough, Mouseless might register this as Alt tap and display the overlay, as it has no visibility of the F key events.

If you experience such issues, lowering the tap_threshold setting might help prevent most false triggers, otherwise you might need to adjust keybindings in one app or the other.

On macOS, you can try changing the event tap location to see if this alleviates these conflicts. It’s found in the System / debug section at the bottom of the config editor.

Windows Input Issues

Autohotkey

To use a Windows key tap without triggering the start menu, use this: ~LWin::vkE8 (see reddit thread)

Linux - Common Issues

Blank Windows

This is likely the result of GPU/driver compatibility issues.

  • Solution: You can use the --no-compositing CLI flag or WEBKIT_DISABLE_COMPOSITING_MODE=1 environment variable to fix this
  • Side effect: When using this mode, the overlay may not clear its draw buffer correctly, causing highlights and subgrids to stay visible when they shouldn’t. Background and highlights accumulate opacity, but typically clear approximately every 5 uses of the overlay.
  • Workaround: There is a minimal_background style preset that helps alleviate the opacity buildup side effect.

I have a suspicion/hope that this issue might be resolvable with proprietary drivers (see solution/disclaimer in the “Segmentation Fault” section just below). If you find this to be the case, please let me know!

Segmentation Fault on Startup

Observed on Linux Mint 22: the app crashes with a ‘segmentation fault’ error in the terminal on startup.

  • Solution: You may find that installing proprietary drivers (as opposed to ‘Mesa’ drivers) solves the issue for you – see this user-provided guide for more info / instructions.
  • Disclaimer: update drivers at your own risk. The creators of Mouseless are not liable for any issues that may arise from doing so.

‘Cannot Execute’ AppImage errors

If, when running Mouseless, you see a terminal message like: cannot execute: required file not found

Or the more specific error: dlopen(): error loading libfuse.so.2: cannot open shared object file

…you are likely missing the FUSE 2 library, which is no longer pre-installed on many modern distributions.

Here are the common packages needed to run AppImages:

  • On Fedora:

    sudo dnf install fuse-libs

  • On Debian 13+ / Ubuntu 24+:

    sudo apt install libfuse2t64

  • On Debian 12 / Ubuntu 22:

    sudo apt install libfuse2

See issue #445 for context.

Overlay Size

Mouseless does its best to automatically determine and account for system DPI scaling to correctly size and position the overlay(s). Some users however, may need to do one of the following:

Starting in v0.5.0-preview.2: you can use the overlay_scaling setting at the bottom of the config editor to adjust the overlay size. The prior method below is still available until overlay_scaling is battle-tested.

Prior method (< v0.5.0-preview.2):

  • Use the --dpi-scale CLI option to force a certain scale. The value is your system’s DPI divided by 96 (the default). For example, for a system with 192 DPI, use --dpi-scale 2.0.
  • Use --dpi-scale 1 to counteract the effects of the automatic process

Mouse Position

If you find that mouse click positions don’t line up with the overlay:

Starting in v0.5.0-preview.2: you can use the mouse_scaling and mouse_screen_offset_scaling settings at the bottom of the config editor to adjust mouse click locations. The prior method below is still available until these settings are battle-tested.

Prior method (< v0.5.0-preview.2): you can currently use the debug options field (at bottom of config editor) to enter JSON to fix this (adjust values as needed):

{ "mouse_screen_position_mult": 1, "mouse_screen_size_mult": 1.25 }

Network Proxies / SSL Issues

As of v0.4.2, Mouseless now uses the system certificate store, which, for many corporate users, should eliminate the need to specify an SSL certificate to successfully activate / validate your license.

If you still have SSL, proxy authentication, or other network-related issues, please contact support and we will work on getting Mouseless to ‘just work’ in all cases. The old instructions may allow you to use Mouseless in the meantime:

Specifying a Custom Cert (Prior Method)

  1. Obtain the custom cert (.pem) file from your IT department
  2. On macOS, move/copy the .pem file to the Mouseless data dir, e.g.: $ cp cert.pem ~/Library/Containers/net.sonuscape.mouseless/Data/
  3. Open Mouseless via the command line like so:
  • macOS
REQUESTS_CA_BUNDLE=~/Library/Containers/net.sonuscape.mouseless/Data/cert.pem open Mouseless.app
  • Windows (powershell)
$env:REQUESTS_CA_BUNDLE="path\to\cert.pem"; & 'C:\Program Files\Mouseless\mouseless.exe'
  • Linux
REQUESTS_CA_BUNDLE=path/to/cert.pem ./<filename>.AppImage

Air-gapped / Networkless Activation

For those who use an air-gapped machine, or whose organization has strict network restrictions, an offline licensing procedure is available (as of v0.4.3). Simply choose the “Offline Licensing” option in the introductory dialogs before activation, or after activation, from the Mouseless menu (Tools -> Offline licensing).

Roadmap

November 2025

  • Wayland compatibility (done in current preview release)

December 2025

  • Online training tool
  • Comprehensive tutorial videos

February 2025

  • v0.5 stable release

Key enhancements

v0.5 (upcoming)

  • Improved welcome / tutorial
  • Customizable config location - #110, #187
    • Workaround: use a hard link: ln ~/.config/mouseless/config.yaml "$HOME/Library/Containers/net.sonuscape.mouseless/Data/.mouseless/configs/config.yaml"
  • Monitor selection improvements
    • Direct selection via hotkey - #324
    • Single overlay across multiple monitors
  • Zoom on subgrid for readability - #53, #320
  • Improved precision
    • Shift/case sensitive overlay keys
    • Additional grid level
  • Preserve comments and field order in config file - #129
  • Allow wheel movement while overlay is up - #194
  • New wheel-related hold for commands (hold for wheel mode, stepped scrolling)
  • Hide inactive portion of overlay - #261
  • Improved preset management - #303
  • Show status toast on active overlay/monitor - #318

Done in current preview release:

  • Multi-color backgrounds
  • Modifier clicks on Windows