Upgrade Sher safely

Sher never updates in the background. Ordinary CLI and TUI use make no update request. You choose when to check and when to install.

Check before changing anything

sher update --check

The check reports the installed version and channel, whether the executable is owned by Sher's standalone installer, the selected channel, the newest eligible immutable release for this machine, release notes, compatibility class, and the required action. It does not stop the daemon, download the archive, or change local files. A network error affects only this command.

Stable is the default for stable installs. Enter the dev channel explicitly:

sher update --check --channel dev
sher update --channel dev

Returning to stable records that preference and waits for a stable version newer than the installed prerelease; Sher does not silently downgrade.

Managed upgrades

An in-place upgrade is allowed only when the cargo-dist receipt proves that the standalone installer owns the exact sher executable being invoked:

sher update

Before changing the executable, Sher verifies the immutable version, metadata, target archive, SHA-256 checksum, free space, permissions, receipt, and daemon ownership. It stages the new binary beside the destination, validates its embedded identity, and replaces the binary and receipt as one transaction.

Daemon state is preserved:

• no registration remains unregistered;
• a registered, stopped daemon remains stopped;
• a running managed daemon is stopped, upgraded, restarted through the same manager, and health-checked;
• a detached/manual daemon or an ambiguous registration causes a refusal before mutation.

If a step fails after the daemon stops or the binary changes, Sher restores the old binary, receipt, and prior daemon state. A failed rollback leaves backup paths and exact recovery commands in the error output. Keep that output.

Source builds and other unmanaged installations

Sher does not guess which package manager owns an executable. A source build, cargo install, missing or mismatched receipt, read-only destination, or multiple sher executables on PATH will not be overwritten.

To move to the managed standalone install, first inspect every copy:

which -a sher
sher --version --json
sher daemon status

Then use the public installer:

curl -fsSL https://sher.ing/install | sh && export PATH="${CARGO_HOME:-$HOME/.cargo}/bin:$PATH"

The installer leaves old binaries intact, writes the managed binary under $CARGO_HOME/bin or ~/.cargo/bin, writes its ownership receipt, and rebinds an exact Sher-managed launchd/systemd registration to the new path. It refuses an edited, ambiguous, or detached registration. The command prepends the managed binary directory to the current terminal's PATH; future shells use the profile change written by the installer. Then run which -a sher again. Rename or remove an older executable only after confirming it is no longer used.

Local data compatibility

Every release carries a state_impact declaration. The initial updater accepts only:

• none: no incompatible catalog or ledger change; binary rollback is safe.

Unknown metadata, a newer schema, an unsatisfied minimum updater, or any other state impact is refused before daemon shutdown, payload download, binary replacement, or local-state access. The error prints installed and target versions, the rejected value, confirms that nothing changed, and points here.

The local catalog is derived data stored in a filename-versioned database and can be rebuilt from original harness sessions. The publication ledger contains durable facts and is additive-only; Sher does not delete or rewrite it during the current release line. Do not delete either store merely to force an upgrade.

A future incompatible change requires its own reviewed transition with backup, validation, confirmation, and recovery steps. Normally, a prior no-state-change bridge release will first teach existing updaters that transition. If a release ever requires reindexing or could lose access to sessions whose original harness files were removed, its release notes and this page will name the affected paths, backup command, irreversible step, and recovery limits before the updater permits it. Until that implementation exists, Sher refuses the release.

Recovery

Start by recording the active binary and daemon state:

which -a sher
sher --version --json
sher daemon status

If an update reports successful rollback, verify the old version and daemon, then retry only after fixing the reported network, permission, disk, receipt, or service-manager problem.

If rollback itself failed, use the exact backup paths and cp -- ... commands printed by Sher. Stop the daemon before copying a binary manually, verify the restored binary with --version --json, and restart only if it was running before:

sher daemon stop
# Run the exact restore commands printed by the failed update.
sher --version --json
sher daemon start
sher daemon status

To reinstall a known immutable stable version without asking for latest:

curl -fsSL 'https://sher.ing/install?version=0.2.0' | sh

Pinned installation verifies the same cargo-dist archive and receipt. It does not make an incompatible local-state transition safe; if the updater refused a compatibility class, keep the current binary and follow the release-specific bridge instructions instead.