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.

Quick Reference: Use gonzo --help or gonzo -h to see a summary of all available flags at any time.

Command Syntax

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:

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

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

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

Default Settings

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

High Volume

Low Memory

Development

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:

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

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

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

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

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

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

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

CI/CD Integration

# 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

Configuration Validation

Development Testing

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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

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

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

# 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

# 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

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

# 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.