Repository navigation
Updating
spn update
spn update check --json
spn update check --prerelease
spn update install --prerelease --dry-run
spn host stop
spn update install --prerelease
spn update status --json
spn host start --phone defaultA bare update checks only in scripts; in a terminal it offers a cursor menu.
Checks use GitHub public releases without an account/token. Stable releases are
the default. --prerelease includes published prereleases and selects the highest
semantic version. Drafts, tags without releases and Actions artifacts are excluded.
A prerelease lookup is bounded to 1,000 releases; rate limits fail with a concise
error. Equal/older versions never downgrade an installation. Missing release assets
or checksums prevent installation. No published release is a normal check result.
Installation is explicit. The updater chooses the current process architecture
(x64/ARM64), downloads the matching ZIP/tar.gz and SHA256SUMS, verifies SHA-256
before extraction and additionally checks GitHub asset digests when supplied.
It verifies a version/runtime/file-hash manifest and rejects archive traversal,
links, duplicate files, special entries and excessive sizes. Checksums establish
integrity against the published release metadata; they are not independent code
signatures or protection against a compromised publisher account.
Self-update requires a self-contained distribution containing sidepulse-install.json.
Source builds, framework-dependent binaries, older previews without that manifest,
modified application files and symlinked installations require manual installation.
Beta 2 adds single-file manifest format 2, with exactly one owned executable.
It also reads legacy format-1 directory packages. Beta 1's updater cannot read the
new format: download the new executable and use spn install to adopt/upgrade the
owned installation, or install into a separate directory. Stop the host first.
Alpha still requires the manual rename transition described in beta 1's notes.
The install directory and its parent must be writable; the updater
never elevates privileges. Package-manager installations should use that manager.
Run the command from outside the installation directory. Stop the agent host and other processes using the installation first. The updater does not kill processes or change startup registration. Downloading/staging leaves the current installation intact. A helper copied outside the installation waits for the calling process to exit, replaces the whole application directory, and runs the new executable's version check. A failed replacement/probe attempts to restore the original directory. A per-installation lock prevents concurrent swaps.
update install returning success means scheduled, not already installed.
Run update status after it exits; wait for installed before restarting the host
with its previous target/profile options. Failure/recovery states return exit 1.
The JSON receipt includes target, backup, workspace and state. If interrupted,
status may remain scheduled/applying. Inspect those paths before manual recovery;
never delete the only intact backup. Updating is not a crash-atomic transaction
across the two directory renames. A power failure between them may require restoring
the backup directory manually before the CLI can run again.
Unknown user-added files are copied into the new directory unless they collide with a new application-owned file. Existing directory access permissions and access permissions on user-added files are preserved. Avoid editing the installation during updating. Phone links, profiles and hooks normally live outside it and are not changed. The complete old installation and temporary download/helper workspace are retained for recovery. Once installation is confirmed and no helper is running, these paths may be removed manually to reclaim space. Failed updates preserve evidence.
The Release workflow runs on vVERSION tags or manual dispatch on such a tag.
The tag must match the project version. It reuses all three native CI jobs and
self-contained smoke checks, collects all six archives, writes SHA256SUMS, uploads
a draft release and only then publishes it. Hyphenated versions are prereleases.
No release or tag is created simply by adding this workflow to a branch. Existing
release tags are not overwritten. Review the release notes/assets after publishing.
update status --json always exposes the same lower-camel-case fields: state,
version, target, backup, workspace, error, and receipt. Missing values
are null; no receipt gives state none. Scripts should inspect state rather
than infer completion from an install command returning successfully.
SidePulse.NET is an unofficial companion for SidePulse. Documentation describes the planned product unless explicitly marked implemented.