[workshop] category:shell tags:documentation,help,productivity,shell - Interactive Shell Help System

shell-help-system.sh

#!/bin/bash
# Interactive Help System for Shell Configurations
# Create a searchable, topic-based documentation system for your terminal

# The help() function - add to ~/.zshrc or ~/.bashrc
help() {
    local help_file="$HOME/.zsh_help.md"
    
    # Check if help file exists
    if [[ ! -f "$help_file" ]]; then
        echo "Help file not found. Creating template at $help_file"
        create_help_template
        return 1
    fi
    
    # If no argument, show full help with glow (or fallback to less)
    if [[ -z "$1" ]]; then
        if command -v glow >/dev/null 2>&1; then
            glow -p "$help_file"
        elif command -v bat >/dev/null 2>&1; then
            bat --style=plain --paging=always "$help_file"
        else
            less "$help_file"
        fi
    else
        # Search for specific topic
        local section
        case "$1" in
            nav|navigation) section="## 🧭 Navigation" ;;
            fzf|fuzzy) section="## 🔍 FZF" ;;
            git) section="## 🛠️ Git" ;;
            tools|cli) section="## 📁 File System Tools" ;;
            sql|db|database) section="## 📀 SQL and Database" ;;
            aws|cloud) section="## 🚀 AWS" ;;
            ai|llm) section="## 🤖 AI/LLM Tools" ;;
            network|ssh) section="## 🌐 Network" ;;
            *) section="## .*$1" ;;  # Regex search for any section
        esac
        
        # Use glow to render and less to search
        if command -v glow >/dev/null 2>&1; then
            glow "$help_file" | less -R +/"$section"
        else
            less +/"$section" "$help_file"
        fi
    fi
}

# Quick aliases for common help topics
alias h='help'
alias h-nav='help navigation'
alias h-git='help git'
alias h-fzf='help fzf'
alias h-aws='help aws'
alias h-ai='help ai'

# Create a template help file
create_help_template() {
    cat << 'EOF' > "$HOME/.zsh_help.md"
# 🚀 Shell Configuration Help

Quick access: `help` or `h` | Search: `help <topic>` | Edit: `help-edit`

## 📋 Table of Contents

- [Navigation](#-navigation)
- [FZF Commands](#-fzf)
- [Git Integration](#-git-integration)
- [File System Tools](#-file-system-tools)
- [SQL and Database](#-sql-and-database)
- [AWS Commands](#-aws)
- [AI/LLM Tools](#-aillm-tools)
- [Network & SSH](#-network--ssh)

---

## 🧭 Navigation

### Directory Shortcuts
- `..` - Go up one directory
- `...` - Go up two directories
- `....` - Go up three directories
- `z <partial-name>` - Jump to frequently used directory
- `d` - Show directory stack
- `1-9` - Jump to directory in stack

### File Operations
- `ll` - Detailed list with icons
- `la` - Show all files including hidden
- `lt` - Tree view with icons
- `lsg` - List with git status

---

## 🔍 FZF

### Key Bindings
- `Ctrl+R` - Search command history
- `Ctrl+T` - Find files and insert path
- `Alt+C` - Change to directory

### Custom Functions
- `fe` - Find and edit file
- `fd` - Find and cd to directory
- `fkill` - Find and kill process
- `fbr` - Checkout git branch

---

## 🛠️ Git Integration

### Quick Commands
- `gs` - Git status
- `gd` - Git diff
- `gl` - Pretty git log
- `gco` - Git checkout
- `gcm` - Git commit with message
- `gp` - Git push
- `gpl` - Git pull

### Advanced
- `lg` - Launch lazygit
- `ghpr` - Create PR to main branch
- `gh dash` - GitHub dashboard

---

## 📁 File System Tools

### Modern Replacements
| Traditional | Modern | Description |
|------------|---------|-------------|
| `ls` | `eza` | File listing with icons |
| `cat` | `bat` | Syntax highlighting |
| `find` | `fd` | User-friendly find |
| `grep` | `rg` | Ripgrep - faster search |
| `top` | `btop` | Beautiful process monitor |
| `df` | `duf` | Disk usage with clarity |
| `du` | `dust` | Directory sizes visualized |

---

## 📀 SQL and Database

### PostgreSQL
- `pgcli` - Enhanced PostgreSQL client
- `psql-local` - Connect to local database
- `format-sql <file>` - Format SQL file

### Universal SQL
- `usql` - Connect to any database
- Supports: PostgreSQL, MySQL, SQLite, etc.

---

## 🚀 AWS

### EC2 Management
- `ec2-list` - List all instances
- `ec2-start <id>` - Start instance
- `ec2-stop <id>` - Stop instance
- `ec2-ssh <id>` - SSH to instance

### Profiles
- `aws-profile` - Switch AWS profile
- `aws-whoami` - Current AWS identity

---

## 🤖 AI/LLM Tools

### Command Line AI
- `gm` - Google Gemini CLI
- `gmc` - Continue Gemini conversation
- `@` - Quick Ollama query
- `??` - GitHub Copilot suggestion
- `?!` - GitHub Copilot explanation

---

## 🌐 Network & SSH

### SSH Shortcuts
- `ssh-key-copy <host>` - Copy SSH key
- `ssh-tunnel <port> <host>` - Create tunnel
- `ports` - Show listening ports
- `myip` - Show public IP

### Tailscale
- `ts-status` - Tailscale status
- `ts-up` - Connect Tailscale
- `ts-down` - Disconnect Tailscale

---

## ⚙️ Configuration

### Reload & Edit
- `reload` - Reload shell config
- `zshconfig` - Edit ~/.zshrc
- `aliasconfig` - Edit ~/.zsh_aliases
- `help-edit` - Edit this help file

### Performance
- `zsh-stats` - Show zsh statistics
- `timezsh` - Profile zsh startup time

---

## 🎯 Pro Tips

1. **Use `take`** - Create and enter directory: `take new-project`
2. **Glob Operators** - `**/*.js` finds all JS files recursively
3. **Parameter Expansion** - `!!` last command, `!$` last argument
4. **Background Jobs** - `&` to background, `jobs` to list, `fg` to foreground

---

*Generated: $(date)*
EOF
    echo "Created help template at $HOME/.zsh_help.md"
}

# Edit help file
help-edit() {
    ${EDITOR:-nano} "$HOME/.zsh_help.md"
}

# Search help for specific content
help-search() {
    if [[ -z "$1" ]]; then
        echo "Usage: help-search <term>"
        return 1
    fi
    
    if command -v rg >/dev/null 2>&1; then
        rg -i "$1" "$HOME/.zsh_help.md"
    else
        grep -i "$1" "$HOME/.zsh_help.md"
    fi
}

# List all help topics
help-topics() {
    echo "Available help topics:"
    grep "^##" "$HOME/.zsh_help.md" | sed 's/## /  /' | grep -v "Table of Contents"
}