nlpcmd-ai 0.1.0

A true NLP-powered command line assistant using AI - works on Windows, Linux, and macOS

🤖 nlpcmd-ai

A truly NLP-powered command-line assistant for Windows, Linux, and macOS that understands natural language and executes system commands intelligently.

Unlike traditional CLI tools with pattern matching, nlpcmd-ai uses AI/LLM to understand complex, ambiguous commands and translate them into executable system operations - automatically adapting commands to your operating system.

✨ Features

• 🧠 True Natural Language Understanding - Uses AI models (OpenAI, Claude, or local Ollama)
• 🔒 Safe Execution - Confirms dangerous operations before execution
• 📝 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 on Windows, Linux, and macOS
• 💬 Interactive Mode - Chat-like interface for complex workflows

🚀 Installation

Quick Install (All Platforms)

pip install nlpcmd-ai

Platform-Specific Installation

Windows

Option 1: Using pip (Recommended)

pip install nlpcmd-ai

Option 2: Using installation script

# Download and run install.bat
curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.bat
install.bat

If nlpai command is not found, add Python Scripts to PATH or use:

python -m nlpcmd_ai.cli "your command here"

Linux

Option 1: Using pip (Recommended)

pip3 install nlpcmd-ai

Option 2: Using installation script

curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.sh
bash install.sh

If nlpai not found, add to PATH:

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

macOS

Option 1: Using pip (Recommended)

pip3 install nlpcmd-ai

Option 2: Using installation script

curl -O https://raw.githubusercontent.com/yourusername/nlpcmd-ai/main/install.sh
bash install.sh

Advanced Installation

With Local LLM Support (Ollama)

pip install nlpcmd-ai[local]

From Source (Developers)

git clone https://github.com/yourusername/nlpcmd-ai.git
cd nlpcmd-ai
pip install -e .

All Optional Dependencies

pip install nlpcmd-ai[all]

⚙️ Configuration

Create a .env file or set environment variables:

# Choose your AI provider (openai, anthropic, or ollama)
NLP_PROVIDER=openai

# API Keys (if using cloud providers)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Ollama settings (if using local)
OLLAMA_MODEL=llama3.2
OLLAMA_HOST=http://localhost:11434

# Safety settings
REQUIRE_CONFIRMATION=true
DRY_RUN_MODE=false
LOG_COMMANDS=true

📖 Usage Examples

One-off Commands

# Simple commands
nlpai "what is my ip address"
nlpai "show me disk usage"
nlpai "find all python files in this directory"

# Complex operations
nlpai "find all python files larger than 1MB modified in the last week"
nlpai "compress all log files from last month and move them to archive folder"
nlpai "show me the top 5 processes using most CPU"

# Development tasks
nlpai "create a git branch called feature/user-auth"
nlpai "install the requests library and add it to requirements.txt"
nlpai "run my tests and show me only the failures"

# File operations
nlpai "rename all .jpeg files to .jpg in the current folder"
nlpai "create a backup of all my python files"
nlpai "delete all cache folders recursively"

# Network operations
nlpai "check if port 8080 is open"
nlpai "download the file from this url and save it as data.json"
nlpai "what's the response time for google.com"

Interactive Mode

nlpai

> show me the current directory
📁 Current directory: /home/user/projects

> list all python files
📄 Found 15 Python files:
  - main.py
  - utils.py
  ...

> show me the size of the largest one
📊 main.py: 15.3 KB

> open it in vim
✅ Opening main.py in vim...

> exit
👋 Goodbye!

Conversation History

The AI remembers context within a session:

nlpai "create a folder called my_project"
nlpai "go into it"  # Remembers "my_project" from previous command
nlpai "create a python file named main.py"
nlpai "add a hello world function to it"  # Knows which file you're referring to

🎯 Supported Command Categories

System Operations

• File and directory management
• Process management
• System information
• User management
• Environment variables

Network Operations

• IP address information
• Port scanning
• Network connectivity tests
• DNS lookups
• HTTP requests

Development Tools

• Git operations
• Package management (pip, npm, etc.)
• Docker commands
• Code formatting/linting
• Test execution

Data Processing

• CSV/JSON manipulation
• Text file operations
• Data transformation
• Batch file operations

Custom Extensions

• Plugin system for custom handlers
• Easy to add domain-specific commands

🔒 Safety Features

Confirmation Prompts

Dangerous operations require confirmation:

nlpai "delete all files in /tmp"

⚠️  WARNING: This will delete files
Command: rm -rf /tmp/*
Execute? [y/N]:

Dry Run Mode

Test commands without executing:

nlpai --dry-run "remove all .pyc files"

🔍 DRY RUN MODE
Would execute: find . -name "*.pyc" -delete
Affected files: 23 files

Command Logging

All executed commands are logged:

cat ~/.nlpcmd_ai/history.log

2025-01-15 10:23:45 | User: "show my ip" | Executed: ip addr show
2025-01-15 10:24:12 | User: "delete old logs" | Executed: rm logs/*.log.old

🛠️ Advanced Usage

Custom Handlers

Add your own command handlers:

# ~/.nlpcmd_ai/handlers/custom.py

from nlpcmd_ai.handlers.base import BaseHandler

class MyCustomHandler(BaseHandler):
    def can_handle(self, intent: str, params: dict) -> bool:
        return intent == "deploy_app"
    
    def execute(self, params: dict) -> str:
        # Your custom deployment logic
        return "Deployment successful!"

Configuration File

Advanced settings in ~/.nlpcmd_ai/config.yaml:

ai:
  provider: openai
  model: gpt-4-turbo-preview
  temperature: 0.3
  
safety:
  require_confirmation: true
  dangerous_patterns:
    - "rm -rf"
    - "dd if="
    - "mkfs"
  allowed_directories:
    - "/home/user"
    - "/tmp"
    
logging:
  level: INFO
  file: ~/.nlpcmd_ai/nlpcmd.log
  
handlers:
  custom_path: ~/.nlpcmd_ai/handlers

🔄 How It Works

1. Natural Language Input → User types command in plain English
2. AI Processing → LLM analyzes intent and extracts parameters
3. Intent Classification → Determines command category
4. Handler Selection → Routes to appropriate handler
5. Command Generation → Creates safe, executable command
6. Safety Check → Validates and optionally asks for confirmation
7. Execution → Runs command and captures output
8. Response → Formats and displays result to user

📊 Comparison with Traditional CLI Tools

Feature	Traditional CLI	nlpcmd-ai
Input Style	Exact syntax required	Natural language
Learning Curve	Steep	Minimal
Flexibility	Limited to defined patterns	Understands variations
Context Awareness	None	Full conversation history
Error Handling	Cryptic errors	Helpful explanations
Discovery	Man pages/help flags	Just ask what you want

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

• Built on top of powerful LLM APIs
• Inspired by natural human-computer interaction
• Community-driven command handlers

🔗 Links

• Documentation: https://nlpcmd-ai.readthedocs.io
• PyPI: https://pypi.org/project/nlpcmd-ai
• GitHub: https://github.com/yourusername/nlpcmd-ai
• Issues: https://github.com/yourusername/nlpcmd-ai/issues

---

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