Merge pull request #297 from michaelw/codex/align-config-discovery-docs

fix: align config path docs and implementation

Author: michaelw

cmd/cli/README.md

@@ -21,7 +21,7 @@ thand request access --provider aws-prod --role admin --duration 4h --reason "Da
 
 All commands support these global flags:
 
-- `--config <path>` - Config file (default: `$HOME/.thand/config.yaml`)
+- `--config <path>` - Config file (default: `$HOME/.config/thand/config.yaml`)
 - `--login-server <url>` - Override default login server URL (e.g., `http://localhost:8080`)
 - `--verbose`, `-v` - Enable verbose output
 
@@ -214,7 +214,7 @@ Launches a guided wizard that walks through creating an access request with prop
 
 ## Configuration
 
-The agent uses a YAML configuration file located at `$HOME/.thand/config.yaml` by default. You can specify a different config file using the `--config` flag.
+The agent uses a YAML configuration file located at `$HOME/.config/thand/config.yaml` by default. You can specify a different config file using the `--config` flag.
 
 **Example configuration:**
 ```yaml
@@ -260,4 +260,4 @@ thand service start
 
 # Update to latest version
 thand update --check
-```
+```

cmd/cli/main.go

@@ -311,7 +311,7 @@ func init() {
 
 	// Add global flags
 	rootCmd.PersistentFlags().BoolP("verbose", "v", false, "Enable verbose output")
-	rootCmd.PersistentFlags().String("config", "", "Config file (default is $HOME/.thand/config.yaml)")
+	rootCmd.PersistentFlags().String("config", "", "Config file (default is $HOME/.config/thand/config.yaml)")
 	// Add the login-server flag
 	rootCmd.PersistentFlags().String("login-server", "", "Override the default login server URL (e.g., http://localhost:8080)")
 

docs/configuration/cli.md

@@ -54,6 +54,8 @@ thand --verbose server
 
 ```
 
+`--config` takes precedence over `THAND_CONFIG_PATH`. `THAND_CONFIG_PATH` chooses the config file location, while other `THAND_*` environment variables override values loaded from that file.
+
 ---
 
 ## Main Command

docs/configuration/index.md

@@ -19,10 +19,12 @@ Thand Agent uses YAML configuration files to define behavior, providers, roles,
 Configuration is loaded in this order (later sources override earlier ones):
 
 1. Default values
-2. Configuration file (`~/.thand/config.yaml`)
+2. Configuration file (`~/.config/thand/config.yaml` by default, or the path set by `THAND_CONFIG_PATH`)
 3. Environment variables (prefixed with `THAND_`)
 4. Command line flags
 
+`--config` overrides `THAND_CONFIG_PATH`. `THAND_CONFIG_PATH` selects which config file to read, while other `THAND_*` variables override values after the file is loaded.
+
 {: .warning }
 > **Important:** If you are using Temporal (recommended for production), you must configure specific Search Attributes in your Temporal Namespace. See **[Temporal Configuration](temporal.md)** for critical setup instructions.
 

docs/environments/docker/index.md

@@ -126,10 +126,11 @@ docker run -d \
   -p 8080:8080 \
   -v $(pwd)/thand-config:/app/config:ro \
   -e THAND_CONFIG_PATH=/app/config/config.yaml \
-  ghcr.io/thand-io/agent:latest \
-  ./thand server --config /app/config/config.yaml
+  ghcr.io/thand-io/agent:latest
 ```
 
+`THAND_CONFIG_PATH` selects the config file to load inside the container. Other `THAND_*` variables still override values from that file.
+
 ### Option 2: Environment Variables
 
 Run with environment-based configuration:
@@ -425,4 +426,3 @@ docker run -d \
 - Set up [approval workflows](../../configuration/workflows)
 - Integrate with your existing authentication systems
 - Set up monitoring and alerting for production deployments
-

docs/getting-started.md

@@ -82,7 +82,7 @@ The binary will be available at `bin/agent`.
 
 ### Basic Configuration
 
-Create a configuration file at `~/.thand/config.yaml`:
+Create a configuration file at `~/.config/thand/config.yaml`:
 
 ```yaml
 server:

internal/config/config.go

@@ -8,7 +8,6 @@ import (
 	"log"
 	"net/http"
 	"os"
-	"os/user"
 	"path/filepath"
 	"runtime"
 	"runtime/debug"
@@ -30,6 +29,8 @@ import (
 var ErrNoActiveLoginSession = fmt.Errorf(
 	"you must login first. No valid session found to sync with login server")
 
+const configPathEnvVar = "THAND_CONFIG_PATH"
+
 func DefaultConfig() *Config {
 
 	v := viper.New()
@@ -111,9 +112,8 @@ func setupViperConfig(v *viper.Viper, configFile string) error {
 	v.AddConfigPath(".")
 	v.AddConfigPath("./config")
 	v.AddConfigPath("/etc/thand")
-	v.AddConfigPath("~/.config/thand")
 
-	if len(configFile) > 0 {
+	if configFile = resolveConfigFileOverride(configFile); len(configFile) > 0 {
 		v.SetConfigFile(configFile)
 	}
 
@@ -133,21 +133,23 @@ func setupViperConfig(v *viper.Viper, configFile string) error {
 	return nil
 }
 
+func resolveConfigFileOverride(configFile string) string {
+	configFile = strings.TrimSpace(configFile)
+	if len(configFile) > 0 {
+		return configFile
+	}
+
+	return strings.TrimSpace(os.Getenv(configPathEnvVar))
+}
+
 // setupHomeConfigPath adds the home directory config path if available
 func setupHomeConfigPath(v *viper.Viper) error {
-	home := os.Getenv("HOME")
-	if len(home) == 0 {
+	home, err := os.UserHomeDir()
+	if err != nil || len(home) == 0 {
 		return nil
 	}
 
-	// Get the user's home directory
-	usr, err := user.Current()
-	if err != nil {
-		logrus.Fatalf("Failed to get current user: %v", err)
-	}
-
-	// Expand the session manager path to use the actual home directory
-	sessionPath := filepath.Join(usr.HomeDir, ".config", "thand")
+	sessionPath := filepath.Join(home, ".config", "thand")
 	v.AddConfigPath(sessionPath)
 
 	// Check if the folder exists and create it if it does not exist

internal/config/config_path_test.go

@@ -0,0 +1,71 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/thand-io/agent/internal/common"
+)
+
+func TestLoad_PrefersExplicitConfigFileOverEnvOverride(t *testing.T) {
+	envConfigPath := writeTestConfigFile(t, filepath.Join(t.TempDir(), "env.yaml"), "env-secret")
+	explicitConfigPath := writeTestConfigFile(t, filepath.Join(t.TempDir(), "explicit.yaml"), "explicit-secret")
+
+	t.Setenv(configPathEnvVar, envConfigPath)
+
+	cfg, err := Load(explicitConfigPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, "explicit-secret", cfg.Secret)
+}
+
+func TestLoad_UsesConfigPathEnvOverrideWhenFlagNotProvided(t *testing.T) {
+	configPath := writeTestConfigFile(t, filepath.Join(t.TempDir(), "env.yaml"), "env-secret")
+
+	t.Setenv(configPathEnvVar, configPath)
+
+	cfg, err := Load("")
+	require.NoError(t, err)
+
+	assert.Equal(t, "env-secret", cfg.Secret)
+}
+
+func TestLoad_FindsDefaultConfigInHomeConfigDir(t *testing.T) {
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+	t.Setenv(configPathEnvVar, "")
+
+	configPath := filepath.Join(homeDir, ".config", "thand", "config.yaml")
+	writeTestConfigFile(t, configPath, "home-secret")
+
+	cfg, err := Load("")
+	require.NoError(t, err)
+
+	assert.Equal(t, "home-secret", cfg.Secret)
+}
+
+func TestLoad_DoesNotUseLegacyThandConfigPath(t *testing.T) {
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+	t.Setenv(configPathEnvVar, "")
+
+	legacyConfigPath := filepath.Join(homeDir, ".thand", "config.yaml")
+	writeTestConfigFile(t, legacyConfigPath, "legacy-secret")
+
+	cfg, err := Load("")
+	require.NoError(t, err)
+
+	assert.Equal(t, common.DefaultServerSecret, cfg.Secret)
+}
+
+func writeTestConfigFile(t *testing.T, path string, secret string) string {
+	t.Helper()
+
+	require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o755))
+	require.NoError(t, os.WriteFile(path, []byte("secret: "+secret+"\n"), 0o644))
+
+	return path
+}