nlpcmd-ai 0.1.3

AI-powered CLI assistant that understands natural language - transform plain English into system commands on Windows, Linux, and macOS

🤖 nlpcmd-ai

Transform natural language into system commands with AI 🚀
Current Version: 0.1.3

A truly AI-powered command-line assistant for Windows, Linux, and macOS that understands natural language and executes system commands intelligently. No more memorizing complex command syntax - just ask in plain English!

Unlike traditional CLI tools with pattern matching, nlpcmd-ai uses AI/LLM (OpenAI GPT-4, Anthropic Claude, or local Ollama) to understand complex, ambiguous commands and translate them into executable system operations - automatically adapting commands to your operating system.

📚 Links

• 📦 PyPI Package: https://pypi.org/project/nlpcmd-ai/
• 💻 GitHub Repository: https://github.com/Avikg/nlp_terminal_cmd
• 📖 Documentation: Full Documentation
• 🐛 Issues: Report Issues

✨ Features

• 🧠 True Natural Language Understanding - Uses AI models (OpenAI GPT-4, Anthropic Claude, or local Ollama)
• 🔒 Safe Execution - Smart confirmation for dangerous operations only
• 📝 Context Awareness - Remembers conversation history for follow-up commands
• 🎯 Intent Detection - Automatically determines what you want to do
• 🔧 Extensible - Easy to add custom command handlers
• 🌐 Cross-platform - Works seamlessly on Windows, Linux, and macOS
• 💬 Interactive Mode - Chat-like interface for complex workflows
• 🆓 100% Free Option - Use with local Ollama (no API costs)
• ⚡ Fast & Efficient - Powered by optimized AI models
• 🐍 Pure Python - No PowerShell issues, works everywhere

🎬 Quick Start

Try it in 3 commands:

# 1. Install
pip install nlpcmd-ai

# 2. Setup (choose one - Ollama is free!)
ollama pull llama3.2  # Free option
# OR get OpenAI API key from https://platform.openai.com/api-keys

# 3. Use it!
python -m nlpcmd_ai.cli "what is my ip"

🚀 Installation

Prerequisites

• Python 3.8+ - Download Python
• pip (comes with Python)

Step 1: Install the Package

pip install nlpcmd-ai

Step 2: Choose Your AI Provider

You have 3 options for the AI backend:

Option A: Ollama (Recommended - 100% Free & Private)

Run AI models locally on your computer - completely free, no API keys needed!

1. Install Ollama:

   • Windows/Mac: Download from https://ollama.ai
   • Linux: curl https://ollama.ai/install.sh | sh

2. Download AI model:

   ollama pull llama3.2
   

3. Create configuration file:

   Windows:

   echo NLP_PROVIDER=ollama > .env
   echo OLLAMA_MODEL=llama3.2 >> .env
   echo REQUIRE_CONFIRMATION=false >> .env
   

   Linux/macOS:

   cat > .env << EOF
   NLP_PROVIDER=ollama
   OLLAMA_MODEL=llama3.2
   REQUIRE_CONFIRMATION=false
   EOF
   

Option B: OpenAI (Paid - Most Accurate)

1. Get API Key: https://platform.openai.com/api-keys

2. Create .env file:

   # Windows
   echo NLP_PROVIDER=openai > .env
   echo OPENAI_API_KEY=your-api-key-here >> .env
   
   # Linux/macOS
   cat > .env << EOF
   NLP_PROVIDER=openai
   OPENAI_API_KEY=your-api-key-here
   EOF
   

Option C: Anthropic Claude (Paid - Most Intelligent)

1. Get API Key: https://console.anthropic.com/

2. Create .env file:

   NLP_PROVIDER=anthropic
   ANTHROPIC_API_KEY=your-api-key-here
   

Step 3: Verify Installation

python -m nlpcmd_ai.cli "what is my ip"

If it shows your IP address, you're all set! 🎉

💡 Usage

Basic Commands

Just ask naturally - the AI will understand!

# System Information
python -m nlpcmd_ai.cli "what is my ip"
python -m nlpcmd_ai.cli "show mac address"
python -m nlpcmd_ai.cli "how much memory do I have"
python -m nlpcmd_ai.cli "show disk usage"
python -m nlpcmd_ai.cli "what's my CPU usage"
python -m nlpcmd_ai.cli "how long has my computer been running"
python -m nlpcmd_ai.cli "who am I"

# File Operations
python -m nlpcmd_ai.cli "list all python files"
python -m nlpcmd_ai.cli "find files larger than 10MB"
python -m nlpcmd_ai.cli "show directory structure"
python -m nlpcmd_ai.cli "show folders in C:"
python -m nlpcmd_ai.cli "find a.txt"
python -m nlpcmd_ai.cli "where is config.json"

# Network Commands
python -m nlpcmd_ai.cli "is port 8080 open"
python -m nlpcmd_ai.cli "ping google.com"
python -m nlpcmd_ai.cli "trace yahoo.com"

# Application Launching
python -m nlpcmd_ai.cli "open file explorer"
python -m nlpcmd_ai.cli "open browser"

# Get Help
python -m nlpcmd_ai.cli "help"
python -m nlpcmd_ai.cli "what can you do"

Interactive Mode (Recommended!)

Have a conversation with your terminal:

python -m nlpcmd_ai.cli -i

Then chat naturally:

> what is my ip
> show disk usage
> list python files in current directory
> find files modified today
> help
> exit

Advanced Usage

# Auto-confirm (skip confirmation prompts)
python -m nlpcmd_ai.cli --yes "show disk usage"

# Dry run (see what would execute without running)
python -m nlpcmd_ai.cli --dry-run "delete all .log files"

# Help
python -m nlpcmd_ai.cli --help

Create a Shortcut (Optional but Convenient)

Windows: Create nlpai.bat in your PATH:

@echo off
python -m nlpcmd_ai.cli %*

Then use:

nlpai "what is my ip"
nlpai -i

Linux/macOS: Add to ~/.bashrc or ~/.zshrc:

alias nlpai='python -m nlpcmd_ai.cli'

Then:

nlpai "what is my ip"
nlpai -i

📋 Supported Commands

System Information

• CPU usage, memory info, disk space - "show CPU usage", "how much RAM"
• System uptime, user info, hostname - "how long running", "who am I"
• Operating system details - Windows, Linux, macOS

Network Operations

• IP address lookup - "what is my ip", "show mac address"
• Port checking - "is port 8080 open"
• Network diagnostics - "ping google.com", "trace yahoo.com"
• Connectivity tests - Works without confirmation!

File & Directory Operations

• List files - "list python files", "show folders in C:"
• Find files - "find a.txt", "where is config.json"
• Directory navigation - "show current folder", "folder structure"
• File search - "search for *.py files"

Process Management

• List running processes - "show running processes"
• Find processes by name - "is python running"
• Monitor system resources - CPU, memory usage

Application Launching

• Open applications - "open file explorer", "open browser"
• Launch programs - Cross-platform support

Help & Information

• Get help - "help", "what can you do"
• Show capabilities - Lists all available commands
• Conversational queries - Friendly redirects to help

See SUPPORTED_COMMANDS.txt for complete list

🔧 Configuration

Environment Variables (.env file)

# AI Provider (required)
NLP_PROVIDER=ollama  # or "openai" or "anthropic"

# Provider-specific settings
OLLAMA_MODEL=llama3.2
OPENAI_API_KEY=your-key
ANTHROPIC_API_KEY=your-key

# Safety
REQUIRE_CONFIRMATION=false  # Set to true for dangerous operations

# Logging
LOG_COMMANDS=true
LOG_FILE=~/.nlpcmd_ai/history.log

🛡️ Safety Features

• ✅ Smart confirmation - Only dangerous operations require confirmation
• ✅ Safe diagnostics - Network commands (ping, tracert) run without prompts
• ✅ Dry-run mode to preview commands
• ✅ Command logging for audit trail
• ✅ Path validation for file operations
• ✅ Protection against system directory access

Commands That Don't Need Confirmation:

• ✅ Network diagnostics (ping, tracert, nslookup)
• ✅ System info queries (CPU, memory, disk, uptime)
• ✅ File searches and listings
• ✅ Process listing
• ✅ Read-only operations

Commands That Require Confirmation:

• ⚠️ Deleting files/directories
• ⚠️ Stopping processes
• ⚠️ Modifying system files
• ⚠️ Operations with sudo/admin privileges

🎯 Examples

Example 1: System Monitoring

$ python -m nlpcmd_ai.cli -i

> what's my CPU usage
CPU Information:
Usage: 23.5%
Cores: 8
Current Speed: 2400 MHz

> how much memory do I have
Memory Information:
Total: 16.00 GB
Available: 8.50 GB
Used: 7.50 GB
Usage: 46.9%

> show disk usage
Disk Usage for C:\:
Total: 476.94 GB
Used: 250.30 GB
Free: 226.64 GB
Usage: 52.5%

Example 2: File Management

$ python -m nlpcmd_ai.cli "find all python files"

 📋 Category: file_operation
 ⚡ Action: find_files
 💻 Command: dir /s /b *.py

Found 15 files:
./nlpcmd_ai/engine.py
./nlpcmd_ai/handlers.py
./nlpcmd_ai/cli.py
...

Example 3: Network Troubleshooting

$ python -m nlpcmd_ai.cli "what is my ip"

Local IP: 192.168.1.100
Public IP: 203.0.113.45

$ python -m nlpcmd_ai.cli "show mac address"

Network Interface MAC Addresses:
Ethernet: 00-1A-2B-3C-4D-5E
Wi-Fi: 00-1F-2E-3D-4C-5B

$ python -m nlpcmd_ai.cli "is port 8080 open"

❌ Port 8080 is CLOSED on localhost

Example 4: File Search

$ python -m nlpcmd_ai.cli "where is config.json"

 💻 Command: dir /s /b config.json

C:\Development\nlpcmd\config.json
C:\Users\user\project\config.json

🔌 Extending nlpcmd-ai

Create custom handlers for your specific needs:

# custom_handler.py
from nlpcmd_ai.base_handler import BaseHandler, CommandResult

class MyCustomHandler(BaseHandler):
    def can_handle(self, category: str, action: str) -> bool:
        return category == "my_custom_category"
    
    def execute(self, command: str, parameters: dict, dry_run: bool = False) -> CommandResult:
        # Your custom logic here
        return CommandResult(success=True, output="Custom output")

See examples/custom_handlers.py for more examples.

📊 Comparison with Alternatives

Feature	nlpcmd-ai	Traditional CLI	Shell Scripts
Natural Language	✅ Yes	❌ No	❌ No
Cross-Platform	✅ Auto-adapts	⚠️ Manual	⚠️ Manual
Learning Curve	✅ None	❌ High	❌ High
AI-Powered	✅ Yes	❌ No	❌ No
Interactive	✅ Yes	⚠️ Limited	❌ No
Extensible	✅ Yes	⚠️ Limited	✅ Yes
No PowerShell Issues	✅ Yes	❌ Varies	❌ Varies

🆕 What's New in v0.1.3

• ✅ Fixed MAC address retrieval using Python (psutil)
• ✅ Improved port checking with better parameter extraction
• ✅ Extended timeout for network commands (ping, tracert) - 120 seconds
• ✅ Removed confirmation prompts for safe diagnostic commands
• ✅ Better file search with dir /s /b pattern
• ✅ Help handler for conversational queries
• ✅ Application launching support (file explorer, browser)
• ✅ Enhanced AI prompt for better path handling
• ✅ All system info commands use Python (no PowerShell dependencies)
• ✅ Smart confirmation - only dangerous operations require confirmation
• ✅ Fixed action parameter passing to handlers
• ✅ Improved current directory vs specific path handling

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/Avikg/nlp_terminal_cmd.git
cd nlp_terminal_cmd

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with OpenAI GPT, Anthropic Claude, and Ollama
• Uses psutil for system information
• UI powered by Rich

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• PyPI: https://pypi.org/project/nlpcmd-ai/

🌟 Star History

If you find this project useful, please consider giving it a ⭐ on GitHub!

---

Made with ❤️ by Avikg

Try it now: pip install nlpcmd-ai

---

⚠️ Note: This tool executes system commands based on AI interpretation. Always review commands before execution and use safety features appropriately.