Self-Update
The bare yerd update command (no subcommand) checks for, and optionally installs, a newer version of Yerd itself. yerd update php is a different command that updates an installed PHP version - see PHP.
| Command | Description |
|---|---|
yerd update | Check for a newer Yerd on your configured channel and report it. Installs nothing. |
yerd update --yes | Check, then download, verify, and install the update, and restart the daemon. |
yerd update --edge / --stable | Check (or, with --yes, apply) against the edge or stable channel for this run. |
yerd update --edge --yes / --stable --yes | Also persist the given channel as your saved default. |
yerd update --yes --force | Allow a downgrade (e.g. moving from a newer pre-release back to stable). |
yerd update # check only, using your saved channel
yerd update --edge # check against edge, without changing your saved channel
yerd update --yes # check and install on your saved channel
yerd update --edge --yes # switch to (and install from) the edge channelChannels
Yerd ships two release channels, persisted as update_channel in yerd.toml ("stable" by default):
stable- the highest released version that isn't a pre-release.edge- the highest released version including pre-releases / release candidates.
--edge/--stable override the saved channel for this invocation only. Add --yes and the override also becomes the new saved default - a check-only run (no --yes) never touches your saved preference, but prints a reminder that it's showing a channel other than the one it will use next time.
The stable channel never installs a downgrade: if you're running a pre-release that is already newer than the latest stable, yerd update --yes (without --edge) reports you're ahead of stable and stays put. --force (which requires --yes) is the escape hatch for that case, though an automated downgrade isn't implemented yet - it currently just says so.
What --yes does
- Persists the channel override, if
--edge/--stablewas given. - Asks the daemon to check the channel (
yerd_ipc::Request::CheckUpdate). If nothing is available, it reports and exits0- no download happens. - Otherwise asks the daemon to download and verify the target release's artifact (
Request::StageUpdate): the daemon fetches the platform-specific asset (macOS.app.tar.gz, Linux.deb/.pkg.tar.zst/.rpm, or the.headless.tar.gzfor a headless install), checks its SHA-256 against the release'sSHA256SUMSmanifest, and verifies a detached minisign signature (the<artifact>.minisigasset, with a legacy<artifact>.sigaccepted as a fallback) against an embedded public key. - Re-verifies the signature a second time locally (closing the window between the daemon's verify and the install), then installs the artifact and restarts the daemon so it comes back up on the new version.
--yes is not compatible with --json - the apply path is interactive progress output, not a single structured response.
Where Yerd must live
On macOS, the desktop app only self-updates when it is installed at /Applications/Yerd.app and that location is writable by you. Installs elsewhere (e.g. a dev build) are rejected with a clear error rather than silently failing. A headless install has no app bundle and updates its binaries in place, wherever you installed them.
Headless installs
A headless install is recognised by the yerd-install-receipt file next to its binaries. The daemon reads it and stages the headless tarball for your platform (Yerd_<OS>_<Arch>_v<ver>.headless.tar.gz) instead of the desktop app's package, with the same SHA-256 and minisign checks. The CLI then:
- Takes the install directory's update lock (a second update running at the same time stops without changing anything), copies the tarball into a staging directory inside your install directory, checks the copy's signature again, and unpacks that copy. It then checks the result holds the required files (
yerd,yerdd,yerd-helper,yerd-forwardon macOS, and a receipt that saysheadless). Extra files a newer release adds are accepted and installed too, as long as each is a plain regular file directly insideyerd/namedyerd-followed by at least one more character, using only ASCII letters, digits,.,_and-, and not containing.yerd-old-(reserved for backups). Anything else (symlinks, directories, hidden or nested names, other characters) rejects the whole archive. - Replaces each file with an atomic rename, keeping a backup until every file is in place; if any step fails, the files already replaced are restored and any newly added ones removed. If a restore itself fails, the error says so and names the backup files left on disk.
- Restarts the daemon: on Linux through the
yerdsystemd user service (or a stop/start fallback), on macOS with an in-place restart, the same asyerd restart daemon, since the system LaunchDaemon can't be restarted without root. If the daemon isn't running, the new version starts with it next time. If the restart fails, the command exits1and says the new files are installed (nothing is rolled back); runyerd restart daemonto load them.
No sudo is needed: the install directory is yours. On Linux, replacing yerdd drops its port capability. If you use ports 80/443, run sudo ~/.yerd/bin/yerd elevate ports and then ~/.yerd/bin/yerd restart daemon afterwards: the capability only applies when yerdd next starts. If you installed somewhere else with YERD_INSTALL_DIR, use that directory's yerd in both commands. The updater prints both commands with your install's path when yerdd had the capability, or when getcap can't tell.
The CLI also refuses, before changing anything, when the daemon belongs to a different headless install than the yerd you ran: either the running daemon reports a different directory with the staged update, or the registered daemon service (the systemd unit's ExecStart=, or the macOS LaunchDaemon's program) runs a yerdd from a different directory. Updating this install's files would leave that daemon on its old version.
The CLI refuses to apply an update that belongs to the other kind of install: a desktop app yerd talking to a headless daemon is told to run the headless install's yerd update --yes, and a headless yerd talking to the desktop app's daemon is told to use the app's updater. On Linux, the package paths (dpkg/pacman/rpm) also refuse to run unless yerd itself lives where a package puts it: /usr/bin/yerd, or the Debian package's /usr/lib/<dir>/yerd fallback. A tarball install never pulls in the desktop package. A receipt Yerd can't read or doesn't recognise is an error, not a fallback: reinstall with the install script.
Platform support
| Platform | Install mechanism |
|---|---|
| macOS (Apple Silicon) | Extracts the .app.tar.gz, swaps it into /Applications, restarts the daemon via launchctl kickstart -k. |
Linux (.deb build) | Reinstalls via dpkg -i, elevated with pkexec if needed; restarts the daemon via systemctl --user restart (or a stop/start fallback with no systemd user instance). |
Linux (Arch .pkg.tar.zst build) | Reinstalls via pacman -U, same elevation and restart path as the .deb build. |
Linux (Fedora .rpm build) | Reinstalls via rpm -U --oldpackage, same elevation and restart path as the .deb build. |
| Headless install (Linux x86-64/arm64, macOS Apple Silicon) | Swaps the binaries from the .headless.tar.gz in place, no elevation; restarts the daemon as described above. |
| Intel macOS, other platforms | No self-update artifact is published; yerd update reports nothing available. |
See also
- PHP - the unrelated
yerd update php [VERSION]command. - Configuration Reference - the persisted
update_channelkey. - yerd-update - the channel-resolution and artifact-selection/verification logic.
- yerd-service-ctl - the daemon restart step of the applier.
- Daemon control - the separate
yerd restart daemoncommand.