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

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
    • Note: The latest versions (v0.4.4 and v1.0.0-preview.5) fix some issues with the prompt not showing or the app going silent – if you still see these issues, refer to the solution here.
  • Restart the application for permissions to take effect
  • Enjoy!

To run Mouseless on startup:

As a sandboxed app, Mouseless can not add itself as a ‘Login Item’, so you must do this:

  1. Open ‘Login Items’ via spotlight search
  2. Click the ‘+’ button
  3. Add Mouseless.app

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 page before running Mouseless (also, be sure to download the 1.0 preview release). If you’re unsure if you’re on Wayland or X11, run echo $XDG_SESSION_TYPE in a terminal.

Flatpak

Flatpak is a package manager that allows apps to have self-contained dependencies (either in the app itself or in standardized runtimes) for cross-distro compatibility.

The Mouseless developer(s) host their own flatpak repo, which means releases/updates are GPG-signed to verify their authenticity. (GPG key, fingerprint: C739 2023 E17C 0B73 1291 668E 1D97 183A C9AF 10C4)

There is also a standalone bundle, but it requires manual updates (download latest bundle and re-install).

Recommended install method (flatpak repo):

# Add GPG-signed repo
flatpak remote-add --user --if-not-exists sonuscape \
  https://dl.sonuscape.net/flatpak/sonuscape.flatpakrepo

# Install mouseless (stable channel)
flatpak install net.sonuscape.mouseless

# Run
flatpak run net.sonuscape.mouseless
  • Uses the GPG-signed dl.sonuscape.net repo
  • Allows for easy updates via flatpak update / software managers
  • Ensures Mouseless displays correctly in software manager apps
  • Enables other (future) Sonuscape software to show up in searches and be easily installable
  • For the preview channel, use flatpak install net.sonuscape.mouseless//preview

Method B (.flatpakref file):

# Install mouseless
flatpak install --user \
  https://dl.sonuscape.net/flatpak/net.sonuscape.mouseless.flatpakref

# Run
flatpak run net.sonuscape.mouseless
  • Uses the GPG-signed dl.sonuscape.net repo
  • Allows for easy updates via flatpak update / software managers
  • Compared to the full repo method (above):
    • May have degraded UX in software managers
    • Does not enable other Sonuscape software to be findable in your software manager
  • For the preview channel, use flatpak install --user https://dl.sonuscape.net/flatpak/net.sonuscape.mouseless.preview.flatpakref

Method C (standalone .flatpak file):

# Download latest bundle and .sha256sum
curl -LO https://dl.sonuscape.net/flatpak/bundle/mouseless/latest/Mouseless.flatpak
curl -LO https://dl.sonuscape.net/flatpak/bundle/mouseless/latest/Mouseless.flatpak.sha256sum

# Verify download, then install only if it passes
sha256sum -c Mouseless.flatpak.sha256sum && \
  flatpak install --user ./Mouseless.flatpak

# Run
flatpak run net.sonuscape.mouseless
  • Does not use the repo (self-contained file)
  • Updates must be performed manually (download latest and re-install)
    • In-app update notifications are still available (if not disabled)
  • Index of available bundles here
  • For the preview channel, change the filenames in the commands to Mouseless.preview.flatpak

Notes:

  • All three methods will install the official GNOME runtime (~400MB) if not already present on your system.

    • If you don’t already have the Flathub remote, the installer offers to add it; confirm with y

  • Software manager integration: After installing with the commands above, Mouseless should appear in your default software manager GUI (e.g. GNOME Software). You can also install by downloading the sonuscape.flatpakrepo, double clicking it to open in your software manager, then search for/install Mouseless and run it from there or your system launcher. Note: the software manager may only display the stable branch.

  • Older distros: you may see errors like URI .../summary exceeded maximum size (seen on Ubuntu 20 w/ flatpak 1.6). To fix this, you need a newer version of flatpak than may be available from your default repository:

    sudo add-apt-repository ppa:flatpak/stable   # maintained by Flatpak team
sudo apt update && sudo apt install flatpak

Uninstall:

Mouseless: flatpak uninstall net.sonuscape.mouseless

Repo: flatpak remote-delete sonuscape

Pinning a specific version (prevent updates):

Current version:

flatpak mask net.sonuscape.mouseless

Any version:

# List your remotes (to find <remote> for the next command)
flatpak remotes

# View commit (version) history
#  - <remote> is the name from `flatpak remotes` above
#  - it's `sonuscape` if you installed the .repo file
flatpak remote-info --log <remote> net.sonuscape.mouseless

# Install specific version
flatpak update --commit=<GOOD_COMMIT_HASH> net.sonuscape.mouseless

# Prevent future updates
flatpak mask net.sonuscape.mouseless

In-app update notifications will still be shown (unless disabled in app settings).

To resume normal updates (unpin):

# Remove mask
flatpak mask --remove net.sonuscape.mouseless
# Update app
flatpak update net.sonuscape.mouseless

Troubleshooting

Not working right? See the Linux troubleshooting section for solutions and workarounds.