# Command Line Reference

Complete reference for all Gonzo command-line flags and options. From basic file input to advanced performance tuning, this guide covers every CLI option available.

{% hint style="info" %}
**Quick Reference:** Use `gonzo --help` or `gonzo -h` to see a summary of all available flags at any time.
{% endhint %}

### Command Syntax

```bash
gonzo [flags] [command]

# Basic usage
gonzo -f application.log
gonzo -f logs/*.log --follow

# With multiple options
gonzo -f app.log --follow --log-buffer=5000 --ai-model="gpt-4"

# Using configuration file
gonzo --config ~/.config/gonzo/config.yml

# Piping input
cat logs.log | gonzo
kubectl logs -f pod/my-app | gonzo
```

### Core Flags

#### File Input

**Specify log files or patterns to analyze:**

| Flag       | Short | Type    | Description                  | Example                     |
| ---------- | ----- | ------- | ---------------------------- | --------------------------- |
| `--file`   | `-f`  | string  | File or glob pattern to read | `gonzo -f app.log`          |
| `--follow` |       | boolean | Follow file like `tail -f`   | `gonzo -f app.log --follow` |

**Examples:**

```bash
# Single file
gonzo -f application.log

# Multiple files
gonzo -f api.log -f db.log -f cache.log

# Glob patterns (use quotes)
gonzo -f "/var/log/*.log"
gonzo -f "/var/log/app-*.log"

# Follow mode (real-time)
gonzo -f /var/log/app.log --follow

# Multiple files with follow
gonzo -f "/var/log/*.log" --follow

# Combine specific files and patterns
gonzo -f app.log -f "/var/log/nginx/*.log" --follow
```

**Notes:**

* Can be specified multiple times for multiple sources
* Glob patterns must be quoted to prevent shell expansion
* `--follow` works like `tail -f` for real-time monitoring
* Without `--follow`, Gonzo reads entire file and exits

#### Configuration

**Specify configuration files and options:**

| Flag       | Short | Type   | Description                | Example                   |
| ---------- | ----- | ------ | -------------------------- | ------------------------- |
| `--config` |       | string | Path to configuration file | `gonzo --config prod.yml` |

**Examples:**

```bash
# Use specific config file
gonzo --config ~/.config/gonzo/prod.yml

# Relative path
gonzo --config ./my-config.yml

# Absolute path
gonzo --config /etc/gonzo/system.yml

# CLI flags override config file settings
gonzo --config prod.yml --log-buffer=10000
```

**Config File Search Path:**

1. Path specified with `--config` flag
2. `./config.yml` (current directory)
3. `~/.config/gonzo/config.yml` (user config)
4. `/etc/gonzo/config.yml` (system config)

### Performance Flags

#### Buffer and Memory

**Control memory usage and buffer sizes:**

| Flag                | Short | Type     | Default | Description                 |
| ------------------- | ----- | -------- | ------- | --------------------------- |
| `--log-buffer`      | `-b`  | int      | 1000    | Maximum log entries to keep |
| `--memory-size`     | `-m`  | int      | 10000   | Maximum frequency entries   |
| `--update-interval` | `-u`  | duration | 1s      | Dashboard update interval   |

**Examples:**

```bash
# Increase buffer for more history
gonzo -f app.log --log-buffer=10000

# Reduce memory for constrained systems
gonzo -f app.log --log-buffer=500 --memory-size=2000

# Slower updates for better performance
gonzo -f busy.log --update-interval=5s

# High-performance setup
gonzo -f logs.log \
      --log-buffer=20000 \
      --memory-size=50000 \
      --update-interval=10s

# Memory-constrained setup
gonzo -f logs.log \
      --log-buffer=1000 \
      --memory-size=5000 \
      --update-interval=5s
```

**Guidelines:**

{% tabs %}
{% tab title="Default Settings" %}

```bash
# Good for most use cases
--log-buffer=1000      # ~1-2 minutes of history
--memory-size=10000    # Standard pattern tracking
--update-interval=1s   # Responsive updates
```

{% endtab %}

{% tab title="High Volume" %}

```bash
# For logs with >100 entries/second
--log-buffer=20000     # Larger buffer for throughput
--memory-size=100000   # Extensive pattern tracking
--update-interval=10s  # Reduce update overhead
```

{% endtab %}

{% tab title="Low Memory" %}

```bash
# For systems with <4GB RAM
--log-buffer=500       # Minimal buffer
--memory-size=2000     # Reduced tracking
--update-interval=5s   # Less frequent updates
```

{% endtab %}

{% tab title="Development" %}

```bash
# For fast development iteration
--log-buffer=2000      # Moderate history
--memory-size=10000    # Standard tracking
--update-interval=1s   # Fast updates
```

{% endtab %}
{% endtabs %}

### AI Configuration Flags

#### AI Model Selection

**Configure AI analysis features:**

| Flag         | Type   | Default | Description                  |
| ------------ | ------ | ------- | ---------------------------- |
| `--ai-model` | string | auto    | AI model to use for analysis |

**Examples:**

```bash
# Use specific model
gonzo -f app.log --ai-model="gpt-4"
gonzo -f app.log --ai-model="gpt-3.5-turbo"
gonzo -f app.log --ai-model="llama3"

# Auto-select best available (default)
gonzo -f app.log

# Cost-effective for development
gonzo -f debug.log --ai-model="gpt-3.5-turbo"

# Best quality for production incidents
gonzo -f incident.log --ai-model="gpt-4"

# Local AI for privacy
export OPENAI_API_BASE="http://localhost:11434"
gonzo -f sensitive.log --ai-model="llama3"
```

**Supported Models:**

* **OpenAI:** `gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo`, `gpt-3.5-turbo-16k`
* **Ollama:** `llama3`, `llama3:70b`, `mistral`, `mixtral`, `codellama`
* **LM Studio:** Any model loaded in LM Studio
* **Auto:** Automatically selects best available model

**AI Environment Variables:**

```bash
# OpenAI
export OPENAI_API_KEY="sk-your-key"
export OPENAI_API_BASE="https://api.openai.com/v1"

# Ollama
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"

# LM Studio
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"
```

### OTLP Flags

#### OpenTelemetry Protocol

**Configure OTLP log receiver:**

| Flag               | Type    | Default | Description          |
| ------------------ | ------- | ------- | -------------------- |
| `--otlp-enabled`   | boolean | false   | Enable OTLP receiver |
| `--otlp-grpc-port` | int     | 4317    | gRPC endpoint port   |
| `--otlp-http-port` | int     | 4318    | HTTP endpoint port   |

**Examples:**

```bash
# Enable OTLP with default ports
gonzo --otlp-enabled

# Custom ports
gonzo --otlp-enabled \
      --otlp-grpc-port=5317 \
      --otlp-http-port=5318

# OTLP + file backup
gonzo --otlp-enabled -f backup.log --follow

# OTLP with specific configuration
gonzo --otlp-enabled \
      --log-buffer=20000 \
      --update-interval=5s
```

**OTLP Endpoints:**

* **gRPC:** `localhost:4317` (or custom port)
* **HTTP:** `http://localhost:4318/v1/logs` (or custom port)

### Display and Output Flags

#### Interface Customization

**Control display appearance and behavior:**

| Flag              | Short | Type    | Default | Description               |
| ----------------- | ----- | ------- | ------- | ------------------------- |
| `--no-color`      |       | boolean | false   | Disable color output      |
| `-v`, `--version` |       | boolean | false   | Print version information |
| `-h`, `--help`    |       | boolean | false   | Show help message         |

**Examples:**

```bash
# Disable colors (for logging to files)
gonzo -f app.log --no-color > output.txt

# Show version
gonzo --version
gonzo -v

# Show help
gonzo --help
gonzo -h

# Quiet mode (minimal output)
gonzo -f app.log --quiet

# Verbose mode (detailed output)
gonzo -f app.log --verbose
```

### Development and Testing Flags

#### Testing and Debugging

**Options for development and CI/CD:**

| Flag           | Short | Type    | Default | Description                                   |
| -------------- | ----- | ------- | ------- | --------------------------------------------- |
| `--test-mode`  | `-t`  | boolean | false   | Run without TTY for testing                   |
| `--verbose`    |       | boolean | false   | Enable verbose output                         |
| `--dry-run`    |       | boolean | false   | Show config without running                   |
| `--stop-words` |       | strings | \[]     | Additional stop words to filter from analysis |

**Examples:**

```bash
# Test mode (CI/CD friendly)
gonzo -f build.log --test-mode

# Verbose output for debugging
gonzo -f app.log --verbose

# Dry run to validate configuration
gonzo --config prod.yml --dry-run

# Add custom stop words (single)
gonzo -f app.log --stop-words="debug"

# Add multiple stop words
gonzo -f app.log --stop-words="debug" --stop-words="info" --stop-words="warning"

# Stop words in comma-separated format
gonzo -f app.log --stop-words="debug,info,warning"

# Combination for troubleshooting
gonzo -f app.log --verbose --test-mode
```

**Test Mode Features:**

```bash
# Test mode provides CI/CD-friendly output
gonzo --test-mode -f build.log

# Output example:
# 📊 Test Mode Results:
# 
# Total lines: 3
# Unique words: 6
# Unique phrases: 12
# Attribute keys: 0
# 
# Test completed successfully - no crashes!
# Press 'q' to quit or wait 2 seconds for auto-exit.

# Exit code indicates success/failure
if gonzo --test-mode -f build.log; then
    echo "Log analysis passed"
else
    echo "Log analysis failed"
fi
```

**Stop Words Usage:**

```bash
# Filter common log terms
gonzo -f app.log --stop-words="log,message,error,warning,info,debug"

# Filter framework noise
gonzo -f app.log --stop-words="springframework,hibernate,slf4j"

# Filter HTTP terms from web logs
gonzo -f access.log --stop-words="GET,POST,HTTP,status"

# Combine with other options
gonzo -f app.log --follow --stop-words="debug,trace" --ai-model="gpt-4"
```

**Use Cases:**

{% tabs %}
{% tab title="CI/CD Integration" %}

```bash
# Non-interactive mode for automation
build-command 2>&1 | gonzo --test-mode

# Exit code based analysis
gonzo -f build.log --test-mode
if [ $? -ne 0 ]; then
    echo "Build analysis found issues"
fi
```

{% endtab %}

{% tab title="Configuration Validation" %}

```bash
# Validate config file syntax
gonzo --config myconfig.yml --dry-run

# Check what settings would be used
gonzo --config myconfig.yml --show-config

# Debug configuration loading
gonzo --config myconfig.yml --verbose
```

{% endtab %}

{% tab title="Development Testing" %}

```bash
# Test with sample data
echo '{"level":"error","message":"test"}' | gonzo --test-mode

# Verbose output for debugging
gonzo -f test.log --verbose

# Profile performance
time gonzo -f large.log --test-mode
```

{% endtab %}
{% endtabs %}

### Complete Flag Reference Table

#### All Flags Alphabetically

| Flag                | Short | Type     | Default | Description                   |
| ------------------- | ----- | -------- | ------- | ----------------------------- |
| `--ai-model`        |       | string   | auto    | AI model for analysis         |
| `--config`          |       | string   |         | Configuration file path       |
| `--dry-run`         |       | boolean  | false   | Show config without running   |
| `--file`            | `-f`  | string   |         | File or glob pattern to read  |
| `--follow`          |       | boolean  | false   | Follow file like `tail -f`    |
| `--help`            | `-h`  | boolean  | false   | Show help message             |
| `--log-buffer`      | `-b`  | int      | 1000    | Maximum log entries to keep   |
| `--memory-size`     | `-m`  | int      | 10000   | Maximum frequency entries     |
| `--no-color`        |       | boolean  | false   | Disable color output          |
| `--otlp-enabled`    |       | boolean  | false   | Enable OTLP receiver          |
| `--otlp-grpc-port`  |       | int      | 4317    | OTLP gRPC port                |
| `--otlp-http-port`  |       | int      | 4318    | OTLP HTTP port                |
| `--quiet`           |       | boolean  | false   | Suppress non-essential output |
| `--show-config`     |       | boolean  | false   | Display current configuration |
| `--test-mode`       | `-t`  | boolean  | false   | Run without TTY               |
| `--update-interval` | `-u`  | duration | 1s      | Dashboard update interval     |
| `--verbose`         |       | boolean  | false   | Enable verbose output         |
| `--version`         | `-v`  | boolean  | false   | Print version information     |

### Common Command Patterns

#### Development Workflows

```bash
# Basic development monitoring
gonzo -f logs/app.log --follow

# Multi-service development
gonzo -f api.log -f db.log -f cache.log --follow

# With AI for debugging
gonzo -f debug.log --follow --ai-model="gpt-3.5-turbo"

# Fast iteration
gonzo -f logs/*.log --follow --update-interval=1s
```

#### Production Monitoring

```bash
# Single service monitoring
gonzo -f /var/log/app.log --follow --log-buffer=10000

# Multi-service monitoring
gonzo -f "/var/log/app/*.log" --follow \
      --log-buffer=10000 \
      --update-interval=5s

# With premium AI for incidents
gonzo -f /var/log/app.log --follow --ai-model="gpt-4"

# High-availability setup
gonzo -f "/var/log/*.log" --follow \
      --log-buffer=20000 \
      --memory-size=50000 \
      --update-interval=10s
```

#### Analysis and Investigation

```bash
# Analyze archived logs
gonzo -f application.log.1

# Multiple archived files
gonzo -f app.log.* 

# With AI analysis
gonzo -f incident-logs.log --ai-model="gpt-4"

# Performance analysis
gonzo -f app.log --log-buffer=20000
```

#### CI/CD Integration

```bash
# Automated build analysis
build-command 2>&1 | gonzo --test-mode --ai-model="gpt-3.5-turbo"

# Test result analysis
gonzo -f test-results.log --test-mode

# With configuration file
gonzo --config ci-config.yml --test-mode

# Exit on errors
gonzo -f build.log --test-mode || exit 1
```

### Flag Combination Examples

#### Performance Optimization

```bash
# High-volume logs
gonzo -f busy.log --follow \
      --log-buffer=20000 \
      --memory-size=100000 \
      --update-interval=10s

# Low-resource systems
gonzo -f app.log --follow \
      --log-buffer=500 \
      --memory-size=2000 \
      --update-interval=5s

# Balanced setup
gonzo -f app.log --follow \
      --log-buffer=5000 \
      --memory-size=15000 \
      --update-interval=2s
```

#### AI Configuration

```bash
# Cost-optimized development
gonzo -f debug.log --follow --ai-model="gpt-3.5-turbo"

# Production quality analysis
gonzo -f incident.log --ai-model="gpt-4"

# Local AI for privacy
export OPENAI_API_BASE="http://localhost:11434"
gonzo -f sensitive.log --follow --ai-model="llama3"

# No AI (disabled)
unset OPENAI_API_KEY
gonzo -f app.log --follow
```

#### Multi-Source Analysis

```bash
# Application + infrastructure
gonzo -f app.log -f nginx.log -f postgres.log --follow

# Glob patterns + specific files
gonzo -f "/var/log/app-*.log" -f /var/log/critical.log --follow

# OTLP + file backup
gonzo --otlp-enabled -f backup.log --follow

# Multiple sources with custom config
gonzo -f api.log -f db.log \
      --follow \
      --config multi-source.yml
```

### Environment Variables

#### Configuration via Environment

Many flags can be set via environment variables:

```bash
# File configuration
export GONZO_FILES="/var/log/app.log:/var/log/nginx.log"
export GONZO_FOLLOW=true

# Performance settings
export GONZO_UPDATE_INTERVAL=2s
export GONZO_LOG_BUFFER=5000
export GONZO_MEMORY_SIZE=15000

# AI configuration
export GONZO_AI_MODEL="gpt-4"
export OPENAI_API_KEY="sk-your-key"
export OPENAI_API_BASE="https://api.openai.com/v1"

# Display options
export NO_COLOR=1               # Disable colors
export GONZO_TEST_MODE=true    # Enable test mode

# Then run without flags
gonzo
```

**Priority Order:**

1. Command-line flags (highest)
2. Environment variables
3. Configuration file
4. Built-in defaults (lowest)

### Shell Completion

#### Enable Autocomplete

```bash
# Bash
source <(gonzo completion bash)
echo 'source <(gonzo completion bash)' >> ~/.bashrc

# Zsh
source <(gonzo completion zsh)
echo 'source <(gonzo completion zsh)' >> ~/.zshrc

# Fish
gonzo completion fish | source
gonzo completion fish > ~/.config/fish/completions/gonzo.fish

# PowerShell
gonzo completion powershell | Out-String | Invoke-Expression
```

**Benefits:**

* Tab completion for flags
* Completion for flag values
* File path completion
* Command completion

### Troubleshooting CLI Issues

#### Common Problems

**Flag not recognized:**

```bash
# Check flag spelling
gonzo --help | grep flag-name

# Ensure no extra dashes
gonzo --log-buffer=5000     # Correct
gonzo ---log-buffer=5000    # Wrong (three dashes)

# Check flag format
gonzo --log-buffer 5000     # Correct (space)
gonzo --log-buffer=5000     # Correct (equals)
```

**Value not accepted:**

```bash
# Duration format
--update-interval=2s        # Correct
--update-interval=2         # Wrong (no unit)

# Glob patterns must be quoted
gonzo -f "/var/log/*.log"   # Correct
gonzo -f /var/log/*.log     # Wrong (shell expands)

# Boolean flags
--follow                    # Correct (true)
--follow=true              # Also correct
--follow true              # Wrong (no equals)
```

**Configuration conflicts:**

```bash
# CLI flags override config file
# If config has: log-buffer: 2000
# And you run: gonzo --log-buffer=5000
# Result: Uses 5000 (CLI wins)

# Check what's actually being used
gonzo --show-config
```

### Quick Reference Card

#### Most Common Commands

```bash
# Basic file analysis
gonzo -f app.log

# Real-time monitoring
gonzo -f app.log --follow

# Multiple files
gonzo -f "*.log" --follow

# With AI
gonzo -f app.log --follow --ai-model="gpt-4"

# High performance
gonzo -f busy.log --follow --log-buffer=20000 --update-interval=10s

# Using config
gonzo --config prod.yml

# OTLP receiver
gonzo --otlp-enabled

# CI/CD mode
build-cmd | gonzo --test-mode
```

#### Essential Flags

```bash
-f, --file          # Specify log file
    --follow        # Real-time following
-b, --log-buffer    # History buffer size
-u, --update-interval  # Refresh rate
    --ai-model      # AI model selection
    --config        # Config file path
-h, --help          # Show help
-v, --version       # Show version
```

### What's Next?

Now that you know all CLI flags, explore related topics:

* **Configuration File** - Persistent settings via YAML
* **Advanced Configuration** - Complex setups and tuning
* **User Guide** - Master the Gonzo interface

Or start using flags effectively:

```bash
# Create aliases for common patterns
alias gonzo-dev='gonzo --follow --ai-model="gpt-3.5-turbo"'
alias gonzo-prod='gonzo --follow --log-buffer=10000 --ai-model="gpt-4"'
alias gonzo-test='gonzo --test-mode'

# Use them
gonzo-dev -f logs/app.log
gonzo-prod -f /var/log/app.log
```

***

**Master CLI flags for quick, powerful log analysis!** ⚡ From simple file analysis to sophisticated multi-source monitoring, command-line flags give you precise control over every Gonzo session.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/configuration/command-line-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.