# Reference

Welcome to the Gonzo reference documentation! This section provides comprehensive technical reference material for all aspects of Gonzo.

### Overview

The Reference section contains detailed specifications, complete lists, and quick-lookup information. Use this section when you need to:

* **Look up** a specific keyboard shortcut
* **Check** valid configuration options
* **Find** environment variable names
* **Review** version history and changes
* **Verify** exact syntax or values

### Quick Access

#### Need to find something fast?

**Keyboard shortcuts**: Keyboard Shortcuts\
**Configuration options**: Configuration Schema\
**Environment variables**: Environment Variables\
**Version history**: Changelog

### Reference Guides

#### Keyboard Shortcuts

Complete reference of all keyboard shortcuts and mouse interactions.

**What's inside**:

* Global shortcuts (Space, q, r, etc.)
* Panel navigation (Tab, arrow keys)
* Log viewer controls
* AI feature shortcuts
* Search and filter shortcuts
* Vim-style navigation
* Mouse support
* Quick reference card (printable)

**Use when**:

* Learning keyboard shortcuts
* Looking up a specific key
* Wanting to optimize your workflow
* Printing a cheat sheet

**Quick examples**:

```
Space    - Pause/Resume
Enter    - View details
/        - Filter logs
i        - AI analysis
m        - Switch AI model
```

#### Configuration Schema

Complete specification of the configuration file format.

**What's inside**:

* Full YAML schema
* All configuration options
* Valid value types and ranges
* Default values
* Complete examples
* Validation rules
* Best practices

**Use when**:

* Creating a config file
* Validating configuration syntax
* Understanding default values
* Checking valid ranges
* Troubleshooting config issues

**Quick example**:

```yaml
files:
  - "/var/log/app.log"
follow: true
update-interval: 2s
log-buffer: 2000
skin: dracula
```

#### Environment Variables

Complete reference of all environment variables.

**What's inside**:

* Gonzo-specific variables
* AI provider variables
* System variables
* Variable precedence
* Configuration examples
* Docker/Kubernetes usage
* Shell profile setup

**Use when**:

* Setting up environment
* Container deployments
* CI/CD pipelines
* Debugging configuration
* Checking precedence

**Quick examples**:

```bash
GONZO_FILES="/var/log/app.log"
GONZO_FOLLOW="true"
OPENAI_API_KEY="sk-..."
GONZO_AI_MODEL="gpt-4"
```

#### Changelog

Version history and release notes.

**What's inside**:

* All version releases
* New features by version
* Bug fixes
* Breaking changes
* Upgrade notes
* Known issues
* Roadmap

**Use when**:

* Checking what's new
* Planning upgrades
* Understanding changes
* Reviewing history
* Checking compatibility

**Latest version**: 0.1.6 (August 2024)

### How to Use This Section

#### As a Quick Reference

**Keep these open while working**:

* Keyboard Shortcuts - For quick lookups
* Print the quick reference card for your desk

**Bookmark for frequent use**:

* Configuration Schema - When editing config
* Environment Variables - When setting up

#### As Complete Documentation

**Read through for comprehensive understanding**:

* Start with Configuration Schema
* Learn all shortcuts in Keyboard Shortcuts
* Understand precedence in Environment Variables
* Track changes via Changelog

#### As Troubleshooting Aid

**When something's not working**:

1. Check Configuration Schema for valid values
2. Verify environment in Environment Variables
3. Review Changelog for known issues
4. Try shortcuts from Keyboard Shortcuts

### Common Lookup Tasks

#### Find a Keyboard Shortcut

**Question**: "How do I pause the dashboard?"

**Answer**: Check Keyboard Shortcuts → Global Shortcuts

* `Space` - Pause/Resume

#### Validate Config Setting

**Question**: "What values can `update-interval` have?"

**Answer**: Check Configuration Schema → Performance Settings

* Type: `duration`
* Examples: `"500ms"`, `"1s"`, `"2s"`, `"5s"`

#### Find Environment Variable

**Question**: "How do I set the log buffer size via environment?"

**Answer**: Check Environment Variables → Performance Settings

* `GONZO_LOG_BUFFER="2000"`

#### Check Version Changes

**Question**: "What's new in version 0.1.6?"

**Answer**: Check Changelog → \[0.1.6]

* Full screen log viewing (`f` key)
* Extended search character limit
* OTLP message size increase

### Configuration Priority

Understanding how configuration is applied:

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

1. **Command line flags** - `gonzo --update-interval=2s`
2. **Environment variables** - `GONZO_UPDATE_INTERVAL="2s"`
3. **Configuration file** - `~/.config/gonzo/config.yml`
4. **Default values** - Built-in defaults

**Example**:

```bash
# config.yml says: update-interval: 10s
export GONZO_UPDATE_INTERVAL="5s"
gonzo --update-interval=1s
# Result: Uses 1s (flag overrides all)
```

Learn more in Configuration Schema and Environment Variables.

### Quick Reference Cards

#### Configuration Quick Card

```yaml
# Essential configuration
files: ["/var/log/app.log"]
follow: true
update-interval: 2s
log-buffer: 2000
memory-size: 15000
skin: dracula
ai-model: "gpt-4"
```

#### Environment Quick Card

```bash
# Essential environment variables
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_UPDATE_INTERVAL="2s"
export OPENAI_API_KEY="sk-..."
export GONZO_AI_MODEL="gpt-4"
```

#### Keyboard Quick Card

```
ESSENTIAL KEYS
─────────────
Space    Pause/Resume
q        Quit
/        Filter
s        Search
Enter    View details
ESC      Cancel/Close
i        AI analysis
m        Switch model
```

### Version Information

**Current Version**: 0.1.6\
**Release Date**: August 27, 2024\
**Go Version**: 1.21+ required\
**License**: MIT

See Changelog for complete version history.

### Compatibility

#### Platform Support

* **Linux**: All major distributions
* **macOS**: 10.15 and later
* **Windows**: Windows 10+ (WSL recommended)

#### Terminal Compatibility

**Recommended**:

* iTerm2 (macOS)
* Alacritty (Cross-platform)
* Windows Terminal (Windows)
* GNOME Terminal (Linux)
* Kitty (Cross-platform)

**Requirements**:

* Minimum 80x24 size
* 256 color support
* UTF-8 encoding

#### Go Version

**Required**: Go 1.21 or higher (for building from source)

**Check version**:

```bash
go version
```

### Related Documentation

#### Configuration Guides

* **Configuration File Guide** - Detailed config guide
* **CLI Reference** - Command line options
* **Advanced Configuration** - Advanced topics

#### User Guides

* **Quick Start** - Get started quickly
* **Basic Usage** - Learn the basics
* **Navigation & Controls** - Master the interface

#### Technical Docs

* **Architecture Overview** - How Gonzo works
* **OTLP Protocol** - Protocol details
* **Extension Points** - Extending Gonzo

### Printable Resources

#### Cheat Sheets

Create your own cheat sheets from these pages:

**Keyboard Shortcuts**:

* Print the quick reference card
* Keep near your workstation

**Configuration Template**:

* Copy the complete example
* Customize for your needs

**Environment Setup**:

* Use shell profile templates
* Add to your `.bashrc` or `.zshrc`

### Contributing to Reference Docs

Found an error or missing information?

**How to help**:

* [Open an issue](https://github.com/control-theory/gonzo/issues) to report problems
* [Submit a PR](https://github.com/control-theory/gonzo/pulls) to fix errors
* Suggest improvements via [Discussions](https://github.com/control-theory/gonzo/discussions)

See Contributing Guidelines for details.

### Keeping Up to Date

#### Stay Current

**Watch for updates**:

* Star the [GitHub repository](https://github.com/control-theory/gonzo)
* Watch for release notifications
* Check Changelog regularly
* Follow [@ControlTheoryHQ](https://twitter.com/ControlTheoryHQ)

**Update Gonzo**:

```bash
# Via go install
go install github.com/control-theory/gonzo/cmd/gonzo@latest

# Via Homebrew
brew upgrade gonzo

# Check version
gonzo --version
```

### Support

#### Need Help?

**For reference questions**:

* Search this Reference section
* Check related documentation
* Look in Troubleshooting

**For other help**:

* [GitHub Discussions](https://github.com/control-theory/gonzo/discussions) - Q\&A
* [GitHub Issues](https://github.com/control-theory/gonzo/issues) - Bug reports
* Email: <support@controltheory.com>

### Feedback

#### Improve These Docs

Help make reference docs better:

**What works well**:

* Clear examples
* Complete coverage
* Easy navigation
* Quick lookups

**We're working on**:

* Searchability
* More examples
* Better organization
* Interactive demos

**Your feedback matters**: [Share suggestions →](https://github.com/control-theory/gonzo/discussions)

***

### Navigate Reference Docs

Choose what you need:

**⌨️ Keyboard Shortcuts** - All shortcuts and mouse actions

**⚙️ Configuration Schema** - Complete config file reference

**🌍 Environment Variables** - All environment variables

**📋 Changelog** - Version history and release notes

{% hint style="info" %}
**Pro Tip**: Bookmark the pages you reference most often. The Keyboard Shortcuts and Environment Variables pages are frequently accessed.
{% endhint %}


---

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