clive

README

clive

Version detection, display, and update-check helpers for Go CLIs.

Packages

Package	Description
clive	Version detection, display, and update checks
clive/semver	Semantic version parsing and comparison
clive/updater	Shared self-update interface and helpers
clive/updater/brew	Self-update a CLI binary through Homebrew
clive/updater/goinstall	Self-update a CLI binary through go install
clive/updater/github	Self-update a CLI binary from GitHub release assets
clive/notify	Background update hints

Installation

go get github.com/gechr/clive

Usage

Inject build metadata via -ldflags

VERSION=$(git describe --tags)
BUILDTIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)

go build -ldflags "-s -w \
  -X github.com/gechr/clive.version=${VERSION} \
  -X github.com/gechr/clive.buildTime=${BUILDTIME}" ./...

When ldflags are not set (e.g. go install ...@latest), clive.Current falls back to debug.BuildInfo so the binary still reports a sensible version.

Print the version

import "github.com/gechr/clive"

func main() {
    if printVersion {
        clive.Print()
        return
    }
}

Detailed version output with hyperlinks

info := clive.Info{Module: "github.com/gechr/myapp"}
info.PrintDetailed()

Version:     v0.1.2
Go version:  go1.26.2
OS/Arch:     darwin/arm64
Built:       2026-04-29T18:00:00Z (12 hours ago)
Commit:      a1b2c3d4...

Repo is auto-derived from Module when the module path starts with github.com/. Override explicitly when it doesn't:

info := clive.Info{
    Module: "go.example.com/myapp",
    Repo:   "myorg/myapp",
}

Check the Go module proxy for the latest version

latest, err := info.Latest(ctx)

Check for updates

info := clive.Info{Module: "github.com/gechr/myapp"}
if ok, _ := info.UpdateAvailable(ctx); ok {
    fmt.Printf("A new version is available. Run: go install %s@latest\n", info.Module)
}

Compare versions

import "github.com/gechr/clive/semver"

if semver.IsDev(clive.Current()) {
    base := semver.ExtractBase(clive.Current())
    // ...
}

a, _ := semver.Parse("v1.2.3")
b, _ := semver.Parse("v1.2.4")
semver.GreaterThan(b, a) // true

Documentation

Overview

Package clive provides version detection, display, and "latest version" lookup for Go CLIs.

Callers inject build metadata via -ldflags:

-X github.com/gechr/clive.version=$(VERSION)
-X github.com/gechr/clive.buildTime=$(BUILDTIME)

When ldflags are not set (e.g. `go install ...@latest` or `go build` without flags), Current falls back to debug.BuildInfo so the binary still reports a sensible version string.

Index

• func Current() string
• func DeriveVersion(moduleVersion, revision string) string
• func Print()
• type Info
  • func (i Info) Latest(ctx context.Context) (string, error)
  • func (i Info) LatestTag(ctx context.Context, client *http.Client) (string, error)
  • func (i Info) PrintDetailed()
  • func (i Info) UpdateAvailable(ctx context.Context) (bool, error)
  • func (i Info) VersionLink(v string) string
  • func (i Info) VersionURL(v string) string

Functions

func Current

func Current() string

Current returns the version string for the running binary, computing it once and caching the result.

Resolution order:

1. ldflag-injected `version` (Makefile path)
2. debug.BuildInfo Main.Version (Go module proxy / `go install`)
3. debug.BuildInfo vcs.revision (plain `go build`)

Dev versions are normalised so a trailing "-dev" is preserved or appended as appropriate.

func DeriveVersion

func DeriveVersion(moduleVersion, revision string) string

DeriveVersion resolves a display version from Go build metadata. A module version (set by `go install module@version` via the module proxy) is preferred over a VCS revision (from a plain `go build`). It returns "" when neither is available. Current uses it as the fallback when no version was injected via ldflags.

func Print

func Print()

Print writes Current to stdout, or a friendly placeholder when unknown.

Types

type Info

type Info struct {
	// Module is the Go module path, e.g. "github.com/gechr/clone".
	// Required by Latest.
	Module string

	// Repo is the GitHub "owner/name" used to build release/commit URLs.
	// If empty and Module starts with "github.com/", Repo is derived from it.
	Repo string

	// Private resolves Latest via direct version control rather than the public
	// module proxy, by scoping GOPRIVATE to Module for that one `go list` call.
	// Set it for a tool published from a private repository, so the lookup uses
	// the caller's local git credentials (e.g. SSH keys) instead of failing
	// against a proxy that cannot see the module. It has no effect on a public
	// module and never mutates the process environment.
	Private bool
}

Info identifies the binary for version-link and latest-lookup purposes. The zero value is usable for Current/Print but Latest and VersionLink require Module (and Repo for hyperlinks).

func (Info) Latest

func (i Info) Latest(ctx context.Context) (string, error)

Latest queries the Go module proxy for the latest published version of i.Module. Returns the raw `result.Version` string from `go list -m -json`. Requires `go` on PATH.

func (Info) LatestTag

func (i Info) LatestTag(ctx context.Context, client *http.Client) (string, error)

LatestTag returns the highest semver-shaped tag published in i's GitHub repository, read from the repository's tags list. Unlike Info.Latest, which shells out to the Go toolchain, it needs only network access, so a distributed binary - which has no `go` on PATH - can call it. A nil client uses http.DefaultClient. It returns "" with a nil error when the repository publishes no semver-shaped tag.

func (Info) PrintDetailed

func (i Info) PrintDetailed()

PrintDetailed writes a labelled table of version, Go runtime, OS/arch, build time, and VCS info. When i.Repo (or i.Module) is set, the version row is rendered as a clickable terminal hyperlink.

func (Info) UpdateAvailable

func (i Info) UpdateAvailable(ctx context.Context) (bool, error)

UpdateAvailable reports whether a newer version of i.Module is available on the module proxy than the currently running binary. It returns (false, nil) when the current version cannot be parsed or is already the latest. Requires `go` on PATH.

func (Info) VersionLink

func (i Info) VersionLink(v string) string

VersionLink returns v rendered as a clickable terminal hyperlink to the matching GitHub tag (release versions) or commit (dev versions). If i has no usable Repo, v is returned unchanged.

func (Info) VersionURL

func (i Info) VersionURL(v string) string

VersionURL returns the GitHub URL for v: the release-tag page for a release version, or the commit page for a dev version. It returns "" when i has no usable Repo or v has no derivable URL, so a caller can fall back to plain text.