ForgeShell Documentation
📦 What is ForgeShell?
ForgeShell is a developer-first terminal assistant that leverages AI to help you explain, optimize, and safeguard your shell commands in real-time. Built in Rust for performance and safety, ForgeShell empowers developers with intelligent command-line insights while maintaining full transparency.
🧰 Core Functionality
ForgeShell provides intelligent assistance across your entire command-line workflow, from understanding complex commands to optimizing shell scripts and preventing dangerous operations.
😓 Addressing Shell User Pain Points
ForgeShell is designed to reduce friction and eliminate common frustrations in the CLI and shell scripting experience.
Interactive CLI Challenges
- Steep Learning Curve →
forge assistandforge explainprovide real-time context - Lack of Visual Feedback → Command summaries and logs help visualize what's happening
- Typing/Memorization Issues →
forge buildguides you step-by-step - Finding the Right Command → Natural language queries via
forge assist - Cryptic Errors → AI-enhanced error explanations
Shell Scripting Challenges
- Syntax Quirkiness →
forge optimizehighlights improvements - Limited Error Handling → Detects missing
set -epatterns - Debugging Headaches →
forge tracefor execution tracing - Portability Problems → POSIX compliance suggestions
- Security Risks → Warns on unescaped input and risky patterns
⚡ Core Commands
🔍 Explain Command
forge explain "your_command_here"
- Uses AI to break down unfamiliar shell commands
- Highlights potential risks
- Suggests safer alternatives when applicable
Example:
$ forge explain "sudo rm -rf /var/www"
This command recursively deletes all files in /var/www with root privileges.
⚠️ Dangerous. Consider running with --dry-run if supported.
🚀 Optimize Script
forge optimize script.sh
- Scans shell scripts for redundant loops, unsafe calls, and poor performance
- Suggests rewrites using best practices
- Highlights lines that could be simplified or parallelized
⚠️ Risk Detection
# Automatically runs when you execute risky commands (optional hook)
- Warns before executing high-risk operations (e.g.,
rm -rf,kill -9,chmod 777,curl | sh) - Adds confirmation prompts for flagged actions
🧠 Contextual Assistant
forge assist
Responds to general questions like:
- "How do I tail a log and highlight errors?"
- "What's the best way to SCP a file from server A to B?"
- Functions as a terminal-native prompt engineer
🔧 Command Builder
forge build ssh # or forge build <tool>
- Walks you through filling in parameters for common commands
- Builds correct syntax based on prompts (e.g., hostname, port, key path)
- Optionally outputs a ready-to-use shell script or alias
Example:
$ forge build ssh
> Host to connect to? dev.myserver.com
> Port (default 22)? 2200
> Username? root
> Identity file path? ~/.ssh/id_rsa
Suggested command:
ssh -i ~/.ssh/id_rsa root@dev.myserver.com -p 2200
🧭 Task-Oriented Guidance
forge guide "task description"
- Tell ForgeShell what you're trying to accomplish
- Receives a step-by-step breakdown of your available options
- Offers command suggestions with usage notes and safety tips
Example:
$ forge guide "how do I delete a file"
Navigate to the directory:
cd Documents
Delete a single file:
rm filename
Delete multiple files:
rm file1 file2 file3
Pattern delete (wildcards):
rm *.txt
Force delete without prompt:
rm -f filename
Prompt before delete:
rm -i filename
Delete directory recursively:
rm -r folder
Force delete directory recursively:
rm -rf folder (⚠️ dangerous)
📜 AI Command History
forge log
- Shows recent commands with AI explanations
- Tags unsafe or inefficient usage
- Optional local-only history with privacy-respecting settings
🔒 Privacy & Security
- ✓ ForgeShell does not transmit shell history unless explicitly opted-in
- ✓ Local-only mode using Ollama or llama.cpp supported
- ✓ API key vault for OpenAI / Anthropic / other LLMs with .env support
🚀 Installation
Option 1: Rust (Cargo)
cargo install forgeshell
Option 2: Binary Installer
wget forgeshell.com/install.sh | bash
Option 3: Homebrew (Coming Soon)
brew install forgeshell
Option 4: Debian-based (.deb)
sudo dpkg -i forgeshell-x.x.x.deb
Requires: Ubuntu, Debian, or compatible distribution
Option 5: RPM-based (.rpm)
sudo rpm -i forgeshell-x.x.x.rpm
Requires: RHEL, Fedora, CentOS, or compatible distribution
🔄 Release Plan
v1.0
Alpha
Explain, Optimize, Risk Warnings, Local Logging
v1.1+
Enhanced Features
Plugin support, prompt packs, community workflows
v2.0+
Advanced Platform
Visual workflow builder, team logging, full agentic CLI