# Updating

How the desktop app and the espx command update themselves, and how to check a release by hand.

Every espx release is signed. The app, `espx update` and the install script each check a download's SHA-256 and its minisign signature before they replace anything, and they refuse a signature made for another file or another release.

## The desktop app

The app checks espx.dev once a day, starting ten seconds after launch. When a newer release is out it downloads it, checks it, and installs it over the running app. A toast then says the new version is ready, and Restart to update in the toast or the status bar relaunches the app on it.

- Check for Updates… in the espx menu checks now and says whether the app is up to date. The command palette and Settings > About > Check now do the same.
- Settings > About > Check for updates automatically turns the daily check off. Check for Updates… still works.
- An automatic check stays quiet unless it found an update, so a Mac that is offline does not get a toast every day. Settings > About shows the last check's result.

The app carries its own copy of the `espx` command, from the same build, and updates it with the app. Install Command Line Tool in the espx menu (also in the palette and in Settings > About > Command line tool) links `~/.espx/bin/espx` to that copy, so your terminal and your agents run the same espx as the app.

## The espx command

```sh
espx update           # download, check and install the latest release
espx update --check   # only report whether a newer release exists
```

`espx update` replaces an `espx` that the [install script](https://www.espx.dev/docs/installation) put in `~/.espx/bin`. It refuses in two cases, and `--check` still reports in both:

- The copy inside the desktop app, or the `~/.espx/bin/espx` link to it. The app updates that copy.
- A build that cargo installed into `~/.cargo/bin`. Pull the repository and run `cargo install --path crates/espx-cli` again.

`--force` reinstalls the latest release even when it is the one you have.

Once a day, after a command finishes, espx checks for a newer release in a detached background process and prints a notice on a later run. It only writes a cache file under `~/.espx`, and `espx doctor` reads the same cache to flag an outdated tool. Set `ESPX_NO_UPDATE_CHECK` to any value to turn the check off.

## The tools

espflash, cargo-espflash and esp-generate are pinned separately from espx. Run `espx setup` again to move to the versions the mirror pins now; it replaces only the tools whose version differs. The app's Toolchain page does the same with Install.

## A specific release

The install script installs the latest release unless `ESPX_VERSION` names another, which is also how to go back to an older one:

```sh
curl -fsSL https://www.espx.dev/install.sh | ESPX_VERSION=0.1.0 sh
```

Each release has its own page at `/releases/<version>` with its notes, its files and these commands. The [changelog](https://www.espx.dev/changelog) lists every release, and [Verifying downloads](https://www.espx.dev/docs/installation#verifying-downloads) shows how to check a file by hand.