- Features
- Why ShellMind?
- Installation
- Configuration
- Usage
- Contributing
- Roadmap
- License
- Acknowledgments
ShellMind is your AI-powered terminal companion. It helps you generate, understand, and debug command-line instructions using natural language. Never struggle with terminal commands or flags again!
- Natural Language to Commands: Convert questions like "How do I find large files?" into terminal commands, making it accessible even for beginners.
- Command Explanations: Understand flags and syntax with
--explain, helping users learn as they go. - Error Diagnosis: Get suggestions for common CLI errors, reducing frustration and improving productivity.
- Safety Checks: AI-powered warnings for destructive or risky commands (e.g.,
rm -rf,chmod 777), ensuring safe usage. - OpenAI Integration: Powered by OpenAI API compatible endpoints, with support for local models like Ollama for added flexibility.
- System-Specific Commands: Automatically detect or specify your system type (e.g., Fedora, Debian, Ubuntu) for accurate, system-specific command generation.
- Real-Time Execution: Execute commands directly with real-time output using the
-xflag, ideal for long-running processes like system upgrades. - Interactive Mode: Ask multiple questions in a continuous session with
-i, perfect for complex workflows. - Command History: View previously generated commands with
--history, making it easy to reuse or review past queries. - JSON Output: All responses are structured as valid JSON, making it easy to integrate with other tools or scripts.
- Customizable Configuration: Specify your system type, API key, and base URL in a config file for a personalized experience.
ShellMind is designed to make terminal usage easier, safer, and more efficient for everyone. Here's what makes it special:
- User-Friendly: Whether you're a beginner or an advanced user, ShellMind bridges the gap between natural language and terminal commands.
- Educational: Explanations and safety checks help you learn terminal commands while avoiding common pitfalls.
- Efficient: Real-time execution and interactive mode streamline workflows, saving you time and effort.
- Extensible: The modular design makes it easy to add new features or integrate with other tools.
- Cross-Platform: Works with OpenAI and local models (e.g., Ollama), giving you flexibility in how you use the tool.
pip install shellmindgit clone https://github.com/k-mktr/shellmind.git
cd shellmind
pip install .You can specify your base URL, model and API key in the configuration file:
mkdir ~/.config/shellmind
touch ~/.config/shellmind/config.ini[default]
base_url = http://localhost:11434/v1 # or your OpenAI API base URL
model = llama3.2:3b-instruct-q8_0 # or your OpenAI API model
api_key = ollama # or your OpenAI API keyYou can specify your system type in the configuration file to ensure ShellMind generates system-specific commands:
[default]
system_type = Fedora # or Debian, Ubuntu, Arch, etc.If not specified, ShellMind will automatically detect your system type.
shellmind -a "How to search for 'error' in all .log files?"Output:
Command: grep -r "error" *.log
Explanation:
- `-r`: Recursively search subdirectories.
Start an interactive session where you can ask multiple questions:
shellmind -i
> How to check disk usage?
> How to find large files?
> exitshellmind -a "Explain tar -xzvf" --explainOutput:
Command: tar -xzvf archive.tar.gz
Explanation:
- `-x`: Extract files.
- `-z`: Decompress using gzip.
- `-v`: Verbose output (show progress).
- `-f`: Specify filename.
ShellMind now uses AI-powered safety checks to warn about destructive commands:
shellmind -a "Delete everything in /tmp"Output:
Command: rm -rf /tmp/*
⚠️ Warning: This command will delete all files in /tmp. Use with caution!
Execute the generated command directly (with confirmation for destructive commands):
shellmind -a "List files in /tmp" -xGenerate commands specific to your system type:
shellmind -a "Update my system"Output:
Command: sudo dnf upgrade # or sudo apt-get upgrade, depending on your system
Explanation:
- `sudo`: Run as superuser.
- `dnf`: Package manager for Fedora.
- `upgrade`: Upgrade all installed packages.
Real-Time Output:
When using the -x flag, ShellMind streams the command's output directly to the terminal, allowing you to see progress in real-time. This is especially useful for commands like dnf upgrade or apt-get upgrade.
View previously generated commands:
shellmind --historyShellMind can diagnose and suggest fixes for common CLI errors:
shellmind -a "Invalid command" -xShellMind ensures that all responses are structured as valid JSON, making it easier to parse and integrate with other tools.
shellmind -a "How to check disk usage?"ShellMind uses a detailed system prompt to ensure accurate, safe, and efficient command generation. The prompt includes:
- Role definition (Linux terminal expert).
- Safety guidelines.
- Output format requirements.
Example:
shellmind -a "Delete all files in /tmp"Get help and see all available options:
shellmind -hContributions are welcome! Here's how you can help:
- Report Issues: Found a bug or have a feature request? Open an issue.
- Submit Pull Requests: Want to contribute code? Fork the repository, make your changes, and submit a pull request.
- Improve Documentation: Help improve the README, add examples, or write tutorials.
Before contributing, please read our Contributing Guidelines.
Here are some planned features and improvements:
- Plugin System: Add support for custom plugins to extend functionality.
- Command Aliases: Support user-defined aliases for frequently used commands.
- Enhanced Error Handling: Provide more detailed error messages and recovery suggestions.
Have an idea? Open an issue or submit a pull request!
ShellMind is licensed under the MIT License. See the LICENSE file for details.
- DeepSeek: For providing the powerful language models that make ShellMind possible.
- Ollama: For enabling local model support.
- CLI Warriors: Inspired by the countless developers and sysadmins who make the terminal their home.
Made with ❤️ by Karl Danisz | Inspired by CLI warriors everywhere.