Interactive Help System for Shell Configurations

1#!/bin/bash
2# Interactive Help System for Shell Configurations
3# Create a searchable, topic-based documentation system for your terminal
4
5# The help() function - add to ~/.zshrc or ~/.bashrc
6help() {
7    local help_file="$HOME/.zsh_help.md"
8    
9    # Check if help file exists
10    if [[ ! -f "$help_file" ]]; then
11        echo "Help file not found. Creating template at $help_file"
12        create_help_template
13        return 1
14    fi
15    
16    # If no argument, show full help with glow (or fallback to less)
17    if [[ -z "$1" ]]; then
18        if command -v glow >/dev/null 2>&1; then
19            glow -p "$help_file"
20        elif command -v bat >/dev/null 2>&1; then
21            bat --style=plain --paging=always "$help_file"
22        else
23            less "$help_file"
24        fi
25    else
26        # Search for specific topic
27        local section
28        case "$1" in
29            nav|navigation) section="## 🧭 Navigation" ;;
30            fzf|fuzzy) section="## 🔍 FZF" ;;
31            git) section="## 🛠️ Git" ;;
32            tools|cli) section="## 📁 File System Tools" ;;
33            sql|db|database) section="## 📀 SQL and Database" ;;
34            aws|cloud) section="## 🚀 AWS" ;;
35            ai|llm) section="## 🤖 AI/LLM Tools" ;;
36            network|ssh) section="## 🌐 Network" ;;
37            *) section="## .*$1" ;;  # Regex search for any section
38        esac
39        
40        # Use glow to render and less to search
41        if command -v glow >/dev/null 2>&1; then
42            glow "$help_file" | less -R +/"$section"
43        else
44            less +/"$section" "$help_file"
45        fi
46    fi
47}
48
49# Quick aliases for common help topics
50alias h='help'
51alias h-nav='help navigation'
52alias h-git='help git'
53alias h-fzf='help fzf'
54alias h-aws='help aws'
55alias h-ai='help ai'
56
57# Create a template help file
58create_help_template() {
59    cat << 'EOF' > "$HOME/.zsh_help.md"
60# 🚀 Shell Configuration Help
61
62Quick access: `help` or `h` | Search: `help <topic>` | Edit: `help-edit`
63
64## 📋 Table of Contents
65
66- [Navigation](#-navigation)
67- [FZF Commands](#-fzf)
68- [Git Integration](#-git-integration)
69- [File System Tools](#-file-system-tools)
70- [SQL and Database](#-sql-and-database)
71- [AWS Commands](#-aws)
72- [AI/LLM Tools](#-aillm-tools)
73- [Network & SSH](#-network--ssh)
74
75---
76
77## 🧭 Navigation
78
79### Directory Shortcuts
80- `..` - Go up one directory
81- `...` - Go up two directories
82- `....` - Go up three directories
83- `z <partial-name>` - Jump to frequently used directory
84- `d` - Show directory stack
85- `1-9` - Jump to directory in stack
86
87### File Operations
88- `ll` - Detailed list with icons
89- `la` - Show all files including hidden
90- `lt` - Tree view with icons
91- `lsg` - List with git status
92
93---
94
95## 🔍 FZF
96
97### Key Bindings
98- `Ctrl+R` - Search command history
99- `Ctrl+T` - Find files and insert path
100- `Alt+C` - Change to directory
101
102### Custom Functions
103- `fe` - Find and edit file
104- `fd` - Find and cd to directory
105- `fkill` - Find and kill process
106- `fbr` - Checkout git branch
107
108---
109
110## 🛠️ Git Integration
111
112### Quick Commands
113- `gs` - Git status
114- `gd` - Git diff
115- `gl` - Pretty git log
116- `gco` - Git checkout
117- `gcm` - Git commit with message
118- `gp` - Git push
119- `gpl` - Git pull
120
121### Advanced
122- `lg` - Launch lazygit
123- `ghpr` - Create PR to main branch
124- `gh dash` - GitHub dashboard
125
126---
127
128## 📁 File System Tools
129
130### Modern Replacements
131| Traditional | Modern | Description |
132|------------|---------|-------------|
133| `ls` | `eza` | File listing with icons |
134| `cat` | `bat` | Syntax highlighting |
135| `find` | `fd` | User-friendly find |
136| `grep` | `rg` | Ripgrep - faster search |
137| `top` | `btop` | Beautiful process monitor |
138| `df` | `duf` | Disk usage with clarity |
139| `du` | `dust` | Directory sizes visualized |
140
141---
142
143## 📀 SQL and Database
144
145### PostgreSQL
146- `pgcli` - Enhanced PostgreSQL client
147- `psql-local` - Connect to local database
148- `format-sql <file>` - Format SQL file
149
150### Universal SQL
151- `usql` - Connect to any database
152- Supports: PostgreSQL, MySQL, SQLite, etc.
153
154---
155
156## 🚀 AWS
157
158### EC2 Management
159- `ec2-list` - List all instances
160- `ec2-start <id>` - Start instance
161- `ec2-stop <id>` - Stop instance
162- `ec2-ssh <id>` - SSH to instance
163
164### Profiles
165- `aws-profile` - Switch AWS profile
166- `aws-whoami` - Current AWS identity
167
168---
169
170## 🤖 AI/LLM Tools
171
172### Command Line AI
173- `gm` - Google Gemini CLI
174- `gmc` - Continue Gemini conversation
175- `@` - Quick Ollama query
176- `??` - GitHub Copilot suggestion
177- `?!` - GitHub Copilot explanation
178
179---
180
181## 🌐 Network & SSH
182
183### SSH Shortcuts
184- `ssh-key-copy <host>` - Copy SSH key
185- `ssh-tunnel <port> <host>` - Create tunnel
186- `ports` - Show listening ports
187- `myip` - Show public IP
188
189### Tailscale
190- `ts-status` - Tailscale status
191- `ts-up` - Connect Tailscale
192- `ts-down` - Disconnect Tailscale
193
194---
195
196## ⚙️ Configuration
197
198### Reload & Edit
199- `reload` - Reload shell config
200- `zshconfig` - Edit ~/.zshrc
201- `aliasconfig` - Edit ~/.zsh_aliases
202- `help-edit` - Edit this help file
203
204### Performance
205- `zsh-stats` - Show zsh statistics
206- `timezsh` - Profile zsh startup time
207
208---
209
210## 🎯 Pro Tips
211
2121. **Use `take`** - Create and enter directory: `take new-project`
2132. **Glob Operators** - `**/*.js` finds all JS files recursively
2143. **Parameter Expansion** - `!!` last command, `!$` last argument
2154. **Background Jobs** - `&` to background, `jobs` to list, `fg` to foreground
216
217---
218
219*Generated: $(date)*
220EOF
221    echo "Created help template at $HOME/.zsh_help.md"
222}
223
224# Edit help file
225help-edit() {
226    ${EDITOR:-nano} "$HOME/.zsh_help.md"
227}
228
229# Search help for specific content
230help-search() {
231    if [[ -z "$1" ]]; then
232        echo "Usage: help-search <term>"
233        return 1
234    fi
235    
236    if command -v rg >/dev/null 2>&1; then
237        rg -i "$1" "$HOME/.zsh_help.md"
238    else
239        grep -i "$1" "$HOME/.zsh_help.md"
240    fi
241}
242
243# List all help topics
244help-topics() {
245    echo "Available help topics:"
246    grep "^##" "$HOME/.zsh_help.md" | sed 's/## /  /' | grep -v "Table of Contents"
247}