ForgeShell Documentation
📦 What is ForgeShell?
ForgeShell is an operations-first terminal assistant for the people who carry the pager. It leverages AI to help operators, SREs, and platform engineers explain, simulate, and safeguard production commands in real time. Built in Rust for performance and safety, ForgeShell keeps incident responders fast while maintaining full transparency and control.
🧰 Core Functionality
ForgeShell backs every phase of an on-call workflow—from understanding complex remediation steps to optimizing runbooks and intercepting dangerous operations before they reach production.
😓 Eliminating On-Call Shell Pain Points
ForgeShell removes friction for incident responders working in high-pressure terminals, covering both live CLI fixes and scripted automations.
Interactive CLI Challenges Under Pressure
- Steep Learning Curve for new responders →
forge assistandforge explainprovide runbook-ready context - Lack of Visual Feedback → Command summaries and logs clarify what will happen before you press enter
- Typing/Memorization Issues →
forge buildguides responders step-by-step - Finding the Right Command → Natural language queries via
forge assisttranslate incident intent into action - Cryptic Errors → AI-enhanced error explanations speed up incident triage
Shell Scripting Challenges in Production
- Syntax Quirkiness →
forge optimizehardens scripts before they ship to production - Limited Error Handling → Detects missing
set -epatterns and escalation paths - Debugging Headaches →
forge traceprovides incident-ready execution tracing - Portability Problems → POSIX compliance suggestions keep shared runbooks consistent
- Security Risks → Warns on unescaped input and risky patterns before change windows open
⚡ 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 real-time on-call questions like:
- "How do I tail a log and highlight errors during an incident?"
- "What's the safest way to SCP a hotfix from server A to B?"
- Functions as a terminal-native prompt engineer for ops teams
🔧 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 on-call task you're trying to accomplish
- Receives a step-by-step breakdown of safe options and rollback paths
- Offers command suggestions with usage notes, safety tips, and simulation advice
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 for post-incident reviews
- Tags unsafe or inefficient usage to feed back into runbooks
- 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