AI CLI Assistant (LLM Powered)
AI-powered command-line assistant that converts natural language into safe shell commands using Gemini LLM with human-in-the-loop confirmation.
🚀 Quick Start
Install via pip
pip install ai-cli-llm==2.0.1
Set your API Key
Windows (PowerShell):
$env:GEMINI_API_KEY = "your_api_key_here"
Linux/macOS:
export GEMINI_API_KEY="your_api_key_here"
Get your free Gemini API key at ai.google.com
Run the CLI
python -m ai_cli.main
Fallback Mode (Offline)
You can switch to offline fallback mode at any time by typing:
/mode fallback
This disables LLM and uses pattern-based command generation locally (no API required).
That's it! Start typing natural language commands like:
create folder named projectsshow all filesdelete test.txt/mode fallback(to switch to offline mode)
Features
✨ Core Capabilities
- 🤖 Natural Language Processing: Describe what you want to do in plain English
- 🧠 LLM-Powered Command Generation: Uses Gemini API to generate accurate shell commands
- 🔒 Safety First: Built-in risk assessment and execution approval workflow
- 🔄 Undo/Rollback: Revert executed commands with automatic backup management
- 📋 Multi-Step Planning: Execute complex workflows with automatic plan generation
- 💾 Context Memory: Maintains conversation context across sessions
🔧 Advanced Features
- 🎯 Intent Recognition: NLP-based command categorization (file ops, system, dev, etc.)
- 🚀 Fallback Generator: Pattern-based command generation when API unavailable
- 📊 Execution Tracking: Full history of executed commands with timestamps
- ⚙️ Smart Autocomplete: Context-aware command suggestions
- 🌐 Multi-LLM Support: Works with Gemini API or local Ollama instances
Installation (From Source)
Prerequisites
- Python 3.10+
- Google Gemini API Key (free tier available at ai.google.com)
- PowerShell (Windows) or Bash (Linux/macOS)
Setup
-
Clone the repository
git clone https://github.com/yourusername/ai-cli.git cd ai-cli
-
Install the package
pip install -e .
-
Configure environment Create a
.envfile in the project root:GEMINI_API_KEY=your_api_key_here # Optional: for Ollama fallback OLLAMA_API_URL=http://localhost:11434
Get your free Gemini API key:
- Visit Google AI Studio
- Create a new API key
- Paste it in your
.envfile
-
Verify installation
python -m ai_cli.main
Usage
Interactive Mode
ai-cli
You can switch between LLM and fallback modes at any time:
> /mode fallback # Switch to offline mode
> /mode llm # Switch back to Gemini LLM
Then describe what you want to do:
> Clean up all .pyc files in the project
Generated command: find . -name "*.pyc" -type f -delete
Safe to execute? (y/n): y
✓ Command executed successfully
Supported Commands
File Operations
> Create a backup of my config file
> Delete all temporary files
> Find files larger than 100MB
> Rename all .txt files to .bak
System Management
> Show disk usage
> Kill process on port 8080
> Restart the Docker service
Development
> Install dependencies from requirements.txt
> Build and test the project
> Format all Python files
Command Flow
- Input → Natural language description
- Parse → Intent recognition and command mapping
- Generate → LLM creates the actual command
- Review → Risk assessment with execution approval
- Execute → Command runs with output capture
- Track → Stores for undo/history
Safety Features
Risk Assessment
Commands are automatically classified by risk level:
- 🟢 LOW: Read operations, non-destructive
- 🟡 MEDIUM: File modifications, package installations
- 🔴 HIGH: System changes, destructive operations
Approval Workflow
Generated command: rm -rf /important/directory
⚠️ HIGH RISK: Destructive file operation
Estimated impact: Permanent deletion
Safe to execute? (y/n): n
❌ Command blocked by user
Undo Capability
> undo
Recent commands:
1. mv file.txt file.bak ✓
2. rm oldfile.py ✓
Undo which? (1): 1
✓ Command reverted: file.bak → file.txt
Command History
AI CLI now tracks all commands executed in its own internal history file (ai_cli_history.txt).
-
To view your AI CLI command history, type:
show ai-cli history -
This will display a numbered list of all commands run via the AI CLI (not PowerShell session history).
-
The history file is stored in the project root and is persistent across sessions.
Project Structure
ai-cli/
├── ai_cli/
│ ├── main.py # Entry point and CLI loop
│ ├── llm_generator.py # Gemini API integration & fallback
│ ├── executor.py # Command execution engine
│ ├── safety.py # Risk assessment module
│ ├── planner.py # Multi-step plan execution
│ ├── undo_manager.py # Undo/rollback functionality
│ ├── context_manager.py # Context and history tracking
│ ├── intent_parser.py # NLP intent recognition
│ ├── command_mapper.py # Intent → command mapping
│ └── autocomplete.py # Tab completion support
├── setup.py # Package configuration
├── .env # API keys (not in git)
├── .gitignore # Git ignore patterns
└── README.md # This file
Configuration
Environment Variables
# Required
GEMINI_API_KEY=sk_...
# Optional
OLLAMA_API_URL=http://localhost:11434
OLLAMA_MODEL=mistral
SAFETY_LEVEL=medium # low, medium, high
HISTORY_SIZE=100
DEBUG=false
Architecture
Command Generation Flow
User Input
↓
Intent Parser (NLP)
↓
Intent → Command Mapper
↓
LLM Generator (Gemini API)
↓
Fallback Generator (if needed)
↓
Safety Assessment
↓
User Approval
↓
Executor
Undo System
- Maintains command history with metadata
- Tracks file state changes
- Generates reverse commands automatically
- Supports multi-command rollback
API Keys & Security
Getting a Gemini API Key
- Go to Google AI Studio
- Click "Create API Key"
- Copy the key to your
.envfile - Never commit
.envto git (already in.gitignore)
Free Tier Limits
- 100 requests per minute (sufficient for interactive use)
- 15 requests per day for batch operations
- Upgrade to paid plan for higher limits
Troubleshooting
"API Key not found"
# Check .env exists and has GEMINI_API_KEY
cat .env
"No module named 'spacy'"
# Install NLP dependencies
pip install spacy
python -m spacy download en_core_web_sm
Commands taking too long
- Check API rate limits
- Switch to Ollama for instant generation (local)
- Use fallback generator for common commands
Undo not working
- Check undo history:
ai-cli --history - Ensure backup files exist in
.ai-cli-backups/
Advanced Usage
Batch Mode
echo "Find all .log files" | ai-cli --batch
Dry Run (preview only)
ai-cli --dry-run
> Clean up temp files
[DRY RUN] rm -rf /tmp/*.log
No commands executed
View History
ai-cli --history
Clear History
ai-cli --clear-history
Contributing
Contributions welcome! Areas for improvement:
- Cross-platform command support (Windows/Linux/macOS)
- More fallback patterns for common operations
- Integration with other LLMs (Claude, GPT-4)
- Web UI dashboard
- Docker container support
Limitations & Known Issues
⚠️ Important Notes
- Commands are OS-specific (PowerShell on Windows, Bash on Linux/macOS)
- Some complex multi-step operations may require manual execution
- API rate limits apply during batch operations
- Undo only works for tracked file operations
Dependencies
google-generativeai>=0.3.0 # Gemini API
requests>=2.28.0 # Ollama API
python-dotenv>=0.19.0 # .env support
spacy>=3.0.0 # NLP (optional)
License
MIT License - Feel free to use, modify, and distribute.
Support
- 📧 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📚 Documentation: See ADVANCED_FEATURES.md
Roadmap
- Basic command generation
- Safety checks
- Undo functionality
- Web interface
- Database backend for history
- Custom command templates
- Multi-user support
- Cloud sync
Made with ❤️ for command-line enthusiasts
Metadata
Release files for ai-cli-llm 2.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_cli_llm-2.0.3.tar.gz | 38.4 kB | Without provenance | Details for ai_cli_llm-2.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_cli_llm-2.0.3-py3-none-any.whl | Python 3 | none | any | Details for ai_cli_llm-2.0.3-py3-none-any.whl |
Total release size: 77.2 kB
Release files / ai_cli_llm-2.0.3.tar.gz
| Download URL | ai_cli_llm-2.0.3.tar.gz |
|---|---|
| Size | 38.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
85633193a9bd8185bc61ccdab64b90d31c89a3a8d7cb310043accebc0d329961
|
|
BLAKE2b-256 checksum How to use checksums |
a50a8c411b85df439d38fa44961615749596b6301544edfb01a974c2a2357b66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / ai_cli_llm-2.0.3-py3-none-any.whl
| Download URL | ai_cli_llm-2.0.3-py3-none-any.whl |
|---|---|
| Size | 38.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9937a875535dfef13c662c79e4f727f62318203df388b1f2e8f31768cbf7c68f
|
|
BLAKE2b-256 checksum How to use checksums |
bbf1960d3c9cd8f08e7a0c670dfc5f310695ce2153f692d189a615af969d370a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for ai-cli-llm 2.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.