selfupdate

README

selfupdate

Ship a CLI that updates itself — without shipping a supply-chain hole.

Three calls in main(): your tool checks GitHub Releases, verifies what it downloads, and atomically swaps its own binary.

No dependencies. No re-exec. No surprises on Windows.

Quick start · Release setup · Layouts · Signing · Hardening · Testing

---

[!NOTE] Young library. The API is settled enough to build on but may move before v1. Issues welcome. 🙌

🚀 Quick start

go get github.com/p-arndt/selfupdate

up, err := selfupdate.New(selfupdate.Config{Owner: "you", Repo: "mytool"})

selfupdate.CleanupLeftovers()                      // once at startup
up.NotifyIfAvailable(os.Stderr, version)           // the passive hint
up.Run(ctx, os.Stdout, version, false)             // your `update` subcommand

That's the whole integration. Owner and Repo are the only required fields.

What users see:

$ mytool status
... your tool's output ...

A newer mytool is available: 1.4.0 (you have 1.2.0). Run `mytool update` to upgrade.

$ mytool update
Current version: 1.2.0. Checking for updates…
Updated mytool 1.2.0 → 1.4.0.

The hint goes to stderr, so mytool status | jq stays clean.

The three calls in detail

Call	When	Notes
CleanupLeftovers()	Once at startup	Package-level, no Updater needed. Removes the <exe>.old file a previous Windows update left. Never errors.
NotifyIfAvailable(w, current)	Late in a normal run	Prints the cached result, then refreshes for next time. Never blocks >1.5s. Silent on dev builds and when the opt-out env var is set.
Run(ctx, w, current, checkOnly)	Your update subcommand	Prints progress, installs, reports. Returns an error; you own the exit code. ctx lets Ctrl-C interrupt a download; without a deadline it gets UpdateTimeout (60s).

current takes your version with or without a leading v. "", "dev" and "(devel)" are treated as source builds and never updated over — a local build is usually ahead of the last tag.

A runnable version lives in examples/minimal.

✨ Features

• 🔒 Verified downloads — SHA-256 against the release checksums, before anything touches your binary
• ✍️ Optional signing — Ed25519 over the checksums, with key rotation that doesn't brick shipped binaries
• 🪟 Windows-correct — a running .exe can't be overwritten, so it's renamed aside and cleaned up next run
• ⚡ Free on the hot path — the notice reads a cache; the network refresh is bounded at 1.5s, once a day
• 📦 Two release layouts — archives or raw binaries, or bring your own naming
• 🧊 Zero dependencies — standard library only, enforced by CI
• 🧪 Testable — three Config seams point the whole flow at httptest and a temp dir
• 🚫 Opinionated refusals — no downgrades, no dev-build clobbering, no plain HTTP, no truncated installs

📤 What your release must ship

The library finds nothing unless your release publishes these names. Repo mytool, tag v1.2.0:

mytool_1.2.0_linux_amd64.tar.gz      ← contains a file named "mytool"
mytool_1.2.0_darwin_arm64.tar.gz
mytool_1.2.0_windows_amd64.zip       ← contains "mytool.exe"
mytool_1.2.0_checksums.txt
mytool_1.2.0_checksums.txt.sig       ← only when signing

Checksums are plain sha256sum output, hashing the archive, not the binary inside it:

9f2c…  mytool_1.2.0_linux_amd64.tar.gz

The five things that trip people up:

1. The tag carries v, the file names don't. v1.2.0 → assets say _1.2.0_. The most common mistake by far.
2. Stamp the version in: -ldflags "-X main.version=1.2.0". Without it your build reports dev and the updater refuses to touch it.
3. Set AppName if the binary isn't named after the repo — one field, not six.
4. Signing is all-or-nothing. With a verifier set, a release without a .sig is an error, never a fallback.
5. Tags must match ^[0-9][0-9A-Za-z.+-]{0,63}$ once v is stripped, or the release is rejected.

Also: pre-release tags (v1.2.0-rc.1) never appear in GitHub's releases/latest, so they're never offered. A missing platform asset gives a clear error, not a silent skip.

🎛️ What you get for free

For Config{Owner: "you", Repo: "mytool"} — all derived from AppName, which defaults to Repo:

	Default
Asset name	mytool_<version>_<goos>_<goarch>.tar.gz (.zip on Windows)
Binary inside	mytool (mytool.exe on Windows)
Checksums file	mytool_<version>_checksums.txt
Upgrade hint	mytool update
Opt-out variable	MYTOOL_NO_UPDATE_CHECK
State cache	<os.UserConfigDir>/mytool/update-check.json
User agent	mytool-updater
Check interval / timeouts	24h · 1.5s notice · 60s update

[!TIP] Binary not named after the repo? Set AppName and stop — asset names, checksums file, opt-out variable, state dir, user agent and hint text all follow it. Repo compose-check-updates shipping ccu needs AppName: "ccu", not six separate overrides.

Every field is overridable on Config.

🗂️ Release layouts

Layout	Produces	Use when
&layout.Archive{} (default)	mytool_1.2.0_linux_amd64.tar.gz	goreleaser-style, binary inside an archive
&layout.RawBinary{}	mytool-linux-amd64 (.exe on Windows)	your README's install one-liner curls that exact name

Neither fits? Override the names instead of forking:

Layout: &layout.Archive{
    Name:       func(version, goos, goarch string) string { ... },
    BinaryName: func(goos string) string { ... },
},
ChecksumsName: func(version string) string { ... },

Or implement layout.Layout — three methods.

🔐 Signing releases

Checksums only prove the download wasn't corrupted in transit. They travel over the same channel as the binary, so anyone who can edit release assets regenerates both and verification still "passes". Signing anchors trust in a key that never lives in the repo or the release.

Verifier: &verify.Ed25519{
    Keys:   []string{"sQrabBts6F9SlNhvnwFw5HRHS8xHHM92frEJKpctvd4"},
    Domain: "mytool release checksums v1",
},

• Unsigned release → refused outright. Never downgraded to a warning.
• Replay-proof. The signed message includes the checksums file's name, which carries the version, so an old signed release can't reappear under a newer tag.
• Cheap to reject. Signature presence is checked against metadata already in hand, then the small files are verified — a bad release never costs you a 64 MiB download.
• Fails closed. An empty or all-garbage key list refuses everything; it never becomes "no key, so skip".

Sign at release time with the same struct — v.Sign(privateKey, checksumsName, content) — and upload the result as <checksums name>.sig. See examples/signed.

[!WARNING] Keys is a list so you can rotate. A binary only trusts the keys it was compiled with, so swapping the sole key makes every shipped binary reject every new release — permanently, unfixably. Instead: add the successor, ship releases signed by it while both are trusted, drop the old one once users have upgraded.

🖥️ For a TUI

latest := up.Refresh(version) // "" when current, disabled, or unreachable

Unlike NotifyIfAvailable, this refreshes a stale cache and reports what's true now. Blocks up to 1.5s — call it off the UI thread.

🛡️ What it refuses to do

Deliberate, load-bearing refusals. If one is in your way, the answer is almost never to remove it.

• https-only, GitHub hosts only — redirects included. A checksum only vouches for a download if the whole chain is authenticated. Loopback may use plain http, so tests can serve locally.
• Release tags validated at ingress — leading digit, [0-9A-Za-z.+-], ≤64 bytes. Tags reach your terminal, file names and cache: no ANSI escapes, no ../, no homoglyphs.
• Size caps error, never truncate — including what an archive inflates to. A truncated binary bricks an install as thoroughly as a malicious one.
• Only strictly newer versions install — an attacker controlling the network can stall you, but can't serve an older, known-vulnerable release as an "update".
• Dev and source builds are never touched.
• Errors never echo server text — not the URL, not the HTTP status line.
• The new binary is not re-executed — the process keeps the code it loaded.
• The cache is re-validated on load — it's attacker-influencable at rest.
• Nothing large is fetched before it's trusted.

🧪 Testing your integration

Three Config seams run the whole flow offline:

Seam	Point it at
APIBase	an httptest server instead of api.github.com
StatePath	a temp file, so tests never touch the real cache
ExecutablePath	a throwaway file, so an install doesn't overwrite your test binary

cfg := selfupdate.Config{
    Owner: "you", Repo: "mytool",
    APIBase:        srv.URL,
    StatePath:      func() (string, error) { return filepath.Join(t.TempDir(), "c.json"), nil },
    ExecutablePath: func() (string, error) { return throwaway, nil },
}

Take a Config in your own constructor so production passes the zero value and tests pass their seams. examples/testing is a complete, runnable version — copy tool_test.go and change the names.

📚 Packages

Package	What's in it
. (selfupdate)	Config, New, Updater — what you integrate against
layout	How release assets are named and packed
verify	Optional Ed25519 signature verification
version	Semver ordering and the ingress guard
internal/…	GitHub client, checksums, the atomic swap, the cache

Most integrations import only the root package. Integration notes for coding agents live in llm.txt.

🛠️ Development

just ci          # vet + gofmt + race + dependency gate
just test        # go test ./...
just cover       # per-package coverage

CI runs on Windows, macOS and Linux — the executable swap takes a different path on Windows. It also fails the build if a third-party dependency ever appears: a self-updater with a dependency tree is a supply-chain surface sitting directly on the code path that replaces the user's binary.

📄 License

MIT

Documentation

Overview

Package selfupdate self-updates a Go CLI from its GitHub Releases, and prints the passive "a newer version is available" notice that goes with it.

The flow: ask GitHub for the latest release, compare it against the running version, download the asset for this platform, verify its SHA-256 against the release's checksums file (and, with a verify.Verifier, verify that checksums file's signature), unpack the executable, and atomically swap it in place of the running binary.

A minimal integration is three calls:

up, err := selfupdate.New(selfupdate.Config{Owner: "you", Repo: "mytool"})
if err != nil {
	return err
}
selfupdate.CleanupLeftovers()                      // once, at startup
up.NotifyIfAvailable(os.Stderr, buildinfo.Version) // passive hint
err = up.Run(ctx, os.Stdout, buildinfo.Version, false) // the `update` subcommand

Only Owner and Repo are required; everything else is derived from them. If the binary is not named after the repository, set Config.AppName — every other default follows it. See Config for the full list, and the layout package for matching a release workflow that names its assets differently.

What it refuses to do

The defaults are chosen so that a hostile release, a hostile network, or a tampered cache cannot turn an update check into an install of something the project did not publish:

• Downloads are https-only to GitHub-controlled hosts, redirects included — a checksum only vouches for a download if the whole chain is authenticated.
• Release tags are validated at ingress, before they reach a terminal, a file name, or the on-disk cache.
• Size caps are errors, never truncation: a truncated binary bricks an install as thoroughly as a malicious one.
• Only a strictly newer version installs, so an attacker who controls the network can stall a user on their current version but cannot serve them an older, known-vulnerable release as an "update".
• Dev and source builds are never updated over.
• Error messages never echo server-supplied URLs or HTTP status text.

Checksums alone do not protect against someone who can edit release assets; see the verify package for closing that gap with a signing key.

Index

• Constants
• func CleanupLeftovers()
• type Asset
• type Config
• type Release
• type Result
• type Updater
  • func New(cfg Config) (*Updater, error)
  • func (u *Updater) DisableEnvName() string
  • func (u *Updater) Disabled(current string) bool
  • func (u *Updater) LatestRelease(ctx context.Context) (*Release, error)
  • func (u *Updater) NotifyIfAvailable(w io.Writer, current string)
  • func (u *Updater) Refresh(current string) string
  • func (u *Updater) Run(ctx context.Context, w io.Writer, current string, checkOnly bool) error
  • func (u *Updater) SelfUpdate(ctx context.Context, current string, checkOnly bool) (*Result, error)

Constants

const (
	// DefaultMaxAsset caps how many bytes are accepted from a release asset — the
	// download and, for archive layouts, the binary inside it — so a hostile or
	// corrupt response can't exhaust memory. Release binaries are a few MB.
	DefaultMaxAsset = int64(64 << 20) // 64 MiB

	// DefaultMaxChecksums is far tighter: a genuine checksums file is a few
	// hundred bytes, so there is no reason to buffer megabytes of "checksums" a
	// hostile release asset serves up.
	DefaultMaxChecksums = int64(1 << 20) // 1 MiB

	// DefaultCheckInterval is how often the passive notice refreshes its cached
	// "latest version", so normal commands never repeatedly hit the network.
	DefaultCheckInterval = 24 * time.Hour

	// DefaultNoticeTimeout bounds the background refresh, so a slow or
	// unreachable GitHub can't delay the user's command by more than this.
	DefaultNoticeTimeout = 1500 * time.Millisecond

	// DefaultUpdateTimeout bounds the whole check-download-verify-install cycle.
	// Generous compared to the notice, since the user explicitly asked to update
	// and is waiting on the result rather than being interrupted by it.
	DefaultUpdateTimeout = 60 * time.Second
)

Default sizes and timings. All are overridable through Config.

Functions

func CleanupLeftovers

func CleanupLeftovers()

CleanupLeftovers removes the "<exe>.old" file left behind by a prior Windows self-update. Call it once at startup; it is best effort and never errors, so calling it is always safe.

Types

type Asset

type Asset = ghrelease.Asset

Asset is one downloadable file attached to a Release.

type Config

type Config struct {
	// Owner is the GitHub user or organisation that owns the releases. Required.
	Owner string

	// Repo is the repository name — where the releases live. Required.
	//
	// It seeds AppName, and through it every other default, so a project whose
	// binary and repository share a name needs nothing else.
	Repo string

	// AppName is how the tool calls itself: the binary name, the name in
	// user-facing text, and the basis for every other derived default. Defaults
	// to Repo.
	//
	// Set it whenever the binary is not named after the repository — for a repo
	// "compose-check-updates" shipping a binary "ccu", AppName: "ccu" is what
	// makes the asset names, checksums file, opt-out variable, state directory
	// and user agent all say "ccu" instead of the repository name.
	AppName string

	// UpdateCmd is the command shown in the "run X to upgrade" hint. Defaults to
	// "<AppName> update".
	UpdateCmd string

	// DisableEnv is the environment variable that switches update checking off
	// when set to anything non-empty. Defaults to "<APPNAME>_NO_UPDATE_CHECK",
	// with non-alphanumerics replaced by underscores.
	DisableEnv string

	// Layout describes the release asset naming and packaging. Defaults to
	// &layout.Archive{}.
	Layout layout.Layout

	// ChecksumsName names the checksums asset for a version. Defaults to
	// "<AppName>_<version>_checksums.txt".
	ChecksumsName func(version string) string

	// Verifier authenticates the checksums file. Nil means checksums-only — see
	// the verify package for what that does and does not protect against.
	Verifier verify.Verifier

	// HTTP is the client used for all requests. Nil gets one with a 30s timeout
	// and an https-only redirect policy. A supplied client without a CheckRedirect
	// has that policy installed on it.
	HTTP *http.Client

	// APIBase is the GitHub API root. Defaults to https://api.github.com; tests
	// point it at a local server.
	APIBase string

	// UserAgent identifies this client to GitHub, which rejects requests without
	// one outright. Defaults to "<AppName>-updater".
	UserAgent string

	// StatePath returns where the update-check cache lives. Defaults to
	// "<os.UserConfigDir>/<AppName>/update-check.json" — %AppData% on Windows,
	// ~/.config elsewhere.
	StatePath func() (string, error)

	// ExecutablePath returns the binary an update replaces. Defaults to the
	// running executable with symlinks resolved, which is what you want in
	// production.
	//
	// Override it in tests to point the install at a throwaway file, so a test
	// that exercises the real install path does not overwrite the test binary.
	ExecutablePath func() (string, error)

	// MaxAsset, MaxChecksums, CheckInterval, NoticeTimeout and UpdateTimeout
	// override the Default* constants when non-zero.
	MaxAsset      int64
	MaxChecksums  int64
	CheckInterval time.Duration
	NoticeTimeout time.Duration
	UpdateTimeout time.Duration
}

Config describes one project's release setup.

Owner and Repo are required. Every other field has a working default derived from Repo, so the common case is a two-field literal.

type Release

type Release = ghrelease.Release

Release is a published GitHub release: its tag and the assets attached to it.

type Result

type Result struct {
	Current string // version before the attempt
	Latest  string // latest available version
	Updated bool   // whether the binary was replaced
	ExePath string // the binary that was (or would be) replaced
}

Result reports the outcome of an update attempt.

type Updater

type Updater struct {
	// contains filtered or unexported fields
}

Updater is a configured self-updater. Create one with New and keep it for the process's lifetime; it holds no per-call state and is safe for concurrent use.

func New

func New(cfg Config) (*Updater, error)

New returns an Updater for cfg, filling in every default. It fails only when Owner or Repo is missing — the two things it cannot invent.

func (*Updater) DisableEnvName

func (u *Updater) DisableEnvName() string

DisableEnvName returns the environment variable that switches update checking off for this Updater — the configured DisableEnv, or the name derived from Repo.

Useful for a help text or a `--version` footer that tells users how to silence the notice, without restating the derivation rule and letting it drift.

func (*Updater) Disabled

func (u *Updater) Disabled(current string) bool

Disabled reports whether update checking is off for this run: the opt-out environment variable is set, or this is a source build with no release to compare against.

func (*Updater) LatestRelease

func (u *Updater) LatestRelease(ctx context.Context) (*Release, error)

LatestRelease fetches the latest published release, for callers that want the tag or asset list rather than an update.

func (*Updater) NotifyIfAvailable

func (u *Updater) NotifyIfAvailable(w io.Writer, current string)

NotifyIfAvailable prints a one-line "newer version available" hint to w when the cached latest version is newer than current, then refreshes a stale cache. It never blocks longer than Config.NoticeTimeout.

Write to stderr, not stdout, so the tool's actual output stays pipeable.

The notice reflects the *previously* cached check; the refresh here is for the next run. That is what keeps it cheap on the hot path — the first run after a release ships stays silent, and the one after it tells the user.

func (*Updater) Refresh

func (u *Updater) Refresh(current string) string

Refresh returns the latest version when it is newer than current, and "" otherwise. It refreshes a stale cache first, so unlike Updater.NotifyIfAvailable it reports what is true now — which a TUI can afford, calling it off the UI thread. It blocks for at most Config.NoticeTimeout.

func (*Updater) Run

func (u *Updater) Run(ctx context.Context, w io.Writer, current string, checkOnly bool) error

Run performs (or checks for) a self-update, writing human-readable progress to w. It is the whole body of a `mytool update` subcommand.

ctx bounds the whole check-download-verify-install cycle, so a caller that wires up signal handling can let Ctrl-C interrupt an in-flight download. If ctx has no deadline of its own, Config.UpdateTimeout is applied as one; pass context.Background() to just get that default.

Errors travel back unwrapped: the caller owns the exit code, this only decides what the user reads.

func (*Updater) SelfUpdate

func (u *Updater) SelfUpdate(ctx context.Context, current string, checkOnly bool) (*Result, error)

SelfUpdate checks for a newer release and, unless checkOnly, downloads, verifies and installs it in place of the running binary. current is the running version, with or without a leading "v".

checkOnly makes exactly one network request — the release lookup — and returns as soon as it knows the latest version. It downloads nothing, writes nothing, and does not touch the notice cache. The Result still reports Latest, so a caller can report an available update without installing it.

The updated binary is NOT re-executed: the calling process keeps running the old code it already loaded, which is both simpler and safer than re-exec'ing mid-command with arguments that may no longer mean the same thing.

A dev or source build is refused outright — it has no release to compare against, and silently overwriting it with a published binary would discard the user's own build.