feat: allow cli args to be set via env vars (#88)

Author: MacroPower

internal/cli/env.go

@@ -0,0 +1,70 @@
+package cli
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// bindEnvVars automatically binds environment variables to cobra command flags.
+// Environment variable names are generated as KAT_<FLAG_NAME> where the flag name
+// is converted to uppercase and dashes are replaced with underscores.
+//
+// For example:
+//   - Flag "log-level" becomes environment variable "KAT_LOG_LEVEL"
+//   - Flag "config" becomes environment variable "KAT_CONFIG"
+//
+// Arguments take precedence over environment variables, which take precedence
+// over default values.
+//
+// This function also updates flag usage descriptions to include the environment
+// variable name, making it visible in help output.
+func bindEnvVars(cmd *cobra.Command) {
+	cmd.Flags().VisitAll(func(flag *pflag.Flag) {
+		bindFlagToEnv(flag)
+	})
+
+	cmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		bindFlagToEnv(flag)
+	})
+}
+
+// bindFlagToEnv binds a single flag to its corresponding environment variable.
+func bindFlagToEnv(flag *pflag.Flag) {
+	envName := flagToEnvName(flag.Name)
+
+	// Update the flag usage to include the environment variable name.
+	if !strings.Contains(flag.Usage, envName) {
+		flag.Usage = fmt.Sprintf("%s ($%s)", flag.Usage, envName)
+	}
+
+	// Skip if flag was already set via command line arguments.
+	if flag.Changed {
+		return
+	}
+
+	envValue, ok := os.LookupEnv(envName)
+	if ok {
+		err := flag.Value.Set(envValue)
+		if err != nil {
+			// Log error but don't fail - use default value instead.
+			slog.Error("failed to set flag from environment variable",
+				slog.String("flag", flag.Name),
+				slog.String("env", envName),
+				slog.String("value", envValue),
+				slog.Any("error", err),
+			)
+		}
+	}
+}
+
+// flagToEnvName converts a flag name to its corresponding environment variable name.
+// Example: "log-level" -> "KAT_LOG_LEVEL".
+func flagToEnvName(flagName string) string {
+	envName := strings.ReplaceAll(flagName, "-", "_")
+	return strings.ToUpper(cmdName + "_" + envName)
+}

internal/cli/env_test.go

@@ -0,0 +1,91 @@
+package cli_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/macropower/kat/internal/cli"
+)
+
+func TestBindEnvVars(t *testing.T) {
+	tcs := map[string]struct {
+		envVars       map[string]string
+		wantLogLevel  string
+		wantLogFormat string
+		args          []string
+	}{
+		"environment variables are bound when no args provided": {
+			envVars: map[string]string{
+				"KAT_LOG_LEVEL":  "debug",
+				"KAT_LOG_FORMAT": "json",
+			},
+			args:          []string{},
+			wantLogLevel:  "debug",
+			wantLogFormat: "json",
+		},
+		"command line args take precedence over environment variables": {
+			envVars: map[string]string{
+				"KAT_LOG_LEVEL":  "debug",
+				"KAT_LOG_FORMAT": "json",
+			},
+			args:          []string{"--log-level", "error", "--log-format", "text"},
+			wantLogLevel:  "error",
+			wantLogFormat: "text",
+		},
+		"partial environment variable override": {
+			envVars: map[string]string{
+				"KAT_LOG_LEVEL": "warn",
+			},
+			args:          []string{"--log-format", "json"},
+			wantLogLevel:  "warn",
+			wantLogFormat: "json",
+		},
+		"no environment variables uses defaults": {
+			envVars:       map[string]string{},
+			args:          []string{},
+			wantLogLevel:  "info", // Default value.
+			wantLogFormat: "text", // Default value.
+		},
+	}
+
+	for name, tc := range tcs {
+		t.Run(name, func(t *testing.T) {
+			for key, val := range tc.envVars {
+				t.Setenv(key, val)
+			}
+
+			cmd := cli.NewRootCmd()
+			cmd.SetArgs(tc.args)
+
+			// Parse flags (this triggers environment variable binding).
+			err := cmd.ParseFlags(tc.args)
+			require.NoError(t, err)
+
+			// Check flag values.
+			logLevel, err := cmd.Flags().GetString("log-level")
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantLogLevel, logLevel)
+
+			logFormat, err := cmd.Flags().GetString("log-format")
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantLogFormat, logFormat)
+		})
+	}
+}
+
+// Test that flag usage strings are updated to include environment variable names.
+func TestEnvironmentVariableUsageUpdate(t *testing.T) {
+	t.Parallel()
+
+	cmd := cli.NewRootCmd()
+
+	logLevelFlag := cmd.PersistentFlags().Lookup("log-level")
+	require.NotNil(t, logLevelFlag)
+	assert.Contains(t, logLevelFlag.Usage, "$KAT_LOG_LEVEL")
+
+	configFlag := cmd.Flags().Lookup("config")
+	require.NotNil(t, configFlag)
+	assert.Contains(t, configFlag.Usage, "$KAT_CONFIG")
+}

internal/cli/root.go

@@ -24,8 +24,10 @@ func NewRootArgs() *RootArgs {
 }
 
 func (ra *RootArgs) AddFlags(cmd *cobra.Command) {
-	cmd.PersistentFlags().StringVar(&ra.LogLevel, "log-level", "info", fmt.Sprintf("Log level %s", log.AllLevels))
-	cmd.PersistentFlags().StringVar(&ra.LogFormat, "log-format", "text", fmt.Sprintf("Log format %s", log.AllFormats))
+	cmd.PersistentFlags().
+		StringVar(&ra.LogLevel, "log-level", "info", fmt.Sprintf("Log level, one of: %s", log.AllLevels))
+	cmd.PersistentFlags().
+		StringVar(&ra.LogFormat, "log-format", "text", fmt.Sprintf("Log format, one of: %s", log.AllFormats))
 
 	var err error
 
@@ -63,6 +65,8 @@ func NewRootCmd() *cobra.Command {
 	runArgs.AddFlags(cmd)
 	cmd.AddCommand(runCmd)
 
+	bindEnvVars(cmd)
+
 	return cmd
 }
 

internal/cli/run.go

@@ -124,6 +124,8 @@ func NewRunCmd(ra *RunArgs) *cobra.Command {
 	}
 	ra.AddFlags(cmd)
 
+	bindEnvVars(cmd)
+
 	return cmd
 }