naturalshell-mac 1.0.2

Natural language to shell command converter with bilingual support

NaturalShell (NS)

Natural Language to Shell Command Converter with Bilingual Support

Note: This is currently a BETA version.

NaturalShell (NS) is a CLI tool that can convert natural language descriptions into shell commands. Optimized for macOS terminal usage with bilingual support (English and Traditional Chinese).

---

Key Features

• Bilingual Support: Full support for both Traditional Chinese and English commands
• High Accuracy: 93.8% accuracy on 500 test cases
• Smart Filtering: Rule-based pre-filtering layer to reject irrelevant requests
• macOS Optimized: Specifically designed for macOS terminal usage
• Safety First: Two-stage verification mechanism ensures command safety
• Runs Locally: Powered by Apple MLX framework, runs completely offline after initial setup
• Lightweight Model: Based on Qwen2.5-3B-Instruct with LoRA fine-tuning

---

Installation

Requirements

• Operating System: macOS (Apple Silicon or Intel)
• Python: 3.9 or higher
• RAM: 8GB+ recommended

Install via pip

pip install naturalshell-mac

After installation, the ns command will be available.

Shell Integration

Important: Shell Integration is required for commands like cd and export to properly affect your current shell session.

To integrate NS into your shell:

# Display integration commands
ns --init

# Add to your shell configuration
# For Zsh (default macOS shell):
ns --init >> ~/.zshrc
source ~/.zshrc

# For Bash:
ns --init >> ~/.bashrc
source ~/.bashrc

---

Quick Start

Basic Usage

Simply type natural language commands in your terminal:

# English examples
ns list all files in current directory
# Output: ls -la

ns find all Python files
# Output: find . -name "*.py"

ns show disk usage
# Output: df -h

# Additional examples
ns list all files in the current folder
# Output: ls -la

ns go to Desktop folder
# Output: cd ~/Desktop

ns search for all Python files
# Output: find . -name "*.py"

ns copy this file to Downloads folder
# Output: cp <file> ~/Downloads/

ns delete temporary files
# Output: rm -rf /tmp/*

---

Examples

File Operations

ns create a new folder called "project"
# mkdir project

ns copy all jpg files to Desktop
# cp *.jpg ~/Desktop/

ns find files modified in last 24 hours
# find . -mtime -1

Git Operations

ns show git status
# git status

ns commit with message "fix bug"
# git commit -m "fix bug"

System Information

ns show CPU usage
# top -l 1 | grep "CPU usage"

ns check available disk space
# df -h

Package Management

ns install python using brew
# brew install python

ns update all brew packages
# brew upgrade

---

Technical Architecture

Two-Stage Pipeline

1. Stage 1: Rule-based Filter

   • Quickly validates if requests are shell-command related
   • Includes shell keywords, Chinese keywords, and path pattern detection
   • Rejects irrelevant requests (e.g., weather queries, poetry composition)

2. Stage 2: AI Model Inference

   • Uses Qwen2.5-3B-Instruct base model
   • LoRA fine-tuned adapters (optimized for macOS shell commands)
   • Apple MLX framework for accelerated inference

Model Specifications

• Base Model: Qwen/Qwen2.5-3B-Instruct
• Fine-tuning Method: LoRA (Low-Rank Adaptation)
• Framework: Apple MLX
• Training Data: Specialized macOS shell command dataset
• Accuracy: 93.8% (500 test cases)

---

Supported Command Types

• File & Directory Operations: ls, cd, mkdir, rm, cp, mv, find, grep
• Version Control: git related commands
• Package Management: brew, pip, npm, yarn
• System Info: top, ps, df, du
• macOS Specific: open, pbcopy, pbpaste, defaults
• Network Tools: curl, wget, ssh, ping
• Compression: tar, zip, unzip, gzip
• Text Processing: cat, head, tail, awk, sed

---

Safety Mechanisms

1. Rule Filter: Rejects non-shell related requests
2. Command Validation: AI model trained to emphasize safe command generation
3. No Auto-execution: Commands are only displayed by default, requiring manual execution or confirmation
4. Scope Limitation: Only processes macOS shell command related requests

---

Development & Contributing

Local Development

# Clone repository
git clone https://github.com/brianchanyan/naturalshell.git
cd naturalshell

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/

Testing

# Test the rule-based filter
python naturalshell/shell_filter.py

# Test the full pipeline
ns "your test query"

---

Troubleshooting

Model Download Issues

On first run, NS will automatically download the Qwen2.5-3B-Instruct model (approximately 6GB). If download fails:

# Manually download model
python3 -c "from mlx_lm import load; load('Qwen/Qwen2.5-3B-Instruct')"

Out of Memory

If you encounter memory issues, try closing other applications or restarting your terminal.

---

Known Limitations

• macOS only (depends on MLX framework)
• Requires sufficient memory (8GB+ recommended)
• First run requires downloading approximately 6GB model
• Does not support complex multi-line script generation

---

Changelog

v1.0.2 (2026-02-22)

• Added ns --uninstall command to cleanly remove shell integration
• Added uninstall guide to tutorial page

v1.0.1 (2026-02-22)

• Fix: Shell integration now uses python3 to invoke script (no execute permission needed)
• Improved pip install experience for all users

v1.0.0 (2026-02-21)

• Initial release
• 93.8% accuracy
• Bilingual support (English and Traditional Chinese)
• Two-stage processing architecture
• Complete macOS shell command support

---

License

MIT License - See LICENSE file for details

---

Author

Brian - GitHub

---

Acknowledgments

• Qwen Team - For providing excellent base model
• Apple MLX - For efficient machine learning framework
• Community Contributors - Thanks for all testing and feedback

---

Links

• PyPI Package
• GitHub Repository
• Issue Tracker
• Documentation