kcc-cache: add -h/--help/help and usage message

kcc-cache is a pass-through wrapper that execs os.Args[1] on a cache
miss. Running 'kcc-cache -h' tried to exec a binary literally named
'-h', failing with a confusing PATH error. Handle -h/--help/help (and
the no-args case) explicitly with a usage message before treating the
first arg as a command.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V2pTHkL3AmyFqgyQhgrohw

Author: claude

cmd/kcc-cache/main.go

@@ -49,6 +49,22 @@ type Backend interface {
 }
 
 func main() {
+	// help
+	//
+	// kcc-cache wraps another command (os.Args[1:]) and execs it on a cache
+	// miss. Without this guard, `kcc-cache -h` would try to exec a binary
+	// literally named "-h" and fail with a confusing PATH error, so handle the
+	// usual help flags explicitly before treating the first arg as a command.
+	if len(os.Args) < 2 {
+		usage(os.Stderr)
+		os.Exit(1)
+	}
+	switch os.Args[1] {
+	case "-h", "--help", "help":
+		usage(os.Stdout)
+		os.Exit(0)
+	}
+
 	// configuration
 	var (
 		refreshMargin   = time.Second * 30
@@ -119,10 +135,7 @@ func main() {
 		fatal("cache read failed: %s", err)
 	}
 	if !ok || time.Until(cache.Status.ExpirationTimestamp) < refreshMargin {
-		// refresh
-		if len(os.Args) < 2 {
-			fatal("not enough command at args")
-		}
+		// refresh (os.Args[1] is guaranteed present; checked at startup)
 		cmd := exec.Command(os.Args[1], os.Args[2:]...)
 		cmd.Stderr = os.Stderr
 		bytes, err := cmd.Output()
@@ -289,6 +302,25 @@ func resolveCacheFilepath() string {
 	return path.Join(cacheDir, "kube-credential-cache", "cache.json")
 }
 
+// usage prints how to invoke kcc-cache. It is a transparent caching wrapper:
+// the arguments after the program name are the credential command it runs and
+// caches, so there are no flags of its own (configuration is via environment
+// variables, documented in the README).
+func usage(w *os.File) {
+	name := path.Base(os.Args[0])
+	fmt.Fprintf(w, "Usage: %s <command> [args...]\n", name)
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "Caching proxy for Kubernetes client-go credential plugins (ExecCredential).\n")
+	fmt.Fprintf(w, "Runs <command> [args...], caches its ExecCredential output, and serves it\n")
+	fmt.Fprintf(w, "from cache until the credential is near expiry.\n")
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "Example:\n")
+	fmt.Fprintf(w, "  %s aws --region <region> eks get-token --cluster-name <cluster>\n", name)
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "Configuration is via environment variables; see\n")
+	fmt.Fprintf(w, "https://github.com/ryodocx/kube-credential-cache#kcc-cache\n")
+}
+
 func fatal(format string, v ...any) {
 	log(format, v...)