shell-command-generator-cli/app

ShellGen - Shell Command Generator CLI

A CLI tool that converts natural language descriptions into shell commands using local LLMs (Ollama, Llama.cpp). Describe what you want in plain English, and ShellGen generates the appropriate shell command with explanations.

Features

• Natural Language to Command: Convert plain English descriptions to shell commands
• Multiple LLM Backends: Support for both Ollama and Llama.cpp
• Safety First: Dangerous commands are flagged before execution
• Command History: Track generated commands and learn from corrections
• Shell Compatibility: Generate commands for Bash and Zsh
• Local Processing: All processing happens locally - no external API calls

Installation

From Source

git clone https://github.com/yourusername/shell-command-generator-cli.git
cd shell-command-generator-cli
pip install -e .

Prerequisites

• Python 3.10+
• Ollama (for Ollama backend) or Llama.cpp
• Required Python packages (installed automatically)

Quick Start

Basic Usage

# Generate a command
shellgen "find all python files in current directory"

# Generate for specific shell
shellgen --shell zsh "list files with detailed info"

# Execute immediately (safe commands only)
shellgen --auto-execute "show current directory"

Using Different Backends

# Use Ollama backend (default)
shellgen --backend ollama "create a new git branch"

# Use Llama.cpp backend
shellgen --backend llama_cpp "find files modified today"

Command History

# View command history
shellgen history

# View last 50 entries
shellgen history --limit 50

# Provide feedback on a generated command
shellgen feedback 5 --corrected "find . -name '*.py' -type f"

Configuration

Environment Variables

Variable	Default	Description
OLLAMA_HOST	localhost:11434	Ollama API endpoint
OLLAMA_MODEL	codellama	Default model name
SHELLGEN_HISTORY_PATH	~/.shellgen/history.db	History database path
SHELLGEN_TEMPLATES_PATH	~/.shellgen/templates	Custom templates path

Config File

Copy .env.example to .env and modify:

cp .env.example .env

Create or edit config.yaml for additional settings:

default_backend: ollama
shell:
  default: bash
  supported:
    - bash
    - zsh
safety:
  auto_execute_safe: false
  require_confirmation: true

Safety Features

ShellGen includes a safety system that:

1. Detects Dangerous Patterns: Blocks commands like rm -rf, dd, mkfs, etc.
2. Safe Command Whitelist: Automatically approves common safe operations
3. Confirmation Workflow: Prompts before executing potentially risky commands
4. Force Flag: Use --force to bypass safety checks (not recommended)

Dangerous Commands Blocked

• rm -rf on root or system directories
• dd operations on system devices
• Disk formatting commands
• Fork bombs and other destructive patterns

Command History

ShellGen stores your command history in an SQLite database, allowing you to:

• Review previously generated commands
• Track which commands were executed
• Provide feedback on incorrect generations
• Learn from your corrections

Database Location

Default: ~/.shellgen/history.db

Feedback System

When a generated command isn't quite right, use the feedback system:

# Submit correction
shellgen feedback 3 --corrected "find . -name '*.txt' -delete"

# Add notes
shellgen feedback 3 --feedback "The original command had wrong flags"

Backend Selection

Ollama

Ollama provides an easy-to-use API for local models:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama server
ollama serve

# Pull a model
ollama pull codellama

Recommended models:

• codellama - Best for code-related commands
• llama2 - General purpose
• mistral - Fast and capable

Llama.cpp

For direct model execution without API server:

# Install llama-cpp-python
pip install llama-cpp-python

# Download a model (e.g., from Hugging Face)
# Place in ~/.cache/llama-cpp/models/

Examples

File Operations

shellgen "find all Python files larger than 1MB"
# Output: find . -name '*.py' -size +1M

shellgen "list directories sorted by size"
# Output: du -h --max-depth=1 | sort -h

Git Operations

shellgen "show uncommitted changes"
# Output: git diff

shellgen "list all branches merged into main"
# Output: git branch --merged main

System Monitoring

shellgen "show processes using most memory"
# Output: ps aux --sort=-%mem | head -10

shellgen "check disk space usage"
# Output: df -h

Development

Running Tests

pytest tests/ -v
pytest tests/ --cov=shellgen --cov-report=term-missing

Project Structure

shellgen/
├── __init__.py          # Main package
├── main.py              # CLI entry point
├── config.py            # Configuration management
├── history.py           # History database
├── core/
│   ├── __init__.py
│   ├── generator.py     # Command generation logic
│   └── prompts.py       # Prompt templates
├── backends/
│   ├── __init__.py
│   ├── base.py          # Abstract backend interface
│   ├── ollama.py        # Ollama backend
│   ├── llama_cpp.py     # Llama.cpp backend
│   └── factory.py       # Backend factory
├── safety/
│   ├── __init__.py
│   └── checker.py       # Safety checking
└── ui/
    ├── __init__.py
    ├── console.py       # Rich console UI
    └── argparse.py      # Argument parsing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest tests/ -v
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Disclaimer

Always review generated commands before execution. While safety checks are in place, always verify that commands do what you expect, especially when using --force or --execute flags.