# Environment Variables

Complete reference for environment variables that configure Gonzo's behavior. Environment variables provide a convenient way to configure Gonzo without command-line flags or config files.

### Overview

Environment variables are useful for:

* **Container deployments**: Configure via Docker/Kubernetes env vars
* **CI/CD pipelines**: Set configuration in pipeline env
* **Quick testing**: Temporary configuration without files
* **System-wide defaults**: Set in shell profile

**Priority Order** (highest to lowest):

1. Command line flags
2. **Environment variables**
3. Configuration file
4. Default values

### Gonzo-Specific Variables

#### Input Configuration

**`GONZO_FILES`**

**Type**: String (comma-separated paths)\
**Default**: `""` (uses stdin)\
**Description**: Log files to read

```bash
# Single file
export GONZO_FILES="/var/log/app.log"

# Multiple files
export GONZO_FILES="/var/log/app.log,/var/log/error.log"

# Glob pattern (quote to prevent shell expansion)
export GONZO_FILES="/var/log/*.log"
```

**Example**:

```bash
export GONZO_SKIN="dracula"
```

**Built-in skins**:

* Dark: `default`, `controltheory-dark`, `dracula`, `gruvbox`, `monokai`, `nord`, `solarized-dark`
* Light: `controltheory-light`, `github-light`, `solarized-light`, `vs-code-light`, `spring`

#### Advanced Settings

**`GONZO_TEST_MODE`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Run without TTY (for testing)

```bash
export GONZO_TEST_MODE="true"
```

**Note**: For automated testing only, not for normal use.

### AI Provider Variables

These configure AI provider connections:

#### OpenAI API

**`OPENAI_API_KEY`**

**Type**: String (API key)\
**Required for**: OpenAI API access\
**Description**: Your OpenAI API key

```bash
export OPENAI_API_KEY="sk-your-actual-api-key-here"
```

**Get your key**: <https://platform.openai.com/api-keys>

**`OPENAI_API_BASE`**

**Type**: String (URL)\
**Default**: `https://api.openai.com/v1`\
**Description**: API endpoint (for custom providers)

```bash
# For OpenAI (default, can omit)
export OPENAI_API_BASE="https://api.openai.com/v1"

# For LM Studio (MUST include /v1)
export OPENAI_API_BASE="http://localhost:1234/v1"

# For Ollama (NO /v1 suffix)
export OPENAI_API_BASE="http://localhost:11434"

# For custom OpenAI-compatible API
export OPENAI_API_BASE="https://your-api.com/v1"
```

**Important Notes**:

* LM Studio: **MUST** include `/v1` suffix
* Ollama: **MUST NOT** include `/v1` suffix
* Most others: Include `/v1` suffix

#### OpenAI Configuration

**`OPENAI_ORGANIZATION`**

**Type**: String (organization ID)\
**Optional**: For multi-org accounts\
**Description**: OpenAI organization ID

```bash
export OPENAI_ORGANIZATION="org-your-org-id"
```

### System Variables

These system-wide variables affect Gonzo:

#### Terminal Configuration

**`TERM`**

**Type**: String\
**Default**: Set by terminal\
**Description**: Terminal type

```bash
export TERM="xterm-256color"
```

**Recommended values**:

* `xterm-256color` - 256 color support
* `screen-256color` - For tmux/screen
* `alacritty` - For Alacritty terminal

**`LANG` / `LC_ALL`**

**Type**: String (locale)\
**Default**: System locale\
**Description**: Character encoding

```bash
export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"
```

**Note**: UTF-8 recommended for proper display.

#### Display Control

**`NO_COLOR`**

**Type**: Boolean (any value)\
**Default**: Not set\
**Description**: Disable color output

```bash
# Disable colors
export NO_COLOR=1

# Re-enable colors
unset NO_COLOR
```

**Note**: Setting to any value disables colors.

### Complete Configuration Examples

#### Basic Development Setup

```bash
# ~/.bashrc or ~/.zshrc
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="dracula"
export OPENAI_API_KEY="sk-your-key-here"
```

#### Production Monitoring

```bash
# Production server configuration
export GONZO_FILES="/var/log/production/*.log"
export GONZO_FOLLOW="true"
export GONZO_UPDATE_INTERVAL="2s"
export GONZO_LOG_BUFFER="5000"
export GONZO_MEMORY_SIZE="20000"
export GONZO_SKIN="default"
export OPENAI_API_KEY="sk-prod-key"
```

#### OTLP Receiver

```bash
# OTLP log receiver setup
export GONZO_OTLP_ENABLED="true"
export GONZO_OTLP_GRPC_PORT="4317"
export GONZO_OTLP_HTTP_PORT="4318"
export GONZO_UPDATE_INTERVAL="1s"
export GONZO_LOG_BUFFER="2000"
```

#### Local AI with Ollama

```bash
# Using Ollama for AI features
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
export GONZO_AI_MODEL="llama3"
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
```

#### Local AI with LM Studio

```bash
# Using LM Studio for AI features
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"  # Note: /v1 required
export GONZO_AI_MODEL=""  # Auto-select
export GONZO_FILES="/var/log/app.log"
```

### Docker/Container Usage

#### Docker Compose

```yaml
# docker-compose.yml
services:
  gonzo:
    image: gonzo:latest
    environment:
      - GONZO_OTLP_ENABLED=true
      - GONZO_OTLP_GRPC_PORT=4317
      - GONZO_OTLP_HTTP_PORT=4318
      - GONZO_LOG_BUFFER=2000
      - GONZO_UPDATE_INTERVAL=2s
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    ports:
      - "4317:4317"
      - "4318:4318"
```

#### Docker Run

```bash
docker run -e GONZO_OTLP_ENABLED=true \
           -e GONZO_OTLP_GRPC_PORT=4317 \
           -e GONZO_OTLP_HTTP_PORT=4318 \
           -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
           -p 4317:4317 \
           -p 4318:4318 \
           gonzo:latest
```

#### Kubernetes

```yaml
# kubernetes-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gonzo
spec:
  template:
    spec:
      containers:
      - name: gonzo
        image: gonzo:latest
        env:
        - name: GONZO_OTLP_ENABLED
          value: "true"
        - name: GONZO_OTLP_GRPC_PORT
          value: "4317"
        - name: GONZO_OTLP_HTTP_PORT
          value: "4318"
        - name: GONZO_LOG_BUFFER
          value: "2000"
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: gonzo-secrets
              key: openai-api-key
        ports:
        - containerPort: 4317
        - containerPort: 4318
```

### Shell Profile Setup

#### Bash (\~/.bashrc)

```bash
# Gonzo Configuration
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="dracula"
export GONZO_UPDATE_INTERVAL="2s"

# OpenAI Configuration
export OPENAI_API_KEY="sk-your-key-here"

# Optional: Add completion
if [ -f ~/.gonzo-completion.bash ]; then
  source ~/.gonzo-completion.bash
fi
```

#### Zsh (\~/.zshrc)

```zsh
# Gonzo Configuration
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="nord"
export GONZO_UPDATE_INTERVAL="2s"

# OpenAI Configuration
export OPENAI_API_KEY="sk-your-key-here"

# Optional: Add completion
if [ -f ~/.gonzo-completion.zsh ]; then
  source ~/.gonzo-completion.zsh
fi
```

#### Fish (\~/.config/fish/config.fish)

```fish
# Gonzo Configuration
set -x GONZO_FILES "/var/log/app.log"
set -x GONZO_FOLLOW "true"
set -x GONZO_SKIN "monokai"
set -x GONZO_UPDATE_INTERVAL "2s"

# OpenAI Configuration
set -x OPENAI_API_KEY "sk-your-key-here"
```

### Debugging Environment Variables

#### View All Gonzo Variables

```bash
# Show all GONZO_* variables
env | grep GONZO

# Show all OpenAI variables
env | grep OPENAI

# Show all relevant variables
env | grep -E '(GONZO|OPENAI|TERM|LANG)'
```

#### Test Configuration

```bash
# Print configuration without starting Gonzo
gonzo --help

# Or check specific values
echo "Files: $GONZO_FILES"
echo "Follow: $GONZO_FOLLOW"
echo "Interval: $GONZO_UPDATE_INTERVAL"
echo "API Key: ${OPENAI_API_KEY:0:10}..."  # Show only first 10 chars
```

#### Clear All Settings

```bash
# Unset all Gonzo variables
unset GONZO_FILES
unset GONZO_FOLLOW
unset GONZO_UPDATE_INTERVAL
unset GONZO_LOG_BUFFER
unset GONZO_MEMORY_SIZE
unset GONZO_AI_MODEL
unset GONZO_OTLP_ENABLED
unset GONZO_OTLP_GRPC_PORT
unset GONZO_OTLP_HTTP_PORT
unset GONZO_SKIN

# Unset OpenAI variables
unset OPENAI_API_KEY
unset OPENAI_API_BASE
```

### Precedence Examples

Understanding how different configuration methods interact:

#### Example 1: Command Line Overrides Env Var

```bash
export GONZO_UPDATE_INTERVAL="5s"
gonzo --update-interval=1s  # Uses 1s, not 5s
```

#### Example 2: Env Var Overrides Config File

```yaml
# config.yml has: update-interval: 10s
```

```bash
export GONZO_UPDATE_INTERVAL="2s"
gonzo --config=config.yml  # Uses 2s, not 10s
```

#### Example 3: Full Precedence Chain

```yaml
# config.yml
update-interval: 10s
```

```bash
export GONZO_UPDATE_INTERVAL="5s"
gonzo --config=config.yml --update-interval=1s
# Result: Uses 1s (flag > env > config)
```

### Security Considerations

#### API Keys

**Never commit API keys**:

```bash
# ❌ BAD - Don't commit to version control
export OPENAI_API_KEY="sk-actual-key"

# ✅ GOOD - Use secrets management
export OPENAI_API_KEY="${OPENAI_KEY_FROM_VAULT}"

# ✅ GOOD - Read from secure file
export OPENAI_API_KEY=$(cat ~/.secrets/openai_key)
```

**Use environment-specific keys**:

```bash
# Development
export OPENAI_API_KEY="sk-dev-key"

# Production
export OPENAI_API_KEY="sk-prod-key"
```

#### File Permissions

Protect your shell profile:

```bash
chmod 600 ~/.bashrc
chmod 600 ~/.zshrc
```

#### Kubernetes Secrets

Store sensitive values in secrets:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: gonzo-secrets
type: Opaque
stringData:
  openai-api-key: "sk-your-key-here"
```

### Troubleshooting

#### Variable Not Applied

**Check if set**:

```bash
echo $GONZO_FILES
# If empty, not set
```

**Check for typos**:

```bash
# Wrong
export GONZO_FILE="/var/log/app.log"  # Missing 'S'

# Correct
export GONZO_FILES="/var/log/app.log"
```

**Check for overrides**:

```bash
# Command line flag overrides env var
gonzo -f other.log  # Ignores GONZO_FILES
```

#### AI Not Working

**Check API key**:

```bash
echo $OPENAI_API_KEY
# Should show your key (sk-...)
```

**Check API base**:

```bash
echo $OPENAI_API_BASE
# Should be correct for your provider
```

**Test connectivity**:

```bash
# For OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# For LM Studio
curl http://localhost:1234/v1/models

# For Ollama
curl http://localhost:11434/api/tags
```

#### OTLP Receiver Not Starting

**Check if enabled**:

```bash
echo $GONZO_OTLP_ENABLED
# Should be "true"
```

**Check port conflicts**:

```bash
# Check if ports are free
lsof -i :4317
lsof -i :4318
```

### Best Practices

1. **Use shell profiles**: Set persistent defaults in `~/.bashrc` or `~/.zshrc`
2. **Separate environments**: Use different values for dev/prod
3. **Secure API keys**: Never commit keys to version control
4. **Document setup**: Comment your environment configuration
5. **Test changes**: Verify variables are applied correctly
6. **Use defaults**: Only override what you need to change

### Related Documentation

* **Configuration Schema** - Configuration file reference
* **CLI Reference** - Command line options
* **AI Integration** - AI provider setup

{% hint style="info" %}
**Tip**: Use `env | grep GONZO` to quickly see all your current Gonzo environment settings.
{% endhint %}

{% hint style="warning" %}
**Security**: Never expose API keys in logs, screenshots, or public repositories. Use environment variables or secrets management.
{% endhint %}

\_FILES="/var/log/nginx/access.log,/var/log/nginx/error.log" gonzo \`\`\`

**`GONZO_FOLLOW`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Follow log files in real-time

```bash
export GONZO_FOLLOW="true"
```

**Example**:

```bash
export GONZO_FOLLOW="true"
export GONZO_FILES="/var/log/app.log"
gonzo
```

#### Performance Settings

**`GONZO_UPDATE_INTERVAL`**

**Type**: Duration string\
**Default**: `"1s"`\
**Valid values**: Go duration format (e.g., `500ms`, `2s`, `5s`)\
**Description**: Dashboard update frequency

```bash
export GONZO_UPDATE_INTERVAL="2s"
```

**Common values**:

* `"500ms"` - Very responsive
* `"1s"` - Default, good balance
* `"2s"` - Reduced CPU usage
* `"5s"` - Low resource usage

**`GONZO_LOG_BUFFER`**

**Type**: Integer\
**Default**: `1000`\
**Valid range**: `1` to `100000`\
**Description**: Maximum log entries in buffer

```bash
export GONZO_LOG_BUFFER="2000"
```

**Guidelines**:

* **Low volume** (`<100 logs/sec`): 500-1000
* **Medium volume** (`100-1000 logs/sec`): 1000-5000
* **High volume** (`>1000 logs/sec`): 5000-10000

**`GONZO_MEMORY_SIZE`**

**Type**: Integer\
**Default**: `10000`\
**Valid range**: `100` to `1000000`\
**Description**: Maximum words tracked for frequency analysis

```bash
export GONZO_MEMORY_SIZE="15000"
```

**Guidelines**:

* **Minimal**: 5000
* **Standard**: 10000 (default)
* **Extended**: 15000-20000
* **Maximum**: 50000+

#### AI Configuration

**`GONZO_AI_MODEL`**

**Type**: String\
**Default**: `""` (auto-select)\
**Description**: AI model for log analysis

```bash
# Auto-select best available (recommended)
export GONZO_AI_MODEL=""

# OpenAI models
export GONZO_AI_MODEL="gpt-4"
export GONZO_AI_MODEL="gpt-3.5-turbo"

# Ollama models
export GONZO_AI_MODEL="llama3"
export GONZO_AI_MODEL="mistral"

# LM Studio models
export GONZO_AI_MODEL="openai/gpt-oss-120b"
```

#### OTLP Receiver

**`GONZO_OTLP_ENABLED`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Enable OTLP log receiver

```bash
export GONZO_OTLP_ENABLED="true"
```

**`GONZO_OTLP_GRPC_PORT`**

**Type**: Integer\
**Default**: `4317`\
**Valid range**: `1024` to `65535`\
**Description**: gRPC receiver port

```bash
export GONZO_OTLP_GRPC_PORT="4317"
```

**`GONZO_OTLP_HTTP_PORT`**

**Type**: Integer\
**Default**: `4318`\
**Valid range**: `1024` to `65535`\
**Description**: HTTP receiver port

```bash
export GONZO_OTLP_HTTP_PORT="4318"
```

#### Display Settings

**`GONZO_SKIN`**

**Type**: String\
**Default**: `"default"`\
**Valid values**: Any installed skin name\
**Description**: Color scheme/theme

```bash
export GONZO
```