foxhunt/fxt/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

mkdir -p ~/.foxhunt

2. Create Config File

Copy the example configuration:

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

Or create manually:

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:

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

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

Example 2: Override with CLI Arguments

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

Example 3: Override with Environment Variables

# Override log level from config
TLI_LOG_LEVEL=debug tli dashboard

Example 4: Mixed Precedence

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

# 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

# ~/.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:

chmod 600 ~/.foxhunt/config.toml

Implementation Details

Config Structure

// 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

// 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:

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:

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

# 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

# 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

# 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