[← README](../../README.md) · [Docs index](../README.md) · [Reference](README.md)

# Update checks

When it starts, and then once a day while it is open, each app asks GitHub whether a newer
release exists, and tells you when it does,
with the command that upgrades your copy. Nothing is downloaded or installed by itself.

![The desktop app (Cyber): at the right end of the command line row, next to Settings, the button Coxswain X.Y.Z is available, naming the newer version](../screenshots/reference-update.png)

## Contents

- [How to use it](#how-to-use-it)
- [What it does](#what-it-does)
- [What you see](#what-you-see)
- [The upgrade command](#the-upgrade-command)
- [Settings and config.toml](#settings-and-configtoml)
- [In the terminal app](#in-the-terminal-app)
- [Questions](#questions)

## How to use it

1. Nothing to do: it is on by default.
2. When a newer version exists, a button appears at the right of the command line (desktop app)
   or a line in the status line (terminal app).
3. Run the command it names in a shell, or click the button for the release page.
4. After the upgrade, the desktop app's **⚙ Settings** button shows a count: click it for
   *Settings → Overview → What's new*, with the new version's changes marked *new*. The terminal app says
   once `Coxswain X.Y.Z is installed: coxswain --whats-new says what it brought`
   ([Notices and what's new](../panels/notices.md)).

To turn it off: Settings (**Ctrl+,**) → *Privacy and updates* → untick *Check for a new
version*, or `check_updates = false` in `config.toml`.

## What it does

- It asks `https://api.github.com/repos/mwo-dk/coxswain/releases/latest` for the latest
  release's version number, with `User-Agent: coxswain/X.Y.Z`. Nothing else is sent.
- It waits at most 5 seconds. Offline, or with GitHub unreachable, it simply finds nothing and
  says nothing.
- It uses the system's certificate store, so it works behind a company proxy that inspects TLS.
- Each app asks once when it starts. After that it looks every hour and asks GitHub again only
  when a day has passed since the last answer, kept in `state.json` and shared by every window
  and both apps; so a window or terminal left open for weeks still hears of a release.
- Only a higher `major.minor.patch` counts as newer.

## What you see

| | Desktop app | Terminal app |
|---|---|---|
| Newer version, installed by a package manager | A button at the right of the command line: *Coxswain X.Y.Z is available: brew upgrade coxswain*. Its tooltip: *Upgrade with: brew upgrade coxswain. Click for the release notes.* | The status line: `Coxswain X.Y.Z is available: brew upgrade coxswain` |
| Newer version, from a channel that takes a release later (WinGet, Flathub, Termux, nixpkgs) | *Coxswain X.Y.Z is available: winget upgrade mwo-dk.Coxswain.Terminal (it can reach WinGet a few days later; or the release page)*; tooltip and click as above | The status line, the same text |
| Newer version, installed from a download | *Coxswain X.Y.Z is available*, tooltip *Open the releases page* | `Coxswain X.Y.Z is available: https://github.com/mwo-dk/coxswain/releases/latest` |
| Click | Opens the release page in your browser | – |
| How long | Until you update; it has no `×` | Until the status line shows something else |
| After updating | A count on **⚙ Settings**; a click opens *Settings → Overview → What's new*, where the new version's changes are marked *new* | Once, in the status line: `Coxswain X.Y.Z is installed: coxswain --whats-new says what it brought` |

While the update button shows, the desktop app holds back a problem with search in the status
line ([Notices and what's new](../panels/notices.md)).

## The upgrade command

It is worked out from where the program is installed:

| Installed with | Command shown |
|---|---|
| Anything else on FreeBSD (the install script, the archives) | `fetch -qo - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-freebsd.sh \| sh`, which updates both apps where they are ([FreeBSD](../systems/freebsd.md#updating)) |
| Anything else on NetBSD or OpenBSD | `ftp -o - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh \| sh` ([NetBSD](../systems/netbsd.md#updating-and-uninstalling), [OpenBSD](../systems/openbsd.md#updating-and-uninstalling)) |
| Anything else on illumos | `curl -fsSL https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh \| sh` ([illumos](../systems/illumos.md#updating-and-uninstalling)) |
| Flatpak, the desktop app (`io.github.mwo_dk.Coxswain`) | `flatpak update io.github.mwo_dk.Coxswain`. It is not on Flathub yet: a Flatpak you built updates by building it again ([Flatpak](../systems/flatpak.md#updating)) |
| Termux's package (`/data/data/com.termux/files/usr/bin`) | `pkg upgrade coxswain`, once the package is in Termux's repository ([Termux](../systems/termux.md)) |
| Cargo (`~/.cargo/bin`, Termux too) | `cargo install --locked coxswain` |
| Homebrew formula (the terminal app) | `brew upgrade coxswain` |
| Homebrew cask (the desktop app) | `brew upgrade --cask coxswain-gui` |
| WinGet, the terminal app (`mwo-dk.Coxswain.Terminal`) | `winget upgrade mwo-dk.Coxswain.Terminal` |
| Nix (the program runs from `/nix/store/`) | `nix profile upgrade coxswain`; for the flake as an input of a NixOS or Home Manager config, update the input and rebuild ([Nix](../systems/nix.md#updating)) |
| A download, `.deb`, `.rpm`, AppImage, the Windows installer, a source build | None: it points to the [releases page](https://github.com/mwo-dk/coxswain/releases/latest) |

The notice asks GitHub, and some channels get a release days after it: WinGet (a new version
is filed at most once a week and waits for Microsoft's moderators), Flathub, Termux's repository
and nixpkgs. For those the notice adds *it can reach … a few days later; or the release page*.
Our Homebrew tap, crates.io (cargo), the Nix flake and the install scripts have it at once.

The Windows desktop installer lands where a download would, so it gets the releases page too.
Its WinGet package, `mwo-dk.Coxswain`, is waiting for WinGet's review; until it is listed, only
`mwo-dk.Coxswain.Terminal` is on WinGet. WinGet gets the newest release once a week, after
Microsoft's review, so `winget upgrade` can be up to a week behind the releases page. There is no
Arch (AUR) package yet.

How to install each is in the [README](../../README.md#install) and
[install/INSTALL.md](../../install/INSTALL.md); update the same way.

## Settings and config.toml

| Settings | Key | Type | Default |
|---|---|---|---|
| *Privacy and updates* → *Check for a new version* | `check_updates` | bool | `true` |

The last check is kept in `state.json` as `update_checked` (a time) and `latest_version`; the
version whose notice you saw is `seen_version`. None of these are for editing.

## In the terminal app

It checks when it starts, then once a day while it is open, on a thread of its own, so a slow
network never holds up the panels. The answer shows in the status line, once for each new version; there is no button and nothing to click. The same
`check_updates` key turns it off.

## Questions

#### Does Coxswain update itself?

No. It only tells you. Updating is left to the way you installed it, so your package manager
stays in charge.

#### Why does it show a URL instead of a command?

It could not tell a package manager from where the program runs: a download, a `.deb`, an
AppImage, or the Windows desktop installer, which lands in the same folder whether you ran it
yourself or, once its WinGet package is listed, WinGet did. Update it the way you installed it:
download the new release, or run your package manager's upgrade.

#### The command finds no new version.

Your channel does not have it yet: WinGet, Flathub, Termux and nixpkgs take a release a few days
after GitHub, and the notice says so (*it can reach WinGet a few days later*). Run the command
again in a few days, or take the new version from the
[release page](https://github.com/mwo-dk/coxswain/releases/latest) now; the desktop app's
button opens it. With Nix, a profile installed from the flake (`github:mwo-dk/coxswain`) has it
at once; one from nixpkgs waits for nixpkgs.

#### I updated, but it still says a newer version is available.

The running app is the old one: quit every Coxswain window and the terminal app, then start
again. `coxswain --version` shows the version you now have.

#### It never tells me about updates.

Check that `check_updates` is not `false`, and that the machine can reach `api.github.com`. The
app asks when it starts, then once a day while it is open, so a release out an hour ago shows
when you next start it, or at the latest a day later.

#### What does the check send?

Only the request for the latest version, with `User-Agent: coxswain/X.Y.Z`. See
[Privacy](privacy.md#what-can-leave-it).

#### How do I get rid of the update button?

Update. Or turn the check off in Settings → *Privacy and updates*; the button then goes at the next hourly look,
or when the app starts again.

---
[← Previous: Privacy](privacy.md) · [Next: Where things are kept →](where-things-are-kept.md)