feat(cli): add version subcommand and --version/-v flags (#7)

* feat(cli): add version subcommand and --version/-v flags

Both nebula-mgmt and nebula-agent now accept `version`, `--version`, and
`-v` and print a single-line banner:

    nebula-mgmt v0.1.2 (1b0d854, built 2026-05-11T13:22:49Z)

When built without ldflags (e.g. `go install ...@latest`), missing
fields are filled from runtime/debug.ReadBuildInfo.

ldflag targets renamed main.version -> main.versionStr to avoid
collision with the new internal/version package import.

Closes #1

* fix(version): explicitly discard fmt.Fprintf return to satisfy errcheck

Author: juev

.goreleaser.yml

@@ -16,7 +16,7 @@ builds:
     flags: [-trimpath]
     ldflags:
       - -s -w
-      - -X main.version={{.Version}}
+      - -X main.versionStr={{.Version}}
       - -X main.commit={{.Commit}}
       - -X main.date={{.Date}}
 
@@ -29,7 +29,7 @@ builds:
     flags: [-trimpath]
     ldflags:
       - -s -w
-      - -X main.version={{.Version}}
+      - -X main.versionStr={{.Version}}
       - -X main.commit={{.Commit}}
       - -X main.date={{.Date}}
 

Dockerfile

@@ -14,7 +14,7 @@ COPY . .
 
 ARG VERSION=dev
 RUN CGO_ENABLED=0 go build -trimpath \
-        -ldflags "-s -w -X main.version=${VERSION}" \
+        -ldflags "-s -w -X main.versionStr=${VERSION}" \
         -o /out/nebula-mgmt ./cmd/nebula-mgmt
 
 FROM alpine:3.20

README.md

@@ -107,6 +107,8 @@ Requires Go 1.26+.
 make build           # outputs bin/nebula-mgmt and bin/nebula-agent
 ```
 
+After install, `nebula-mgmt version` and `nebula-agent --version` print the build version, short commit, and build date.
+
 ## Quickstart
 
 ### 1. Run the server

cmd/nebula-agent/main.go

@@ -11,6 +11,14 @@ import (
 
 	"github.com/juev/nebula-mesh/internal/agent"
 	"github.com/juev/nebula-mesh/internal/config"
+	"github.com/juev/nebula-mesh/internal/version"
+)
+
+// Populated at build time via -ldflags (see .goreleaser.yml).
+var (
+	versionStr = "dev"
+	commit     = "none"
+	date       = "unknown"
 )
 
 func main() {
@@ -23,7 +31,7 @@ func main() {
 func run() error {
 	if len(os.Args) < 2 {
 		fmt.Fprintln(os.Stderr, "usage: nebula-agent <command> [flags]")
-		fmt.Fprintln(os.Stderr, "commands: enroll, run")
+		fmt.Fprintln(os.Stderr, "commands: enroll, run, version")
 		return fmt.Errorf("no command specified")
 	}
 
@@ -32,6 +40,9 @@ func run() error {
 		return runEnroll(os.Args[2:])
 	case "run":
 		return runAgent(os.Args[2:])
+	case "version", "--version", "-v":
+		version.Print(os.Stdout, "nebula-agent", versionStr, commit, date)
+		return nil
 	default:
 		return fmt.Errorf("unknown command: %s", os.Args[1])
 	}

cmd/nebula-mgmt/main.go

@@ -7,6 +7,14 @@ import (
 	"strings"
 
 	"github.com/juev/nebula-mesh/internal/cli"
+	"github.com/juev/nebula-mesh/internal/version"
+)
+
+// Populated at build time via -ldflags (see .goreleaser.yml).
+var (
+	versionStr = "dev"
+	commit     = "none"
+	date       = "unknown"
 )
 
 func main() {
@@ -31,6 +39,9 @@ func run() error {
 		return runHost(os.Args[2:])
 	case "network":
 		return runNetwork(os.Args[2:])
+	case "version", "--version", "-v":
+		version.Print(os.Stdout, "nebula-mgmt", versionStr, commit, date)
+		return nil
 	default:
 		printUsage()
 		return fmt.Errorf("unknown command: %s", os.Args[1])
@@ -39,7 +50,7 @@ func run() error {
 
 func printUsage() {
 	fmt.Fprintln(os.Stderr, "usage: nebula-mgmt <command> [flags]")
-	fmt.Fprintln(os.Stderr, "commands: init, serve, host, network")
+	fmt.Fprintln(os.Stderr, "commands: init, serve, host, network, version")
 }
 
 func runInit(args []string) error {

internal/version/version.go

@@ -0,0 +1,78 @@
+// Package version formats a CLI version banner.
+//
+// Each binary's main package declares its own ldflag-populated
+// `version`, `commit`, `date` variables and passes them to Print. When the
+// binary is built without ldflags (e.g. `go install`), missing fields are
+// filled from runtime/debug.ReadBuildInfo where possible.
+package version
+
+import (
+	"fmt"
+	"io"
+	"runtime/debug"
+)
+
+const (
+	devVersion     = "dev"
+	noCommit       = "none"
+	unknownDate    = "unknown"
+	shortCommitLen = 7
+)
+
+// Print writes a single-line version banner of the form
+//
+//	<name> <version> (<commit>, built <date>)
+//
+// Empty / placeholder fields are filled from runtime/debug.ReadBuildInfo
+// when available so that `go install ...@latest` builds also produce a
+// useful banner.
+func Print(w io.Writer, name, version, commit, date string) {
+	v, c, d := Resolve(version, commit, date)
+	if len(c) > shortCommitLen {
+		c = c[:shortCommitLen]
+	}
+	_, _ = fmt.Fprintf(w, "%s %s (%s, built %s)\n", name, v, c, d)
+}
+
+// Resolve returns the version triple, falling back to VCS info from the
+// embedded build info when the input fields are placeholders or empty.
+// Exported for testing.
+func Resolve(version, commit, date string) (string, string, string) {
+	if isPlaceholder(version) || isPlaceholder(commit) || isPlaceholder(date) {
+		if bi, ok := debug.ReadBuildInfo(); ok {
+			if isPlaceholder(version) && bi.Main.Version != "" && bi.Main.Version != "(devel)" {
+				version = bi.Main.Version
+			}
+			for _, s := range bi.Settings {
+				switch s.Key {
+				case "vcs.revision":
+					if isPlaceholder(commit) {
+						commit = s.Value
+					}
+				case "vcs.time":
+					if isPlaceholder(date) {
+						date = s.Value
+					}
+				}
+			}
+		}
+	}
+	if version == "" {
+		version = devVersion
+	}
+	if commit == "" {
+		commit = noCommit
+	}
+	if date == "" {
+		date = unknownDate
+	}
+	return version, commit, date
+}
+
+func isPlaceholder(s string) bool {
+	switch s {
+	case "", devVersion, noCommit, unknownDate:
+		return true
+	}
+	return false
+}

internal/version/version_test.go

@@ -0,0 +1,59 @@
+package version
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestPrint_FullValues(t *testing.T) {
+	var buf bytes.Buffer
+	Print(&buf, "nebula-mgmt", "v1.2.3", "abcdef0123456", "2026-01-02T03:04:05Z")
+	got := buf.String()
+	want := "nebula-mgmt v1.2.3 (abcdef0, built 2026-01-02T03:04:05Z)\n"
+	if got != want {
+		t.Errorf("Print = %q, want %q", got, want)
+	}
+}
+
+func TestPrint_ShortCommitNotTruncated(t *testing.T) {
+	var buf bytes.Buffer
+	Print(&buf, "x", "v1", "abc123", "2026")
+	got := buf.String()
+	if !strings.Contains(got, "(abc123, built 2026)") {
+		t.Errorf("short commit was truncated: %q", got)
+	}
+}
+
+func TestResolve_AllPlaceholdersFillsDefaults(t *testing.T) {
+	// With no ldflags, an `go install` of the test binary may still populate
+	// VCS info from the test runner's module — so we only assert the
+	// fallback contract: non-empty values for every field.
+	v, c, d := Resolve("", "", "")
+	if v == "" || c == "" || d == "" {
+		t.Errorf("Resolve filled empties incompletely: v=%q c=%q d=%q", v, c, d)
+	}
+}
+
+func TestResolve_KeepsExplicitValues(t *testing.T) {
+	v, c, d := Resolve("v9.9.9", "deadbeef", "2030-01-01")
+	if v != "v9.9.9" || c != "deadbeef" || d != "2030-01-01" {
+		t.Errorf("Resolve overwrote explicit values: v=%q c=%q d=%q", v, c, d)
+	}
+}
+
+func TestIsPlaceholder(t *testing.T) {
+	cases := map[string]bool{
+		"":        true,
+		"dev":     true,
+		"none":    true,
+		"unknown": true,
+		"v1.0.0":  false,
+		"abc123":  false,
+	}
+	for in, want := range cases {
+		if got := isPlaceholder(in); got != want {
+			t.Errorf("isPlaceholder(%q) = %v, want %v", in, got, want)
+		}
+	}
+}