# Configuration Guide

Advanced configuration options and use cases for Grokkit.

## Table of Contents

- [Configuration Priority](#configuration-priority)
- [Environment Variables](#environment-variables)
- [Config File](#config-file)
- [Configuration Examples](#configuration-examples)
- [Advanced Use Cases](#advanced-use-cases)
- [Best Practices](#best-practices)

## Configuration Priority

Grokkit resolves configuration in this order (highest to lowest):

1. **CLI Flags** - `grokkit chat --model grok-4`
2. **Environment Variables** - `export XAI_API_KEY=...`
3. **Config File** - `~/.config/grokkit/config.toml`
4. **Defaults** - Hardcoded in application

**Example:**
```bash
# Config file says: default_model = "grok-4"
# Command uses:
grokkit chat -m grok-beta

# Result: Uses grok-beta (CLI flag wins)
```

## Environment Variables

### XAI_API_KEY (Required)

Your xAI API key.

```bash
# Set for current session
export XAI_API_KEY=sk-your-key-here

# Set permanently (bash)
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.bashrc
source ~/.bashrc

# Set permanently (zsh)
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.zshrc
source ~/.zshrc

# Verify (safely)
echo $XAI_API_KEY | sed 's/sk-.*$/sk-***/'
```

### Environment-based Config

You can also set config values via environment:

```bash
export GROKKIT_MODEL=grok-4
export GROKKIT_TEMPERATURE=0.8
export GROKKIT_LOG_LEVEL=debug
```

Viper (the config library) automatically reads these with `AutomaticEnv()`.

## Config File

### Location

Default location: `~/.config/grokkit/config.toml`

Custom location via Viper (not currently exposed, but easy to add).

### Full Configuration

```toml
# ~/.config/grokkit/config.toml

# ===== Model Settings =====
default_model = "grok-4"           # Model to use by default
temperature = 0.7                  # Creativity (0.0 = deterministic, 1.0 = creative)
timeout = 60                       # API timeout in seconds

# ===== Logging Settings =====
log_level = "info"                 # debug | info | warn | error

# ===== Model Aliases =====
# Create shortcuts for frequently used models
[aliases]
beta = "grok-beta-2"               # grokkit chat -m beta
fast = "grok-4-mini"               # grokkit chat -m fast
creative = "grok-4"                # grokkit chat -m creative

# ===== Chat Settings =====
[chat]
history_file = "~/.config/grokkit/chat_history.json"   # Custom history location
# max_history = 100                # Future: Limit history size
```

### Minimal Configuration

```toml
# Just the essentials
default_model = "grok-4"
temperature = 0.7
```

### Create Config File

```bash
# Create directory
mkdir -p ~/.config/grokkit

# Create config with defaults
cat > ~/.config/grokkit/config.toml <<'EOF'
default_model = "grok-4"
temperature = 0.7
timeout = 60
log_level = "info"

[aliases]
beta = "grok-beta-2"
fast = "grok-4-mini"

[chat]
history_file = "~/.config/grokkit/chat_history.json"
EOF

# Verify
cat ~/.config/grokkit/config.toml
```

## Configuration Examples

### Example 1: Development Environment

Fast iteration, detailed logs, shorter timeouts.

```toml
# ~/.config/grokkit/config.toml
default_model = "grok-4-mini"      # Fast model for quick iterations
temperature = 0.5                  # More predictable responses
timeout = 30                       # Fail fast
log_level = "debug"                # Detailed logging

[aliases]
dev = "grok-4-mini"
prod = "grok-4"
```

```bash
# Usage
grokkit chat -m dev                # Fast model
grokkit review --debug             # With detailed logs
```

### Example 2: Production Environment

Reliable, balanced settings.

```toml
# ~/.config/grokkit/config.toml
default_model = "grok-4"
temperature = 0.7
timeout = 120                      # Longer timeout for reliability
log_level = "warn"                 # Only warnings and errors

[aliases]
prod = "grok-4"
fast = "grok-4-mini"
```

### Example 3: Creative Writing

Higher temperature for more creative responses.

```toml
# ~/.config/grokkit/config-creative.toml
default_model = "grok-4"
temperature = 0.9                  # More creative
timeout = 90

log_level = "info"

[aliases]
creative = "grok-4"
```

```bash
# Use with environment variable pointing to alt config
# (requires code modification to support)
grokkit chat  # Uses high creativity settings
```

### Example 4: Team Settings

Standardized settings for team consistency.

```toml
# team-shared-config.toml
default_model = "grok-4"
temperature = 0.7
timeout = 60
log_level = "info"

[aliases]
review = "grok-4"                  # For code reviews
commit = "grok-4-mini"             # For commit messages
docs = "grok-4"                    # For documentation

[chat]
# Don't save history in team environment
# (requires code modification)
save_history = false
```

```bash
# Usage
grokkit review -m review           # Explicit model for reviews
grokkit commit -m commit           # Fast model for commits
```

### Example 5: Cost Optimization

Minimize API costs while maintaining functionality.

```toml
# ~/.config/grokkit/config.toml
default_model = "grok-4-mini"      # Cheaper model
temperature = 0.5                  # More deterministic = fewer tokens
timeout = 45

[aliases]
cheap = "grok-4-mini"
expensive = "grok-4"
```

```bash
# Use cheap model by default
grokkit chat

# Use expensive model only when needed
grokkit edit complex.go "major refactor" -m expensive
```

## Advanced Use Cases

### Multiple Profiles

Create different config files for different use cases.

```bash
# Directory structure
~/.config/grokkit/
├── config.toml              # Default
├── config-dev.toml          # Development
├── config-creative.toml     # Creative work
└── config-production.toml   # Production use

# Symlink to switch profiles
ln -sf ~/.config/grokkit/config-dev.toml ~/.config/grokkit/config.toml
```

### Project-specific Settings

Place `.env` file in project root:

```bash
# /path/to/project/.env
export XAI_API_KEY=sk-project-specific-key
export GROKKIT_MODEL=grok-4-mini
export GROKKIT_LOG_LEVEL=debug

# Load in shell
source .env
grokkit chat  # Uses project settings
```

### Per-command Defaults

Use aliases for command-specific models:

```toml
[aliases]
chat = "grok-4"                    # Best quality for chat
edit = "grok-4"                    # Precision for edits
review = "grok-4"                  # Thorough reviews
commit = "grok-4-mini"             # Fast for simple commits
history = "grok-4-mini"            # Fast summaries
```

```bash
# Manually specify when calling
grokkit chat -m chat
grokkit edit file.go "task" -m edit
```

### Custom History Location

Useful for separating concerns or compliance:

```toml
[chat]
# Separate histories per project
history_file = "~/projects/current/.grokkit-history.json"

# Or don't save history at all
history_file = "/dev/null"
```

### Network-restricted Environments

Adjust timeouts for slow networks:

```toml
timeout = 300                      # 5 minutes for slow connections
```

Or use proxy settings:

```bash
export HTTP_PROXY=http://proxy.corp.com:8080
export HTTPS_PROXY=http://proxy.corp.com:8080
grokkit chat
```

## Best Practices

### 1. Keep API Keys Secure

**❌ Don't:**
```toml
# config.toml
api_key = "sk-123..."  # ❌ DON'T put in config file
```

**✅ Do:**
```bash
# Use environment variables
export XAI_API_KEY=sk-...

# Or use a secrets manager
export XAI_API_KEY=$(vault kv get -field=key secret/grokkit)
```

### 2. Use Aliases for Workflows

```toml
[aliases]
# Descriptive names
review-critical = "grok-4"         # Thorough for critical code
review-routine = "grok-4-mini"     # Fast for routine changes
refactor = "grok-4"                # Best model for complex refactoring
```

### 3. Adjust Temperature by Use Case

| Use Case | Temperature | Reason |
|----------|-------------|--------|
| Code generation | 0.3 - 0.5 | Predictable, correct code |
| Code review | 0.5 - 0.7 | Balanced analysis |
| Commit messages | 0.5 | Consistent format |
| Documentation | 0.7 | Clear but varied language |
| Creative writing | 0.8 - 1.0 | More variety |
| Debugging | 0.3 | Precise analysis |

### 4. Manage Log Levels

| Environment | Log Level | Reason |
|-------------|-----------|--------|
| Development | `debug` | See everything |
| Staging | `info` | Track operations |
| Production | `warn` | Errors and warnings only |
| CI/CD | `error` | Failures only |

### 5. Set Appropriate Timeouts

| Network | Timeout | Reason |
|---------|---------|--------|
| Fast (LAN) | 30s | Fail fast |
| Normal (broadband) | 60s | Balanced |
| Slow (mobile/VPN) | 120s | Allow completion |
| Restricted (corporate) | 180s | Account for proxies |

### 6. Version Control Config

```bash
# Add template to repo (without secrets)
cat > .grokkit-config.template.toml <<'EOF'
default_model = "grok-4"
temperature = 0.7
timeout = 60
log_level = "info"

[aliases]
dev = "grok-4-mini"
prod = "grok-4"
EOF

# .gitignore
echo "config.toml" >> .gitignore   # Don't commit actual config
```

### 7. Document Team Conventions

```toml
# team-config.toml - Team standard configuration
# Copy this file to ~/.config/grokkit/config.toml

default_model = "grok-4"
temperature = 0.7                  # Don't change without team discussion

[aliases]
# Use these for consistency
code-review = "grok-4"
quick-commit = "grok-4-mini"
```

## Configuration Schema

Reference for all available options:

```toml
# String: Model identifier
default_model = "grok-4"

# Float: 0.0-1.0 (creativity)
temperature = 0.7

# Integer: Seconds (API timeout)
timeout = 60

# String: "debug" | "info" | "warn" | "error"
log_level = "info"

# Map of string to string
[aliases]
alias_name = "actual-model-name"

# Chat-specific settings
[chat]
history_file = "/path/to/history.json"
```

## Troubleshooting Config

### Check Current Config

```bash
# View config file
cat ~/.config/grokkit/config.toml

# Test with debug mode (shows resolved config)
grokkit chat --debug 2>&1 | head -20
```

### Validate TOML Syntax

```bash
# Online validator
# https://www.toml-lint.com/

# Or install tomll
go install github.com/pelletier/go-toml/v2/cmd/tomll@latest
tomll ~/.config/grokkit/config.toml
```

### Reset to Defaults

```bash
# Backup current config
mv ~/.config/grokkit/config.toml ~/.config/grokkit/config.toml.backup

# App will use defaults
grokkit chat

# Restore if needed
mv ~/.config/grokkit/config.toml.backup ~/.config/grokkit/config.toml
```

---

**See also:**
- [Troubleshooting Guide](TROUBLESHOOTING.md)
- [Architecture Overview](ARCHITECTURE.md)