selfupdate

README

go-selfupdate

Self-updates for Linux Go CLIs from GitHub releases. Standard library only; Go 1.23+.

Usage

import selfupdate "github.com/FiretailHosting/go-selfupdate"

updater := selfupdate.Updater{
    Owner: "FiretailHosting", Repo: "my-cli",
    Name: "my-cli", Version: version,
    Token: token, // optional for public repositories
}
installedVersion, err := updater.Install(ctx, executablePath)

Supports Linux amd64/arm64. Publish stable vX.Y.Z releases containing <name>-linux-<arch> and checksums.txt in sha256sum format. The binary's --version must print X.Y.Z.

Installs verify SHA-256 and version, then atomically replace the executable, resolving symlinks. Downloads are bounded; credentials stay on the API origin. Checksums do not protect against a compromised release publisher.

updater.Check(ctx, updater.CachePath(), time.Now()) returns a newer version or empty, silently caching checks and failures for 24 hours. Call it only when a notice is appropriate; the caller handles output and token lookup.

Development

make check

MIT licensed.

Documentation

Overview

Package selfupdate updates Linux CLI executables from stable GitHub releases.

Index

• Constants
• func Newer(candidate, current string) bool
• type Updater
  • func (updater Updater) CachePath() string
  • func (updater Updater) Check(ctx context.Context, cachePath string, now time.Time) string
  • func (updater Updater) Install(ctx context.Context, executablePath string) (string, error)

Constants

const CheckInterval = 24 * time.Hour

Functions

func Newer

func Newer(candidate, current string) bool

Newer compares stable X.Y.Z versions. Invalid candidates are never newer; an invalid current version (including dev) compares as 0.0.0.

Types

type Updater

type Updater struct {
	Owner, Repo   string
	Name, Version string
	Token         string
	// ReleaseURL overrides the latest-release endpoint, primarily for tests.
	ReleaseURL string
}

Updater describes a CLI whose releases contain <Name>-linux-<arch> and checksums.txt. The executable must print its bare X.Y.Z version for --version. Tokens are optional for public repositories. Callers own environment lookup, command selection, and output; this package never restarts the program.

func (Updater) CachePath

func (updater Updater) CachePath() string

CachePath returns the OS cache path for this CLI, or empty if unavailable.

func (Updater) Check

func (updater Updater) Check(ctx context.Context, cachePath string, now time.Time) string

Check returns a newer version, or empty. Checks and failures are cached for 24 hours; errors are silent. Callers decide when a notice is appropriate. Separate concurrent processes may each perform a check on a cache miss.

func (Updater) Install

func (updater Updater) Install(ctx context.Context, executablePath string) (string, error)

Install installs the latest newer release at executablePath, resolving symlinks. It verifies SHA-256 and --version before an atomic rename. A checksum protects against corruption, not a compromised release publisher. Returns the installed version, or the current version if already up to date.