foxhunt/tli/CONFIG_FILE_SUPPORT.md

# TLI Configuration File Support

## Overview

TLI now supports configuration files at `~/.foxhunt/config.toml` for setting default values.

## Configuration Precedence

Settings are resolved in the following order (highest priority first):

1. **CLI arguments** - `--api-gateway-url`, `--log-level`, `--token-storage`
2. **Environment variables** - `API_GATEWAY_URL`, `TLI_LOG_LEVEL`, `TLI_TOKEN_STORAGE`
3. **Config file** - `~/.foxhunt/config.toml`
4. **Hardcoded defaults** - Built into the application

## Setup

### 1. Create Config Directory

```bash
mkdir -p ~/.foxhunt
```

### 2. Create Config File

Copy the example configuration:

```bash
cp tli/config.toml.example ~/.foxhunt/config.toml
```

Or create manually:

```bash
cat > ~/.foxhunt/config.toml << 'EOF'
# API Gateway URL (default: http://localhost:50051)
api_gateway_url = "http://localhost:50051"

# Log level: trace, debug, info, warn, error (default: info)
log_level = "info"

# Token storage: keyring, file (default: keyring)
token_storage = "keyring"
EOF
```

### 3. Edit Configuration

Edit `~/.foxhunt/config.toml` with your preferred settings:

```bash
nano ~/.foxhunt/config.toml
# or
vim ~/.foxhunt/config.toml
```

## Configuration Options

### api_gateway_url

- **Type**: String (URL)
- **Default**: `http://localhost:50051`
- **Description**: API Gateway endpoint for all TLI operations
- **Example**: `api_gateway_url = "https://api.foxhunt.example.com:50051"`

### log_level

- **Type**: String (enum)
- **Default**: `info`
- **Options**: `trace`, `debug`, `info`, `warn`, `error`
- **Description**: Controls verbosity of logging output
- **Example**: `log_level = "debug"`

### token_storage

- **Type**: String (enum)
- **Default**: `keyring`
- **Options**: `keyring`, `file`
- **Description**: Where to store authentication tokens
  - `keyring`: OS keyring (secure, recommended)
  - `file`: Plain text file (NOT SECURE, development only)
- **Example**: `token_storage = "keyring"`

## Usage Examples

### Example 1: Use Config File Defaults

```bash
# Uses settings from ~/.foxhunt/config.toml
tli dashboard
```

### Example 2: Override with CLI Arguments

```bash
# Override API Gateway URL from config
tli --api-gateway-url http://staging.example.com:50051 dashboard
```

### Example 3: Override with Environment Variables

```bash
# Override log level from config
TLI_LOG_LEVEL=debug tli dashboard
```

### Example 4: Mixed Precedence

```toml
# ~/.foxhunt/config.toml
api_gateway_url = "http://localhost:50051"
log_level = "info"
```

```bash
# CLI overrides config file log level
# Environment variable overrides config file URL
API_GATEWAY_URL=http://production.example.com:50051 \
tli --log-level debug dashboard

# Result:
# - api_gateway_url: http://production.example.com:50051 (from env var)
# - log_level: debug (from CLI arg)
# - token_storage: keyring (from config file default)
```

## Production Configuration

### Recommended Production Settings

```toml
# ~/.foxhunt/config.toml (production)

# Production API Gateway
api_gateway_url = "https://api.foxhunt.example.com:50051"

# Info level for production (warn/error for high volume)
log_level = "info"

# Always use keyring in production
token_storage = "keyring"
```

### Security Considerations

1. **Never commit** `~/.foxhunt/config.toml` to version control
2. **Always use** `keyring` token storage in production
3. **Use TLS** for production API Gateway URLs (https://)
4. **Restrict permissions** on config file:

```bash
chmod 600 ~/.foxhunt/config.toml
```

## Implementation Details

### Config Structure

```rust
// tli/src/config.rs
pub struct TliConfig {
    pub api_gateway_url: String,  // Default: "http://localhost:50051"
    pub log_level: String,         // Default: "info"
    pub token_storage: String,     // Default: "keyring"
}
```

### Loading Logic

```rust
// Load config from file (returns defaults if file doesn't exist)
let config = TliConfig::load().unwrap_or_default();

// Parse CLI args
let cli = Cli::parse();

// Merge: CLI args override config file
if cli.api_gateway_url == "http://localhost:50051" {
    cli.api_gateway_url = config.api_gateway_url;
}
```

### Config File Location

- **Linux/macOS**: `~/.foxhunt/config.toml` (e.g., `/home/user/.foxhunt/config.toml`)
- **Windows**: `%USERPROFILE%\.foxhunt\config.toml` (e.g., `C:\Users\user\.foxhunt\config.toml`)

## Troubleshooting

### Config File Not Found

If `~/.foxhunt/config.toml` doesn't exist, TLI will use hardcoded defaults. This is normal behavior.

### Invalid TOML Syntax

If the config file has syntax errors, TLI will return an error:

```
Error: Failed to parse config file
```

Fix the TOML syntax in `~/.foxhunt/config.toml` and try again.

### Verify Config Loading

Check which config values are being used:

```bash
tli dashboard
# Look for startup logs:
# TLI Client Configuration:
#   API Gateway: http://localhost:50051
#   Log Level: info
#   Token Storage: keyring
```

### Test Config File

Test that your config file parses correctly:

```bash
cargo test -p tli --lib config::tests
```

## Files Modified

### New Files

1. `/home/jgrusewski/Work/foxhunt/tli/src/config.rs` - Config module
2. `/home/jgrusewski/Work/foxhunt/tli/config.toml.example` - Example config file
3. `/home/jgrusewski/Work/foxhunt/tli/CONFIG_FILE_SUPPORT.md` - This documentation

### Modified Files

1. `/home/jgrusewski/Work/foxhunt/tli/Cargo.toml` - Added `toml = "0.8"`, `dirs = "5.0"`
2. `/home/jgrusewski/Work/foxhunt/tli/src/lib.rs` - Added `pub mod config;`
3. `/home/jgrusewski/Work/foxhunt/tli/src/main.rs` - Added config loading and merging logic

## Testing

### Unit Tests

```bash
# Run config module tests
cargo test -p tli --lib config::tests

# Output:
# running 4 tests
# test config::tests::test_default_config ... ok
# test config::tests::test_load_nonexistent_config ... ok
# test config::tests::test_serde_defaults ... ok
# test config::tests::test_config_serialization ... ok
```

### Manual Testing

```bash
# 1. Create test config
mkdir -p ~/.foxhunt
cat > ~/.foxhunt/config.toml << 'EOF'
api_gateway_url = "http://test.example.com:50051"
log_level = "debug"
token_storage = "keyring"
EOF

# 2. Test config loading (check startup logs)
cargo run -p tli dashboard

# 3. Test CLI override
cargo run -p tli --api-gateway-url http://override.example.com:50051 dashboard
```

## Dependencies Added

```toml
# tli/Cargo.toml
toml = "0.8"   # TOML parsing for config files
dirs = "5.0"   # Cross-platform directory access
```

## Backward Compatibility

- **No breaking changes**: If config file doesn't exist, defaults are used
- **Existing CLI behavior**: CLI arguments still work exactly as before
- **Environment variables**: Continue to work as before
- **Migration**: No migration needed - config file is optional

## Future Enhancements

Potential future additions (out of scope for this task):

- Config management commands (`tli config set`, `tli config show`)
- Config validation on save
- Config schema versioning
- Multiple config profiles (dev, staging, production)
- Config encryption for sensitive values