One page of the instructor manual.

2. Installing on your computer

You want the app on your laptop, started from an icon. It runs on Mac, Windows, and Linux. It is installed as a Python program with uv, a small tool that fetches Python for you if you do not have it, so there is nothing to download by hand and no warning from your operating system about an unknown developer.

1. Install uv (once)

Open a terminal (Mac: Terminal, in Applications → Utilities; Windows: PowerShell, from the Start menu; Linux: your terminal) and paste one line.

Mac and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close the terminal and open a new one, so that it knows about uv.

2. Install Mosscap (once per version)

You were sent a file named like mosscap-0.1.0-py3-none-any.whl. Save it somewhere (Downloads is fine), then in the terminal:

uv tool install ~/Downloads/mosscap-0.1.0-py3-none-any.whl

On Windows the path looks like C:\Users\you\Downloads\mosscap-0.1.0-py3-none-any.whl. Drag the file into the terminal window to have its path typed for you.

3. Start it

mosscap

Your browser opens on the app. The terminal window stays open while the app runs; closing it stops the app. The first time, log in (chapter 3), open Settings, and press Make a desktop shortcut: from then on you start the app from the icon on your Desktop and never need the terminal. The line beside the button names the files it made.

• Windows gets two shortcuts: one on the Desktop and one in the Start menu, so pressing the Windows key and typing moss finds Mosscap, and a right-click there pins it to the taskbar. If OneDrive backs up your Desktop, "the Desktop" is the OneDrive one and the Desktop shortcut lands there; the Start menu one is never synced. Double-clicking opens a console window beside the browser; it stays open while the app runs.
• Mac: Mosscap.command on the Desktop; double-clicking opens a Terminal window that stays open while the app runs.
• Linux (GNOME): right-click the new icon once and choose Allow Launching. The app is also in the applications menu.

Updating

When you are sent a new file, install it the same way with --force, which replaces the old version:

uv tool install --force ~/Downloads/mosscap-0.2.0-py3-none-any.whl

Your settings, your classes, and your shortcut are untouched by an update.

Uninstalling

uv tool uninstall mosscap

Your class folders are not touched: they are ordinary folders that you chose. The app's own two files (settings and the list of classes) stay in your application-data folder and can be deleted by hand; chapter 3 says where they are.

If your computer warns you about an unknown developer

It will not, with the install above: nothing in it is a downloaded program, so neither macOS Gatekeeper nor Windows SmartScreen has anything to say. This section is for a future version that may ship as a single downloadable program. If that version shows "unidentified developer" (Mac) or "Windows protected your PC", it is because the program is not signed with a paid certificate, not because it is unsafe. On a Mac, right-click the program and choose Open, then Open again. On Windows, press More info, then Run anyway. You only do this once.

Where the app keeps its own files

Two small text files, your settings and the list of your classes, in the folder your operating system provides for such things: ~/Library/Application Support/Mosscap on a Mac, %APPDATA%\Mosscap on Windows, ~/.config/mosscap on Linux. Everything else, rosters, sessions, and results, is in the class folders you choose (chapter 4). Your own API key, if you use one, is in your computer's keyring, not in a file.