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

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) PrintDetailed()
  • func (i Info) UpdateAvailable(ctx context.Context) (bool, error)
  • func (i Info) VersionLink(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
}

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) 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.