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

Updating

Wayscriber never installs updates itself. It can tell you that a newer release exists — in the About window, in the tray menu, and once per release as a desktop notification — and then sends you here. Installing stays with whatever put Wayscriber on your system, so your package manager keeps its usual authority over what is on disk.

Check what you are running:

wayscriber --version

Ask right now whether anything newer exists, without waiting for the background check:

wayscriber --check-update

Then follow the section for the way you installed Wayscriber. If you are not sure, the About window’s “Copy diagnostics” button reports the install source when the package was built with one.

The tarball and source sections below take a version number. Set it once from what --check-update reported, and the commands in those sections will use it:

read -r -p "Version reported by wayscriber --check-update: " VERSION

Ubuntu / Debian

Wayscriber v0.9.23 and newer supports Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04+, and Debian 13+. The v0.9.22 package accidentally required libgtk4-layer-shell0, which is unavailable on Ubuntu 24.04 and its derivatives; upgrading to v0.9.23 or newer removes that external dependency.

From the apt repo (the recommended install):

sudo apt update
sudo apt install --only-upgrade wayscriber wayscriber-configurator

If you installed a one-off .deb, download the new one and install it over the old package:

wget -O wayscriber-amd64.deb https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-amd64.deb
sudo apt install ./wayscriber-amd64.deb

One-off .deb files never update themselves. Switching to the repo (see Installation) is the easier path if you expect to keep up with releases.

Fedora / RHEL

From the dnf repo:

sudo dnf upgrade --refresh wayscriber wayscriber-configurator

If you installed a one-off .rpm:

wget -O wayscriber-x86_64.rpm https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-x86_64.rpm
sudo rpm -Uvh wayscriber-x86_64.rpm

Arch Linux (AUR)

Same helper you installed with, same package name:

yay -Syu wayscriber              # source build
yay -Syu wayscriber-bin          # prebuilt binary
yay -Syu wayscriber-configurator # optional GUI

paru works the same way. AUR mirrors can lag the release by a few minutes.

NixOS / Nix

From nixpkgs, update the channel or flake input your system already tracks, then rebuild:

sudo nixos-rebuild switch                      # channel-based configuration
sudo nixos-rebuild switch --flake .#myhost     # flake-based configuration

Stable channels pin the version that existed when the release branch was cut, and Wayscriber bumps are not backported. If you need the newest release on a stable channel, use the project flake.

From the project flake, change RELEASE_TAG in your flake.nix to the new tag, then update only that input:

nix flake update wayscriber
sudo nixos-rebuild switch --flake .#myhost

A nix profile install (Nix on another distribution) upgrades with:

nix profile upgrade wayscriber

Tarball

Download the new release tarball and the checksum file published beside it, verify the archive, then replace the files you installed from the previous one. VERSION is the version you set above:

BASE="https://github.com/devmobasa/wayscriber/releases/download/v${VERSION}"
wget "${BASE}/wayscriber-v${VERSION}-linux-x86_64.tar.gz" "${BASE}/checksums.txt"
sha256sum --ignore-missing --check checksums.txt

sha256sum must print wayscriber-v${VERSION}-linux-x86_64.tar.gz: OK. If it prints anything else, stop and do not install the archive. Then extract and install:

tar -xzf "wayscriber-v${VERSION}-linux-x86_64.tar.gz"
sudo install -Dm755 "wayscriber-v${VERSION}-linux-x86_64/usr/bin/wayscriber" /usr/local/bin/wayscriber

The archive also carries the desktop entry, icons, and the wayscriber.service systemd user unit under usr/. If you installed those the first time, copy the same paths again:

sudo cp -r "wayscriber-v${VERSION}-linux-x86_64/usr/share/." /usr/local/share/
sudo cp "wayscriber-v${VERSION}-linux-x86_64/usr/lib/systemd/user/wayscriber.service" /usr/local/lib/systemd/user/

Restart the daemon after replacing the binary:

systemctl --user restart wayscriber.service

Build from source

Pull the new tag and rebuild with the same feature flags you used before:

cd wayscriber
git fetch --tags
git checkout "v${VERSION}"
cargo build --release

INSTALLED="$(type -P wayscriber)"
if [[ -w "${INSTALLED}" ]]; then
    install -Dm755 target/release/wayscriber "${INSTALLED}"
else
    sudo install -Dm755 target/release/wayscriber "${INSTALLED}"
fi

That final step replaces the executable already on your PATH; rebuilding by itself does not update an earlier installed copy. Restart wayscriber.service afterward if you run the daemon as a systemd user service.

Build dependencies occasionally change between releases; if the build fails, re-read the dependency list in Installation before filing anything.

The update check

The check is a single HTTPS request for one small static file, https://wayscriber.com/latest.json, containing the newest published version and the links to these instructions. Wayscriber compares that version to its own and stops there. It does not download packages, execute anything, or restart your session.

Details worth knowing:

  • What is sent: no Wayscriber or user identifier, no Wayscriber version, no query parameters, and no cookies. The HTTP client’s version is suppressed too. The request goes out through whichever of curl or wget is installed, so it uses your system’s CA store and proxy settings — but it is invoked with client config files disabled, and Wget cannot consult ~/.netrc, so those files cannot attach headers, cookies, or credentials. One check is one request: if the client is installed and the request fails, that is the result — nothing is retried with a second client.
  • How much is read: the response is cut off past 64 KiB, so a wrong or hostile answer cannot be streamed into memory.
  • How often: once a day by default, and never more than once per hour. The daemon performs the check; the About window only reads the cached result unless you press “Check now”.
  • Notifications: at most one desktop notification per release, suppressed while the annotation overlay is active. The tray keeps the notice until you act on it.
  • Where the result is stored: $XDG_CACHE_HOME/wayscriber/update-check.json (~/.cache/wayscriber/update-check.json by default). Deleting it just makes the next check look like the first one. If the file cannot be written at all, the interval is still honored for the life of the process, so an unwritable cache does not turn the daily check into a repeated one.
  • What “checked N ago” means: the last check that actually got an answer. A failed attempt delays the next one, but never presents an older result as freshly verified: the About window says “Last check failed” alongside the age of the last real answer. Failed explicit checks count toward the interval too — the request was already made.

Turning it off

In config.toml:

[updates]
check = false          # never contact the network
notify = false         # keep the About/tray notice, drop the desktop notification
interval_hours = 24    # minimum 1, maximum 720

Or, without editing config — useful for a session wrapper or a locked-down deployment:

export WAYSCRIBER_DISABLE_UPDATE_CHECK=1

The environment variable wins over the config file. wayscriber --check-update still works when it is set: asking for a check explicitly is its own consent.

Setting it to 0, false, no, off, disable, disabled, or an empty value leaves the check on, matching the boolean words Wayscriber’s other variables accept. Any other value opts out — for a switch whose only job is to stop network access, a value it does not recognize is honored rather than ignored.

If the config file exists but cannot be parsed, the background check does not run at all: Wayscriber cannot confirm your [updates] setting, so it assumes the stricter one until the file is valid again.

Distribution packagers who must guarantee that the binary never contacts wayscriber.com can remove the check at build time:

WAYSCRIBER_NO_UPDATE_CHECK=1 cargo build --release

Such a build reports “Update checks are off in this build” in the About window, and wayscriber --check-update says the same instead of making a request. Nothing in config.toml or the environment can turn it back on. This is a separate variable from the runtime opt-out above, so exporting WAYSCRIBER_DISABLE_UPDATE_CHECK in your shell does not quietly change what a source build is capable of.

Packagers should also set WAYSCRIBER_INSTALL_SOURCE (apt, rpm, aur, nix, tarball, source) when they do ship the check, so the update notice opens the section of this page that applies to their users.