feat(cli): add explicit version metadata output

Author: saadjs

.github/workflows/release.yml

@@ -32,12 +32,20 @@ jobs:
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
+          VERSION: ${{ github.ref_name }}
+          COMMIT: ${{ github.sha }}
         run: |
           mkdir -p dist
           suffix=""
           if [ "${GOOS}" = "windows" ]; then suffix=".exe"; fi
           output="dist/kcal-${GOOS}-${GOARCH}${suffix}"
-          CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o "${output}" .
+          build_date="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+          if [ -z "${VERSION}" ]; then VERSION="v1.1.0"; fi
+          ldflags="-s -w \
+            -X github.com/saad/kcal-cli/cmd/kcal.version=${VERSION} \
+            -X github.com/saad/kcal-cli/cmd/kcal.commit=${COMMIT} \
+            -X github.com/saad/kcal-cli/cmd/kcal.date=${build_date}"
+          CGO_ENABLED=0 go build -trimpath -ldflags "${ldflags}" -o "${output}" .
 
       - name: Smoke test release binary (linux/amd64)
         if: matrix.goos == 'linux' && matrix.goarch == 'amd64'

CHANGELOG.md

@@ -20,6 +20,7 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 - Saved template database schema and model support for saved foods, saved meals, and saved meal components.
 - Saved template command families: `kcal saved-food ...` and `kcal saved-meal ...` (including create from entry/barcode, component management, archive/restore, and logging).
 - Saved templates included in JSON portability workflows (`kcal export --format json`, `kcal import --format json`), including coverage in portability tests.
+- Version metadata output via `kcal version`, `kcal -v`, and `kcal --version` (version tag, commit SHA, and build date).
 
 ### Changed
 - Consolidated GitHub Pages docs into a single-page experience at `docs/index.md` and removed legacy multi-page duplicates from publish paths.

cmd/kcal/root.go

@@ -8,11 +8,25 @@ import (
 )
 
 var dbPath string
+var showVersion bool
+
+var (
+	version = "v1.1.0"
+	commit  = "unknown"
+	date    = "unknown"
+)
 
 var rootCmd = &cobra.Command{
 	Use:   "kcal",
 	Short: "kcal tracks calories and macros from your terminal",
 	Long:  "kcal is a local-first calorie and macro tracking CLI with categories, recipes, goals, and analytics.",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if showVersion {
+			printVersion(cmd)
+			return nil
+		}
+		return cmd.Help()
+	},
 }
 
 func Execute() {
@@ -24,4 +38,9 @@ func Execute() {
 
 func init() {
 	rootCmd.PersistentFlags().StringVar(&dbPath, "db", "", "Path to SQLite database")
+	rootCmd.PersistentFlags().BoolVarP(&showVersion, "version", "v", false, "Show version/build metadata")
+}
+
+func printVersion(cmd *cobra.Command) {
+	fmt.Fprintf(cmd.OutOrStdout(), "kcal %s\ncommit: %s\ndate: %s\n", version, commit, date)
 }

cmd/kcal/root_test.go

@@ -3,10 +3,29 @@ package kcal
 import (
 	"bytes"
 	"path/filepath"
+	"strings"
 	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
+func resetCommandFlags(cmd *cobra.Command) {
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		_ = f.Value.Set(f.DefValue)
+		f.Changed = false
+	})
+	cmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
+		_ = f.Value.Set(f.DefValue)
+		f.Changed = false
+	})
+	for _, child := range cmd.Commands() {
+		resetCommandFlags(child)
+	}
+}
+
 func TestRootHelp(t *testing.T) {
+	resetCommandFlags(rootCmd)
 	buf := &bytes.Buffer{}
 	rootCmd.SetOut(buf)
 	rootCmd.SetErr(buf)
@@ -21,6 +40,7 @@ func TestRootHelp(t *testing.T) {
 }
 
 func TestInitCommandIdempotent(t *testing.T) {
+	resetCommandFlags(rootCmd)
 	path := filepath.Join(t.TempDir(), "kcal.db")
 	for i := 0; i < 2; i++ {
 		buf := &bytes.Buffer{}
@@ -32,3 +52,44 @@ func TestInitCommandIdempotent(t *testing.T) {
 		}
 	}
 }
+
+func TestRootVersionFlagAndCommand(t *testing.T) {
+	oldVersion, oldCommit, oldDate := version, commit, date
+	version = "v1.1.0"
+	commit = "abc123"
+	date = "2026-02-20T00:00:00Z"
+	t.Cleanup(func() {
+		version = oldVersion
+		commit = oldCommit
+		date = oldDate
+		showVersion = false
+	})
+
+	testCases := [][]string{
+		{"--version"},
+		{"-v"},
+		{"version"},
+	}
+
+	for _, args := range testCases {
+		resetCommandFlags(rootCmd)
+		buf := &bytes.Buffer{}
+		rootCmd.SetOut(buf)
+		rootCmd.SetErr(buf)
+		rootCmd.SetArgs(args)
+		if err := rootCmd.Execute(); err != nil {
+			t.Fatalf("execute %v: %v", args, err)
+		}
+		out := buf.String()
+		if !strings.Contains(out, "kcal v1.1.0") {
+			t.Fatalf("expected version in output for %v, got: %s", args, out)
+		}
+		if !strings.Contains(out, "commit: abc123") {
+			t.Fatalf("expected commit in output for %v, got: %s", args, out)
+		}
+		if !strings.Contains(out, "date: 2026-02-20T00:00:00Z") {
+			t.Fatalf("expected date in output for %v, got: %s", args, out)
+		}
+		showVersion = false
+	}
+}

cmd/kcal/version.go

@@ -0,0 +1,15 @@
+package kcal
+
+import "github.com/spf13/cobra"
+
+var versionCmd = &cobra.Command{
+	Use:   "version",
+	Short: "Show version/build metadata",
+	Run: func(cmd *cobra.Command, args []string) {
+		printVersion(cmd)
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(versionCmd)
+}

tests/cli_edge_cases_test.go

@@ -44,6 +44,24 @@ func runKcal(t *testing.T, binPath, dbPath string, args ...string) (string, stri
 	return stdout.String(), stderr.String(), exitErr.ExitCode()
 }
 
+func runKcalRaw(t *testing.T, binPath string, args ...string) (string, string, int) {
+	t.Helper()
+	cmd := exec.Command(binPath, args...)
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	err := cmd.Run()
+	if err == nil {
+		return stdout.String(), stderr.String(), 0
+	}
+	exitErr, ok := err.(*exec.ExitError)
+	if !ok {
+		t.Fatalf("run kcal command: %v", err)
+	}
+	return stdout.String(), stderr.String(), exitErr.ExitCode()
+}
+
 func initDB(t *testing.T, binPath, dbPath string) {
 	t.Helper()
 	_, stderr, exit := runKcal(t, binPath, dbPath, "init")
@@ -254,6 +272,29 @@ func TestCLIExerciseAddAllowsNoDistance(t *testing.T) {
 	}
 }
 
+func TestCLIVersionCommandAndFlags(t *testing.T) {
+	binPath := buildKcalBinary(t)
+
+	for _, args := range [][]string{{"--version"}, {"-v"}, {"version"}} {
+		stdout, stderr, exit := runKcalRaw(t, binPath, args...)
+		if exit != 0 {
+			t.Fatalf("expected version call %v to succeed: exit=%d stderr=%s", args, exit, stderr)
+		}
+		if stderr != "" {
+			t.Fatalf("expected empty stderr for %v, got: %s", args, stderr)
+		}
+		if !strings.Contains(stdout, "kcal v1.1.0") {
+			t.Fatalf("expected version output for %v, got: %s", args, stdout)
+		}
+		if !strings.Contains(stdout, "commit:") {
+			t.Fatalf("expected commit field for %v, got: %s", args, stdout)
+		}
+		if !strings.Contains(stdout, "date:") {
+			t.Fatalf("expected date field for %v, got: %s", args, stdout)
+		}
+	}
+}
+
 func TestMain(m *testing.M) {
 	os.Exit(m.Run())
 }