# Keyboard Shortcuts

Complete reference of all keyboard shortcuts available in Gonzo. Master these to become a power user!

### Global Shortcuts

These shortcuts work from anywhere in the interface:

| Key             | Action                    | Description                                    |
| --------------- | ------------------------- | ---------------------------------------------- |
| `Space`         | Pause/Unpause             | Freeze dashboard updates (logs still buffer)   |
| `r`             | Reset                     | Clear all data and reset dashboard             |
| `q` or `Ctrl+C` | Quit                      | Exit Gonzo                                     |
| `?` or `h`      | Help                      | Show help screen with shortcuts                |
| `/`             | Filter                    | Enter filter mode (supports regex)             |
| `s`             | Search                    | Search and highlight text in logs              |
| `ESC`           | Cancel/Clear              | Clear filters, close modals, or cancel actions |
| `u`             | Cycle Interval (Forward)  | Increase update interval (1s→2s→5s→10s)        |
| `U`             | Cycle Interval (Backward) | Decrease update interval                       |

### Navigation Shortcuts

#### Panel Navigation

| Key         | Action         | Description                                |
| ----------- | -------------- | ------------------------------------------ |
| `Tab`       | Next Panel     | Move to next panel (clockwise)             |
| `Shift+Tab` | Previous Panel | Move to previous panel (counter-clockwise) |
| Mouse Click | Focus Panel    | Click any panel to switch focus            |

**Panel Order**: Log Viewer → Word Frequency → Attributes → Counts → (repeat)

#### Within Panels

| Key         | Action         | Description                                |
| ----------- | -------------- | ------------------------------------------ |
| `↑` or `k`  | Move Up        | Move selection up one entry                |
| `↓` or `j`  | Move Down      | Move selection down one entry              |
| `←` or `h`  | Scroll Left    | Horizontal scroll left                     |
| `→` or `l`  | Scroll Right   | Horizontal scroll right                    |
| `PgUp`      | Page Up        | Move up one page (\~10 entries)            |
| `PgDn`      | Page Down      | Move down one page (\~10 entries)          |
| `Home`      | Jump to Top    | Jump to first entry (pauses auto-scroll)   |
| `End`       | Jump to Bottom | Jump to latest entry (resumes auto-scroll) |
| Mouse Wheel | Scroll         | Scroll through content                     |

### Log Viewer Shortcuts

Specific to the Log Viewer panel (top-left):

| Key     | Action         | Description                        |
| ------- | -------------- | ---------------------------------- |
| `Enter` | View Details   | Open detailed view of selected log |
| `c`     | Toggle Columns | Show/hide Host and Service columns |
| `f`     | Full Screen    | Toggle full screen log viewing     |

#### Auto-Scroll Behavior

* **Scrolling up** or pressing `Home` → Pauses auto-scroll
* **Pressing `End`** → Resumes auto-scroll to latest logs
* **Status indicator**: Shows `FOLLOWING` when auto-scrolling

### Detail View Shortcuts

When viewing a log entry's details (after pressing `Enter`):

| Key             | Action       | Description                          |
| --------------- | ------------ | ------------------------------------ |
| `↑` / `↓`       | Scroll       | Scroll through log details           |
| `PgUp` / `PgDn` | Page Scroll  | Scroll by page                       |
| `i`             | AI Analysis  | Instant AI analysis of this log      |
| `c`             | AI Chat      | Start AI chat conversation about log |
| `Tab`           | Switch Pane  | Switch between details and chat pane |
| `m`             | Switch Model | Open model selection modal           |
| `ESC`           | Close        | Return to main dashboard             |

### AI Features Shortcuts

Available when AI is configured:

| Key | Action           | Description                                      |
| --- | ---------------- | ------------------------------------------------ |
| `i` | Instant Analysis | Get AI insights on selected log (in detail view) |
| `c` | Chat Mode        | Start conversational analysis (in detail view)   |
| `m` | Model Selection  | Choose different AI model                        |

#### In Model Selection Modal

| Key             | Action      | Description                        |
| --------------- | ----------- | ---------------------------------- |
| `↑` / `↓`       | Navigate    | Move through model list            |
| `PgUp` / `PgDn` | Page Scroll | Scroll by page                     |
| Mouse Wheel     | Scroll      | Scroll through models              |
| `Enter`         | Select      | Choose highlighted model           |
| `ESC`           | Cancel      | Close modal without changing model |

### Counts Modal Shortcuts

When viewing the detailed Counts analysis (press `Enter` on Counts panel):

| Key             | Action      | Description              |
| --------------- | ----------- | ------------------------ |
| `↑` / `↓`       | Scroll      | Scroll through analysis  |
| `PgUp` / `PgDn` | Page Scroll | Scroll by page           |
| Mouse Wheel     | Scroll      | Scroll content           |
| `ESC`           | Close       | Return to main dashboard |

**Modal Contents**:

* Time-series heatmap (60-minute window)
* Top 3 patterns per severity level
* Top 3 services per severity level

### Search and Filter Shortcuts

#### Filter Mode

Press `/` to enter filter mode:

| Key       | Action | Description                           |
| --------- | ------ | ------------------------------------- |
| Type text | Filter | Enter filter pattern (supports regex) |
| `Enter`   | Apply  | Apply filter                          |
| `ESC`     | Cancel | Cancel without applying               |

**Filter Examples**:

* `error` - Show logs containing "error"
* `error\|warn` - Show errors OR warnings (regex)
* `payment.*failed` - Regex pattern matching

#### Search Mode

Press `s` to enter search mode:

| Key       | Action | Description               |
| --------- | ------ | ------------------------- |
| Type text | Search | Enter search term         |
| `Enter`   | Apply  | Highlight matches         |
| `ESC`     | Clear  | Clear search highlighting |

### View Options

| Key | Action         | Description                                 |
| --- | -------------- | ------------------------------------------- |
| `c` | Toggle Columns | Show/hide Host/Service columns (Log Viewer) |
| `f` | Full Screen    | Toggle full screen view (Log Viewer)        |

### Mouse Support

Gonzo supports mouse interactions:

#### Click Actions

| Mouse Action     | Result                |
| ---------------- | --------------------- |
| Click panel      | Switch focus to panel |
| Click log entry  | Select entry          |
| Double-click log | Open detail view      |
| Click button     | Activate button       |

#### Scroll Actions

| Mouse Action | Result                            |
| ------------ | --------------------------------- |
| Wheel up     | Scroll up                         |
| Wheel down   | Scroll down                       |
| Shift+Wheel  | Horizontal scroll (if applicable) |

### Quick Reference Card

Print this reference for quick access:

```
═══════════════════════════════════════════════════════════
                    GONZO KEYBOARD SHORTCUTS
═══════════════════════════════════════════════════════════

GLOBAL CONTROLS                 NAVIGATION
───────────────                 ──────────
Space    Pause/Resume           Tab           Next panel
r        Reset data             Shift+Tab     Previous panel
q        Quit                   ↑↓ or kj      Move up/down
?        Help                   ←→ or hl      Scroll left/right
/        Filter                 Home          Jump to top
s        Search                 End           Jump to bottom
ESC      Cancel/Clear           PgUp/PgDn     Page scroll

LOG VIEWER                      AI FEATURES
──────────                      ───────────
Enter    View details           i        Instant analysis
c        Toggle columns         c        Chat mode
f        Full screen            m        Switch model

VIEW OPTIONS                    DETAIL VIEW
────────────                    ───────────
u/U      Cycle interval         ↑↓       Scroll
                               ESC      Close
                               Tab      Switch pane
                               i        AI analysis
                               c        AI chat

═══════════════════════════════════════════════════════════
```

### Vim-Style Navigation

Gonzo supports Vim-style keybindings for navigation:

| Vim Key | Standard Key | Action |
| ------- | ------------ | ------ |
| `h`     | `←`          | Left   |
| `j`     | `↓`          | Down   |
| `k`     | `↑`          | Up     |
| `l`     | `→`          | Right  |

**Why Vim keys?**

* Faster navigation (no need to move to arrow keys)
* Familiar to Vim/Vi users
* More ergonomic hand position

### Customizing Shortcuts

Currently, keyboard shortcuts are not customizable. This is a planned feature for future releases.

**Workaround**: Use terminal key remapping if needed.

### Keyboard Layout Considerations

#### QWERTY

All shortcuts are optimized for QWERTY keyboard layout.

#### Other Layouts

If you use Dvorak, Colemak, or other layouts:

* Physical key positions may differ
* Consider using arrow keys instead of `hjkl`
* Terminal remapping may help

#### International Keyboards

* Shortcuts use ASCII characters
* Should work on most international keyboards
* Some special keys may vary by layout

### Accessibility

#### For Users with Limited Mobility

* **Full mouse support**: All actions available via mouse
* **Large click targets**: Panels are easy to target
* **No rapid key sequences**: All shortcuts are single key or simple combo

#### For Screen Reader Users

Gonzo is a visual terminal UI and may have limited screen reader support. We're working on improvements:

* Alternative text modes
* Better semantic structure
* Keyboard-only navigation

### Common Workflows

#### Efficient Log Review

```
1. Start Gonzo
2. Space (pause)
3. ↑↓ or kj (navigate)
4. Enter (view details)
5. ESC (close)
6. Space (resume)
```

#### Quick Filtering

```
1. / (filter mode)
2. Type: error
3. Enter (apply)
4. Review filtered logs
5. ESC (clear filter)
```

#### AI Analysis

```
1. Navigate to log
2. Enter (open details)
3. i (instant analysis)
4. Read AI response
5. c (start chat if needed)
6. ESC (close)
```

#### Deep Pattern Investigation

```
1. Navigate to Counts panel (Tab)
2. Enter (open modal)
3. Review heatmap and patterns
4. ↑↓ (scroll through analysis)
5. ESC (close modal)
```

### Tips & Tricks

#### Speed Tips

* **Use Vim keys**: `hjkl` is faster than arrow keys
* **Tab navigation**: Quickly jump between panels
* **Space for investigation**: Pause to review, resume when done
* **Home/End**: Quick jumps to top/bottom

#### Workflow Tips

* **Filter before detail**: Use `/` to narrow down before diving in
* **Pause for AI**: Pause dashboard before AI analysis for stability
* **Reset regularly**: Press `r` to clear old data and start fresh
* **Use search**: `s` to highlight without filtering

#### Power User Tricks

* **Combine filters**: Use regex in `/` for complex patterns
* **Quick model switch**: `m` to try different AI models
* **Full screen logs**: `f` for better readability
* **Column toggle**: `c` to see more or less info

### Troubleshooting

#### Shortcuts Not Working

**Key not responding**:

* Ensure panel has focus (click or Tab to it)
* Check if modal is open (ESC to close)
* Verify keyboard layout is correct

**Mouse not working**:

* Check terminal supports mouse (most modern ones do)
* Try keyboard navigation instead
* Update terminal if issues persist

#### Conflicts with Terminal

Some terminals intercept keys:

* `Ctrl+C` - May be caught by terminal (use `q` instead)
* `Ctrl+Z` - Typically suspends process
* Function keys - May not work in all terminals

**Solution**: Use alternative keys or configure terminal.

### Platform-Specific Notes

#### macOS

* `Cmd` key not used (terminal limitation)
* All standard shortcuts work
* Mouse support excellent in iTerm2, Terminal.app

#### Linux

* All shortcuts work as documented
* Mouse support varies by terminal
* Works great in GNOME Terminal, Alacritty, Kitty

#### Windows

* All shortcuts work in Windows Terminal
* Some older terminals have limited mouse support
* Git Bash supports all features

### Related Documentation

* **Navigation & Controls** - Detailed navigation guide
* **Interface Overview** - Understanding the UI
* **AI Integration** - Using AI features

{% hint style="success" %}
**Pro Tip**: Print out the Quick Reference Card and keep it nearby while learning Gonzo. You'll memorize the shortcuts quickly!
{% endhint %}

{% hint style="info" %}
**Missing a shortcut?** Suggest new shortcuts by [opening an issue](https://github.com/control-theory/gonzo/issues) on GitHub!
{% endhint %}