PromptShell

<h1 align="center" style="font-size: 32px;"> >_ PromptShell ^{<span style="font-size: 14px; color: #666;">v0.1.1</span>} </h1> <p align="center" style="font-size: 18px;">The Intelligent Terminal | Context-Aware Natural Language Commands</p> <p align="center"> <img src="https://img.shields.io/badge/Windows-0078D6?style=flat&logo=windows&logoColor=white" height="25" style="margin-right: 4px;"> <img src="https://img.shields.io/badge/Linux-FCC624?style=flat&logo=linux&logoColor=black" height="25" style="margin-right: 4px;"> <img src="https://img.shields.io/badge/macOS-000000?style=flat&logo=apple&logoColor=white" height="25"> </p> <a href="https://pepy.tech/project/promptshell/"> <img src="https://static.pepy.tech/badge/promptshell" height="20"> </a>

https://github.com/user-attachments/assets/c2ba7d09-83ea-4d10-a825-92c30f28c0bd

---

📖 Table of Contents

• Features
• Installation
• Configuration
• Usage
• Examples
• Development Status
• Contributing
• License
• Contact

---

✨ Features

🚀 Redefine Your Terminal Experience

• ⚡Natural Language to Shell Commands: Converts plain English queries into accurate shell commands.

• 🖥️Cross-Platform Compatibility: Works seamlessly across Windows, Linux, and macOS.

• 🤖Hybrid AI-Model Support: Supports both local (Ollama) and cloud-based (Groq, OpenAI, Google, etc.) LLMs for flexibility.

• 🔒Privacy-First Approach: Defaults to local models and runs completely offline, so that no data leaves your device unless you enable cloud APIs.

• 🎯Context-Aware Execution: Remembers command history, tracks files, and adapts suggestions accordingly.

• ⚠️Secure Command Execution: Blocks dangerous commands and asks for confirmation.

• 🛠️Intelligent Debugging & Auto-Correction: Identifies error, autonomously debugs issues and suggests corrected command.

• 🔍Smart Autocompletion: Provides tab completions for files and folder present in working directory.

• 🤖Direct Execution & Queries: Directly execute shell commands with '!' (e.g., !ls -la), or Ask shell-related questions using '?' (e.g., How do I create a new SSH key?).

• 🐳Built-in Support for Git, Docker, and Dev Tools: Seamlessly understands and executes Git, Docker, Kubernetes, and package manager commands.

• 🏷️User Defined Aliases: The alias system allows you to create, remove, list, import and export shortcuts for complex commands.

---

📥 Installation

Prerequisites

• Python 3.9+
• pip (Windows)
• pipx (Linux & macOS)

Installation Steps

Windows:

pip install promptshell

Linux & macOS:

pipx ensurepath  # Ensure pipx is in PATH (Linux/macOS)
pipx install promptshell

Run PromptShell

promptshell

---

⚙️ Configuration

• Local models need 4GB+ RAM (llama3:8b) to 16GB+ (llama3:70b)
• API performance varies by provider (deepseek-r1-distill-llama-70b in Groq is recommended)
• Response quality depends on selected model capabilities

Local Configuration

# Install Ollama for local LLM's
$ curl -fsSL https://ollama.com/install.sh | sh   # Linux
$ brew install ollama   # MacOS
$ winget install Ollama.Ollama    # Windows (via Powershell Administrator)

# Verify Installation
$ ollama --version

# Get base model
$ ollama pull <model_name>

First-Time Setup

# Interactive configuration wizard

$ --config

? Select operation mode: (Use arrow keys)
 » local (Privacy-first, needs 4GB+ RAM)
   api (Faster but requires internet)

# If local mode is selected
? Choose local model: (Use arrow keys) # lists ollama models installed on your system
 » llama3.1:8b
   llama3:8b-instruct-q4_1
   deepseek-r1:latest
   mistral:latest

# If API mode is selected
? API provider selection: (Use arrow keys)
 » Groq
   OpenAI
   Google
   Anthropic
   Fireworks
   OpenRouter
   Deepseek

? Select model for Groq: (Use arrow keys)
 » llama-3.1-8b-instant
   deepseek-r1-distill-llama-70b
   gemma2-9b-it
   llama-3.3-70b-versatile
   llama3-70b-8192
   llama3-8b-8192
   mixtral-8x7b-32768
   Custom model...

? Enter API key for Groq: #[hidden input]

✅ Configuration updated!
Saved to /home/username/.config/PromptShell/promptshell_config.conf   # (Linux & macOS)
Saved to C:\Users\username\AppData\Roaming\PromptShell\promptshell_config.conf   #(Windows)

Active model: #[Selected-model]
Configuration updated!

---

🛠 Usage

Basic Commands

# Start the PromptShell REPL
$ promptshell

# Execute natural language queries
$ backup all .txt files in a folder named backup

# Directly execute raw shell commands (bypassing AI processing) with '!'
$ !mkdir backup && copy *.txt backup\

# Ask questions by prefixing or suffixing your query with '?'
$ What's the command to list all hidden files?

# Configure or change the LLM provider
$ --config

# Start the interactive tutorial
$ --tutorial

# View help and usage instructions
$ --help

# Clear the terminal screen
$ clear

# Exit PromptShell
$ quit

CLI Options

• --version: Display the current version of PromptShell

Alias Support

Create shortcuts for frequently used commands:

# Create an alias
alias add gpm "git push origin main"   # without description
alias add gpn "git push origin main" --desc "Push changes to orgin/main"   # with description

# Use the alias
!gpm

# List all aliases
alias list

# List a specified alias
alias list <alias_name>

# Remove an alias
alias remove gpm

#Remove all alias
alias clear

# Import/export aliases
alias import ~/backup/aliases.json
alias export ~/backup/aliases.json

---

🌟 Examples

Convert Plain English Queries into Accurate Shell Commands

Ask Questions, Execute Commands Directly, and Ensure Secure Execution

Seamless Integration with Git, Docker, and Developer Tools

Generate Code Snippets Using Prompts and Save Directly to Desired Locations

---

🚧 Development Status

PromptShell is currently in alpha stage of development.

Known Limitations:

• Ollama models may hallucinate and produce inaccurate responses.
• Some API providers may have rate limits or require paid plans.

Roadmap:

• [x] Local LLM support
• [x] Interactive configuration setup
• [x] Improve command execution safety measures
• [x] Add support for user-defined command aliases
• [ ] Implement speech input support
• [ ] Expand model compatibility (e.g., fine-tuned small-scale models)

---

🤝 Contributing

We welcome contributions! Here's how to help:

1. Fork the repository.
2. Create a branch: git checkout -b feature/your-idea.
3. Commit changes: git commit -m "Add your feature".
4. Push to the branch: git push origin feature/your-idea.
5. Open a pull request.

---

📜 License

This project is licensed under the Apache 2.0 License. See LICENSE for details.

---

📧 Contact

• Built by Kirti Rathi
• Email: kirtirathi282@gmail.com

---

Note:<br/> Always verify commands before execution.<br/> Use at your own risk with critical operations.<br/> This project is not affiliated with any API or model providers.<br/> Local models require adequate system resources.<br/> Internet is required for API mode.<br/>