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:

Path specified with --config flag
./config.yml (current directory)
~/.config/gonzo/config.yml (user config)
/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

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:

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

# 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

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

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

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:

# 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

# 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

# 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

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

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:

Command-line flags (highest)
Environment variables
Configuration file
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.

PreviousConfiguration File NextIntegration Examples

Last updated 18 days ago