EnhancedTerminal/EnhancedTerminal-Distribution/USAGE_GUIDE.md

Enhanced Terminal v3.0 - Usage Guide

🎯 Quick Start

1. Build the application:

   ./build.sh
   

2. Launch the terminal:

   open EnhancedTerminal.app
   

3. Start using it! The terminal works just like your regular terminal, but with superpowers.

🌟 Key Features

1. Command History Search (Cmd+R)

The most powerful feature for productivity!

How to use:

1. Press Cmd+R to open the history search panel
2. Start typing to search through your command history
3. The search is fuzzy - it finds commands containing your search terms
4. Double-click a command or press Enter to use it
5. The command is inserted at your cursor position

Example:

• Type "docker" to find all docker-related commands
• Type "git commit" to find all git commit commands
• Type "find pdf" to find commands that searched for PDFs

Tips:

• History is saved between sessions
• Recent commands appear first
• Search is case-insensitive

2. Auto-Suggestions (Like Fish Shell)

As you type, the terminal suggests commands from your history.

How it works:

1. Start typing a command
2. If you've used a similar command before, it appears in gray text
3. Press Tab to accept the suggestion
4. Continue typing to ignore it

Example:

$ git st█
      status  ← suggestion appears in gray

Press Tab to complete to git status

Toggle on/off:

• Go to Settings (Cmd+,)
• Check/uncheck "Enable Auto-suggestions"

3. Multiple Tabs (Cmd+T)

Run multiple terminal sessions simultaneously.

How to use:

• Cmd+T - Open a new tab
• Click tab buttons to switch between tabs
• Cmd+W - Close current tab
• Each tab has its own independent shell session

Use cases:

• Monitor logs in one tab while working in another
• Run a development server in one tab, git commands in another
• Keep different project directories in separate tabs

4. AI Command Generation (Cmd+K)

Generate terminal commands from natural language descriptions.

Setup (choose one):

Option A: Ollama (Free, Local, Recommended)

# Install Ollama
brew install ollama

# Pull a model
ollama pull llama3.2:latest

# Ollama runs automatically in the background

Then in Enhanced Terminal:

1. Press Cmd+, for Settings
2. Select "Ollama" as AI Provider
3. Verify URL: http://localhost:11434
4. Set model: llama3.2:latest

Option B: OpenAI (Requires API Key)

1. Get API key from https://platform.openai.com/api-keys
2. Press Cmd+, for Settings
3. Select "OpenAI" as AI Provider
4. Enter your API key

How to use:

1. Press Cmd+K
2. Describe what you want to do in plain English
3. Click "Generate" or press Enter
4. Review the generated command
5. Click "Use Command" to insert it
6. Press Enter to execute

Examples:

• "find all PDF files larger than 10MB" → find . -type f -name "*.pdf" -size +10M

• "show me the 10 largest files in this directory" → du -ah . | sort -rh | head -10

• "kill all processes using port 8080" → lsof -ti:8080 | xargs kill -9

• "compress all log files older than 7 days" → find . -name "*.log" -mtime +7 -exec gzip {} \;

5. Command Snippets (Cmd+P)

Quick access to commonly used commands.

How to use:

1. Press Cmd+P
2. Browse or search for a snippet
3. Double-click or press Enter to use it

Built-in categories:

• Files: List files, find large files, disk usage
• Git: Status, log, commit, branch operations
• Docker: Container and image management
• Network: Port management, network connections
• System: Process management, system information

Add your own snippets:

1. Press Cmd+P
2. Click "Add New"
3. Enter name, command, category, and description
4. Your snippet is saved permanently

Example custom snippets:

• Name: "Deploy to production" Command: git push origin main && ssh prod 'cd /app && ./deploy.sh' Category: "Deployment"

• Name: "Backup database" Command: pg_dump mydb > backup_$(date +%Y%m%d).sql Category: "Database"

6. Themes

Choose from 4 beautiful themes:

Dracula (Default)

• Modern dark purple background
• High contrast, easy on the eyes
• Popular among developers

Solarized Dark

• Scientifically designed color scheme
• Low contrast, reduces eye strain
• Perfect for long coding sessions

Nord

• Arctic-inspired color palette
• Cool, calming colors
• Great for focus

Classic

• Retro green-on-black terminal
• Nostalgic hacker aesthetic
• High contrast

Change theme:

1. Press Cmd+, for Settings
2. Select theme from dropdown
3. Changes apply immediately to all tabs

7. Font Size Adjustment

Keyboard shortcuts:

• Cmd+Plus - Increase font size
• Cmd+Minus - Decrease font size
• Cmd+0 - Reset to default (14pt)

Or in Settings:

1. Press Cmd+,
2. Enter font size (8-72)
3. Changes apply to all tabs

⌨️ Complete Keyboard Shortcuts

Tabs & Navigation

Shortcut	Action
Cmd+T	New tab
Cmd+W	Close current tab
Click tabs	Switch between tabs

Search & Tools

Shortcut	Action
Cmd+R	Search command history
Cmd+K	AI Command Generator
Cmd+P	Command Snippets
Tab	Accept auto-suggestion

View

Shortcut	Action
Cmd+Plus	Increase font size
Cmd+Minus	Decrease font size
Cmd+0	Reset font size
Cmd+F	Toggle fullscreen

Edit

Shortcut	Action
Cmd+C	Copy selected text
Cmd+V	Paste
Cmd+A	Select all

Settings & Help

Shortcut	Action
Cmd+,	Open Settings
Cmd+Q	Quit application
Type help	Show help in terminal

💡 Pro Tips

1. Combine Features

• Use Cmd+R to find a complex command you used before
• Modify it slightly for your current need
• It gets added to history for next time

2. Build Your Snippet Library

• Whenever you create a complex command, save it as a snippet
• Add good descriptions and tags for easy searching
• Share snippets with your team

3. Use AI for Learning

• Generate commands with AI
• Study the generated command to learn new techniques
• Modify and experiment with the suggestions

4. Organize with Tabs

• Keep one tab for each project
• Use descriptive tab names (shown in tab bar)
• Switch quickly between contexts

5. Customize Your Experience

• Adjust font size for your display
• Choose a theme that matches your workflow
• Enable/disable auto-suggestions based on preference

🔧 Troubleshooting

AI Not Working

Ollama:

• Check if Ollama is running: ollama list
• Verify the model is downloaded: ollama pull llama3.2:latest
• Check the URL in Settings: should be http://localhost:11434

OpenAI:

• Verify your API key is correct
• Check you have credits in your OpenAI account
• Test the key at https://platform.openai.com/playground

Auto-suggestions Not Appearing

• Make sure they're enabled in Settings (Cmd+,)
• You need to have command history first
• Suggestions only appear for commands you've used before

History Search Empty

• History builds up as you use the terminal
• Try running some commands first
• History persists between sessions

Tab Not Responding

• Each tab runs an independent shell
• If a command hangs, close the tab (Cmd+W)
• Open a new tab (Cmd+T) to continue

Window Not Showing

• Try Cmd+Tab to switch to the app
• Check if it's in fullscreen mode
• Quit and restart the application

🎓 Learning Resources

Getting Started with Terminal

If you're new to terminal commands:

1. Type help in the terminal for built-in help
2. Use AI (Cmd+K) to learn commands
3. Browse snippets (Cmd+P) to see examples

Common Commands to Try

# Navigation
ls          # List files
cd folder   # Change directory
pwd         # Print working directory

# File operations
cat file.txt    # View file contents
cp src dest     # Copy file
mv old new      # Move/rename file
rm file         # Delete file

# System info
date        # Show date/time
whoami      # Show current user
df -h       # Disk space
top         # Process monitor (press q to quit)

# Git basics
git status      # Check repository status
git log         # View commit history
git diff        # See changes

🚀 Advanced Usage

Custom Shell Configuration

The terminal uses your existing shell configuration:

• .zshrc for zsh (default on macOS)
• .bashrc for bash
• All your aliases and functions work

Environment Variables

All your environment variables are available:

echo $PATH
echo $HOME
echo $USER

Piping and Redirection

Full support for Unix pipes and redirection:

ls -la | grep ".txt"
cat file.txt | wc -l
echo "hello" > output.txt

Background Jobs

Run commands in the background:

long_running_command &

Note: The terminal handles job control properly, so you won't see "fg: no job control" errors.

📊 Performance Tips

For Large Output

• Use less or more for large files
• Pipe to head or tail to limit output
• Clear screen regularly with clear or Cmd+K

For Many Tabs

• Close unused tabs to free memory
• Each tab runs a separate shell process
• Recommended: Keep 5-10 tabs maximum

History Management

• History is limited to 1000 commands
• Clear history if needed: Tools → Clear History
• Old commands are automatically removed

🎨 Customization Ideas

Create Workflow Snippets

Save entire workflows as snippets:

# Development workflow
git pull && npm install && npm run dev

# Deployment workflow
npm run build && npm test && git push

# Backup workflow
tar -czf backup.tar.gz project/ && scp backup.tar.gz server:~/

Use AI for Complex Tasks

Let AI help with:

• Complex find commands
• Advanced git operations
• System administration tasks
• Data processing with awk/sed

Theme Switching

Switch themes based on:

• Time of day (dark themes at night)
• Task (Classic for focused work)
• Mood (Nord for calm, Dracula for energy)

---

Need more help? Type help in the terminal or check the README.md file.

Enjoy your enhanced terminal experience! 🚀