Documentation

NomadWiFi is one Go core with two faces: a WPF desktop app and a command line tool. Both make the same decisions, because both run the same engine.

Install

The installer is the easiest route, and the one the in-app update prompt uses. It is per-user: it installs to %LOCALAPPDATA%\Programs\NomadWiFi and never asks for administrator rights, on install or on update.

Download the installer All releases

Or with a package manager:

# the desktop app and the CLI
winget install mory-dev.NomadWiFi

# the CLI on its own
scoop install nomadwifi

# the CLI from source -- note this build is not code-signed
go install github.com/mory-dev/nomadwifi/cmd/nomadwifi@latest

What the installer does

Installs per-user, with no UAC prompt at any point.
Adds a Start Menu entry and an Add/Remove Programs entry.
Optionally starts NomadWiFi when you sign in, and optionally puts nomadwifi on your PATH.
Checks for .NET Framework 4.8 and links the download if it is missing.
Closes a running copy in order to update it, then puts it back as it found it.
On uninstall, removes everything it added and asks before deleting the networks NomadWiFi learned.

Installed layout

%LOCALAPPDATA%\Programs\NomadWiFi\
  nomadwifi.exe        # the desktop app
  core\nomadwifi.exe   # the engine it drives, and the CLI

Both are called nomadwifi.exe on purpose, which is why they live in separate folders: the app resolves its engine from core\ only, and refuses any candidate that resolves to itself. It is the same binary either way, so putting core\ on your PATH is all the CLI needs.

Portable archives

Zips are still published for anyone who would rather not install anything: NomadWiFi-windows.zip (app plus engine) and nomadwifi-cli-windows.zip (the CLI alone). Unzip either anywhere — the app still needs core\nomadwifi.exe beside it.

Updating

NomadWiFi checks for a new release at most once a day and offers it in a banner with an Install now button. The download is verified against the published SHA-256 digest before it is run, and a mismatch is refused rather than executed. Dismissing the banner silences that specific version, not all future ones.

From a terminal:

$ nomadwifi update             # report whether a newer release exists
$ nomadwifi update --install   # download, verify and run it
$ winget upgrade mory-dev.NomadWiFi

No administrator rights needed. Wi-Fi profiles are written per-user, so scanning, connecting, warming and roaming all work from a normal account. The only action that asks for elevation is pausing a VPN client that has no command line of its own.

Requirements

Windows 10 or Windows 11, 64-bit.
A Wi-Fi adapter with the Windows WLAN service running (the normal case).
.NET Framework 4.8 for the desktop app — shipped with Windows 10 1903 and later. The CLI needs nothing.

How access points are scored

Every radio in range gets a quality score, and the score is explained rather than asserted — hover a row in the app, or read reasons in the JSON output.

Signal	Effect	Why
Band	6 GHz > 5 GHz > 2.4 GHz	Wider channels, far less interference.
802.11 standard	`be` > `ax` > `ac` > `n` > `g`	Newer radios sustain higher throughput at the same signal.
RSSI	Scaled −100 dBm → 0%, −50 dBm → 100%	Derived from measured dBm, not from the driver's link quality, which reports the connected access point at ~99% regardless.
Airtime congestion	Penalty as BSS Load rises	A strong access point with forty clients on it is slower than a middling one that is idle.
Encryption	Small bonus for modern ciphers	WPA3/CCMP over TKIP or none.
Readiness	Saved > prepared > open > needs a password	A network that cannot be joined right now is not a useful roam target.

When it decides to move

Roaming is deliberately reluctant. A switch costs a second of connectivity, so it happens for a reason and not on a single bad sample.

A drop. The wireless service's own disconnect notification arrives in about a hundred milliseconds; the candidate ladder is already built, so recovery starts immediately.
Sustained degradation. Several consecutive samples below the health thresholds — receive rate, signal, latency, jitter, loss — not one.
A clearly better neighbour. Another access point outscores the current one by a margin, and the cooldown since the last switch has passed.

Every switch verifies the result: association, then a gateway probe, then internet reachability. If the new access point does not carry traffic within the deadline, NomadWiFi reconnects the previous one and puts the failed access point in a penalty box so it is not tried again straight away.

A captive portal is not treated as degradation. You are behind a sign-in page, not on a bad access point, and roaming away would just lose your place in the queue.

Warming

Venues publish the same key across several names — Hotel, Hotel_5G, Hotel Lobby, Hotel Floor2. Warming recognises the family, copies the key you already have onto the siblings, and writes the Windows profiles ahead of time, so failover is a connect rather than a connect-plus-prompt.

Profiles are written with connectionMode=manual, so Windows will not auto-connect behind the roamer's back.
They are per-user, so no elevation is required.
Every profile NomadWiFi creates is recorded in %USERPROFILE%\.nomadwifi\state.json and marked verified only after it actually associates.
A guess that fails twice is deleted and the network is penalised, so bad guesses do not accumulate in your Windows profile list.

Where it keeps things

Path	Contents
`%USERPROFILE%\.nomadwifi\state.json`	Profiles NomadWiFi created, verification status, failure counts, penalty box, last venue.
`%USERPROFILE%\.nomadwifi\scan-cache.json`	The rolling view of access points, so a one-shot command sees the whole venue rather than one sweep.

Delete either file to start fresh; both are rebuilt automatically.