Simplify CLI: Make --root and --config optional

- Renamed --rails-root to --root for brevity
- Made --root optional, defaults to current directory (".")
- Made --config optional, auto-loads config/navigator.yml if present
- Updated all documentation and tests to reflect these changes

This makes Navigator easier to use - just run "navigator serve" in your
Rails app directory and it will automatically use the current directory
as root and load config/navigator.yml if it exists.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: rubys

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
         echo '"2025": {}' > /tmp/test-rails/config/tenant/showcases.yml
         
         # Test that binary starts and exits cleanly with new CLI syntax
-        timeout 5s ./navigator serve --rails-root /tmp/test-rails --listen :0 || [ $? -eq 124 ]
+        timeout 5s ./navigator serve --root /tmp/test-rails --listen :0 || [ $? -eq 124 ]
       
   build:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -138,7 +138,7 @@ jobs:
           echo "" >> release_notes.md
           echo "Extract the binary and run:" >> release_notes.md
           echo "\`\`\`bash" >> release_notes.md
-          echo "./navigator serve --rails-root /path/to/your/rails/app" >> release_notes.md
+          echo "./navigator serve --root /path/to/your/rails/app" >> release_notes.md
           echo "\`\`\`" >> release_notes.md
         fi
         

CLAUDE.md

@@ -65,23 +65,29 @@ Navigator is a modern Go-based web server that replaces nginx/Passenger for mult
 go build -o navigator cmd/navigator/main.go
 
 # Run with command-line arguments
-./navigator serve --rails-root /path/to/rails/app --listen :3000
+./navigator serve --root /path/to/rails/app --listen :3000
 
-# Run with configuration file
+# Run in current directory (uses '.' as default)
+./navigator serve
+
+# Run with configuration file (automatically looks for config/navigator.yml)
+./navigator serve
+
+# Run with custom configuration file
 ./navigator serve --config configs/navigator.yaml
 
 # Run with environment variables
 NAVIGATOR_RAILS_ROOT=/path/to/app ./navigator serve
 
 # Build and run in one command
-go build -o navigator cmd/navigator/main.go && ./navigator serve --rails-root /Users/rubys/git/showcase
+go build -o navigator cmd/navigator/main.go && ./navigator serve --root /Users/rubys/git/showcase
 
 # View help and available commands
 ./navigator --help
 ./navigator serve --help
 
 # Validate configuration
-./navigator config validate --rails-root /path/to/app
+./navigator config validate --root /path/to/app
 ```
 
 ### Development Workflow
@@ -146,12 +152,14 @@ When a Puma process dies, Navigator automatically:
 
 ### Configuration Methods
 
-Navigator supports three configuration methods (in order of precedence):
+Navigator supports three configuration methods (in order of precedence).
+
+**Note**: When no `--config` flag is provided, Navigator automatically looks for `config/navigator.yml` relative to the root directory.
 
 1. **Command-line flags** (highest priority):
 ```bash
 ./navigator serve \
-  --rails-root /path/to/rails/app \
+  --root /path/to/rails/app \
   --listen :3000 \
   --url-prefix /showcase \
   --max-puma 20 \
@@ -171,8 +179,11 @@ export NAVIGATOR_AUTH_HTPASSWD_FILE="/path/to/htpasswd"
 ```
 
 3. **YAML configuration file** (lowest priority):
+
+Navigator automatically checks for `config/navigator.yml` relative to the root directory. You can also create a custom configuration file:
+
 ```yaml
-# config/navigator.yaml
+# config/navigator.yml (or custom location)
 server:
   listen: ":3000"
   url_prefix: "/showcase"
@@ -276,7 +287,7 @@ ab -n 100 -c 5 -A username:password http://localhost:3000/2025/raleigh/disney/
 Navigator logs all requests and process management operations:
 
 ```bash
-./navigator -rails-root /path/to/app 2>&1 | tee navigator.log
+./navigator serve --root /path/to/app 2>&1 | tee navigator.log
 ```
 
 ### Common Issues

Makefile

@@ -13,7 +13,7 @@ build: ## Build the binary
 
 # Development targets
 dev: ## Build and run in development mode
-	go run cmd/navigator/main.go -rails-root $(PWD) -log-level debug
+	go run cmd/navigator/main.go serve --log-level debug
 
 clean: ## Clean build artifacts
 	rm -f ${BINARY_NAME}
@@ -70,7 +70,7 @@ watch: ## Watch files and rebuild on changes (requires entr)
 
 profile: ## Run with profiling enabled
 	go build ${LDFLAGS} -o ${BINARY_NAME} cmd/navigator/main.go
-	./${BINARY_NAME} -rails-root $(PWD) -log-level debug -cpuprofile cpu.prof -memprofile mem.prof
+	./${BINARY_NAME} serve --log-level debug -cpuprofile cpu.prof -memprofile mem.prof
 
 # Help
 help: ## Show this help message

README.md

@@ -43,12 +43,18 @@ go build -o navigator cmd/navigator/main.go
 
 ```bash
 # Start Navigator with command-line flags
-./navigator serve --rails-root /path/to/rails/app --listen :3000
+./navigator serve --root /path/to/rails/app --listen :3000
+
+# Or start in the current directory (uses '.' as default)
+./navigator serve
 
 # Or use environment variables
 NAVIGATOR_RAILS_ROOT=/path/to/rails/app ./navigator serve
 
-# Or use a configuration file
+# Or use a configuration file (automatically looks for config/navigator.yml)
+./navigator serve
+
+# Or specify a custom configuration file
 ./navigator serve --config /path/to/navigator.yaml
 
 # Get help and see all available commands
@@ -64,7 +70,7 @@ Navigator supports three configuration methods (in order of precedence):
 
 ```bash
 ./navigator serve \
-  --rails-root /path/to/rails/app \
+  --root /path/to/rails/app \
   --listen :3000 \
   --url-prefix /showcase \
   --max-puma 20 \
@@ -91,7 +97,7 @@ export NAVIGATOR_LOGGING_LEVEL="debug"
 
 ### 3. YAML Configuration File (Lowest Priority)
 
-Create a `navigator.yaml` file:
+Navigator automatically looks for `config/navigator.yml` relative to the root directory. You can also create a custom `navigator.yaml` file:
 
 ```yaml
 server:
@@ -117,14 +123,18 @@ logging:
 
 Then run:
 ```bash
+# Uses config/navigator.yml if present in root directory
+./navigator serve
+
+# Or specify a custom config file
 ./navigator serve --config navigator.yaml
 ```
 
 ### Configuration Options
 
 | Option | CLI Flag | Environment Variable | Default | Description |
 |--------|----------|---------------------|---------|-------------|
-| Rails Root | `--rails-root` | `NAVIGATOR_RAILS_ROOT` | *required* | Rails application directory |
+| Rails Root | `--root` | `NAVIGATOR_RAILS_ROOT` | `.` | Application root directory |
 | Listen Address | `--listen` | `NAVIGATOR_SERVER_LISTEN` | `:3000` | HTTP server bind address |
 | URL Prefix | `--url-prefix` | `NAVIGATOR_SERVER_URL_PREFIX` | `/showcase` | URL prefix to strip |
 | Max Puma | `--max-puma` | `NAVIGATOR_MANAGER_MAX_PUMA` | `10` | Max concurrent Puma processes |

internal/cli/commands_test.go

@@ -1,7 +1,6 @@
 package cli
 
 import (
-	"os"
 	"strings"
 	"testing"
 
@@ -55,7 +54,7 @@ func TestVersionCommand(t *testing.T) {
 func TestServeCommandFlags(t *testing.T) {
 	// Test that serve command has all expected flags
 	expectedFlags := []string{
-		"rails-root",
+		"root",
 		"listen", 
 		"url-prefix",
 		"max-puma",
@@ -88,7 +87,7 @@ func TestServeCommandFlags(t *testing.T) {
 func TestConfigValidateCommandFlags(t *testing.T) {
 	// Test that config validate command has required flags
 	expectedFlags := []string{
-		"rails-root",
+		"root",
 		"config",
 	}
 
@@ -176,9 +175,8 @@ func TestGetConfigInitialization(t *testing.T) {
 		config = originalConfig
 	}()
 
-	// Set minimal required environment for config loading
-	os.Setenv("NAVIGATOR_RAILS_ROOT", "/tmp")
-	defer os.Unsetenv("NAVIGATOR_RAILS_ROOT")
+	// No longer need to set NAVIGATOR_RAILS_ROOT since root has a default value
+	// The default '.' will be used
 
 	// GetConfig should initialize config without panicking
 	testConfig := GetConfig()

internal/cli/config.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 	"strings"
 	"time"
@@ -76,18 +77,36 @@ func LoadConfig(configFile string) (*Config, error) {
 			return nil, fmt.Errorf("error reading config file: %w", err)
 		}
 	} else {
-		// Try to find config file in common locations
-		v.SetConfigName("navigator")
-		v.SetConfigType("yaml")
-		v.AddConfigPath("./config") // Only look in project config directory
-		v.AddConfigPath("/etc/navigator")
-
-		// Read config file if found (ignore if not found or corrupted)
-		if err := v.ReadInConfig(); err != nil {
-			// Only return error if explicitly set config file, otherwise just warn and continue
-			if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+		// First get the root directory from viper (could be from flag or env)
+		rootDir := v.GetString("rails.root")
+		if rootDir == "" || rootDir == "." {
+			rootDir, _ = filepath.Abs(".")
+		} else {
+			rootDir, _ = filepath.Abs(rootDir)
+		}
+		
+		// Check for config/navigator.yml relative to root directory
+		defaultConfigPath := filepath.Join(rootDir, "config", "navigator.yml")
+		if _, err := os.Stat(defaultConfigPath); err == nil {
+			v.SetConfigFile(defaultConfigPath)
+			if err := v.ReadInConfig(); err != nil {
 				// Config file found but has errors - warn but continue
-				fmt.Printf("Warning: found config file but couldn't parse it: %v\n", err)
+				fmt.Printf("Warning: found config file at %s but couldn't parse it: %v\n", defaultConfigPath, err)
+			}
+		} else {
+			// Try to find config file in common locations
+			v.SetConfigName("navigator")
+			v.SetConfigType("yaml")
+			v.AddConfigPath("./config") // Look in local config directory
+			v.AddConfigPath("/etc/navigator")
+
+			// Read config file if found (ignore if not found or corrupted)
+			if err := v.ReadInConfig(); err != nil {
+				// Only return error if explicitly set config file, otherwise just warn and continue
+				if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+					// Config file found but has errors - warn but continue
+					fmt.Printf("Warning: found config file but couldn't parse it: %v\n", err)
+				}
 			}
 		}
 	}
@@ -113,6 +132,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("server.url_prefix", "/showcase")
 
 	// Rails defaults
+	v.SetDefault("rails.root", ".")
 	v.SetDefault("rails.showcases", "config/tenant/showcases.yml")
 	v.SetDefault("rails.db_path", "db")
 	v.SetDefault("rails.storage", "storage")
@@ -127,9 +147,9 @@ func setDefaults(v *viper.Viper) {
 
 // validateAndResolvePaths validates required fields and resolves relative paths
 func (c *Config) validateAndResolvePaths() error {
-	// Validate required fields
+	// Use current directory if Rails.Root is empty
 	if c.Rails.Root == "" {
-		return fmt.Errorf("rails.root is required")
+		c.Rails.Root = "."
 	}
 
 	// Resolve Rails root to absolute path

internal/cli/config_test.go

@@ -199,16 +199,22 @@ func TestValidateAndResolvePaths(t *testing.T) {
 	}
 }
 
-func TestValidateAndResolvePathsRequiredField(t *testing.T) {
+func TestValidateAndResolvePathsDefaultRoot(t *testing.T) {
 	config := &Config{
 		Rails: RailsConfig{
-			Root: "", // Missing required field
+			Root: "", // Empty root should default to "."
 		},
 	}
 
 	err := config.validateAndResolvePaths()
-	if err == nil {
-		t.Error("Expected error for missing rails.root, but got none")
+	if err != nil {
+		t.Errorf("Unexpected error: %v", err)
+	}
+
+	// Verify that empty root was replaced with "."
+	expectedRoot, _ := filepath.Abs(".")
+	if config.Rails.Root != expectedRoot {
+		t.Errorf("Expected root to be '%s', got '%s'", expectedRoot, config.Rails.Root)
 	}
 }
 

internal/cli/config_validate.go

@@ -24,7 +24,7 @@ This command will:
 Examples:
   navigator config validate
   navigator config validate --config /etc/navigator/navigator.yaml
-  navigator config validate --rails-root /path/to/rails/app`,
+  navigator config validate --root /path/to/rails/app`,
 	Run: func(cmd *cobra.Command, args []string) {
 		// Load configuration - flag binding should work with global Viper instance
 		cfg, err := LoadConfig(cfgFile)
@@ -47,8 +47,7 @@ func init() {
 	rootCmd.AddCommand(configCmd)
 	configCmd.AddCommand(configValidateCmd)
 
-	// Mark rails-root as required for config validate command
-	configValidateCmd.MarkPersistentFlagRequired("rails-root")
+	// No longer marking root as required since it has a default value
 }
 
 // validateConfig validates and displays the current configuration

internal/cli/root.go

@@ -46,15 +46,15 @@ func init() {
 	// Let individual commands initialize config as needed
 
 	// Global flags
-	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is navigator.yaml)")
+	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default: config/navigator.yml relative to root)")
 
 	// Server flags
 	rootCmd.PersistentFlags().String("listen", ":3000", "address to listen on")
 	rootCmd.PersistentFlags().String("url-prefix", "/showcase", "URL prefix to strip from requests")
 
 	// Rails flags
-	rootCmd.PersistentFlags().String("rails-root", "", "Rails application root directory (required)")
-	rootCmd.PersistentFlags().String("showcases", "config/tenant/showcases.yml", "path to showcases.yml relative to rails-root")
+	rootCmd.PersistentFlags().String("root", ".", "Application root directory (default: current directory)")
+	rootCmd.PersistentFlags().String("showcases", "config/tenant/showcases.yml", "path to showcases.yml relative to root")
 	rootCmd.PersistentFlags().String("db-path", "db", "database directory path")
 	rootCmd.PersistentFlags().String("storage", "storage", "storage directory path")
 
@@ -82,7 +82,7 @@ func bindFlags() {
 	viper.BindPFlag("server.url_prefix", rootCmd.PersistentFlags().Lookup("url-prefix"))
 
 	// Rails flags
-	viper.BindPFlag("rails.root", rootCmd.PersistentFlags().Lookup("rails-root"))
+	viper.BindPFlag("rails.root", rootCmd.PersistentFlags().Lookup("root"))
 	viper.BindPFlag("rails.showcases", rootCmd.PersistentFlags().Lookup("showcases"))
 	viper.BindPFlag("rails.db_path", rootCmd.PersistentFlags().Lookup("db-path"))
 	viper.BindPFlag("rails.storage", rootCmd.PersistentFlags().Lookup("storage"))