nlsh 0.1.1

# RustShell

![CI](https://github.com/EfeDurmaz16/rustshell/workflows/CI/badge.svg)
[![Crates.io](https://img.shields.io/crates/v/rustshell.svg)](https://crates.io/crates/rustshell)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**The intelligent shell that speaks your language. Built with Rust. Powered by AI. Open Source.**

RustShell is an AI-powered cross-platform shell utility that lets you write commands in natural language. Instead of memorizing complex syntax for different operating systems, simply describe what you want to do, and RustShell translates it into the appropriate shell commands for your platform.

## Features

- **AI-Powered Natural Language Processing**: Convert plain English descriptions into shell commands with support for multiple LLM providers (Groq, Ollama, OpenAI, Anthropic)
- **Cross-Platform Support**: Seamless support for Windows, Linux, and macOS with platform-specific optimizations
- **Flexible Execution Modes**: `approve` (confirm before executing), `auto` (execute immediately), or `dry-run` (preview only)
- **Fuzzy Command Completion**: Intelligent matching finds what you mean even with typos
- **Enhanced Alias System**: Create parametric aliases, organize them into groups, and import/export configurations
- **Plugin System**: Extend RustShell with subprocess-based plugins using the `rustshell-plugin-*` naming convention
- **Script Mode**: Write `.rsh` script files for automation and batch processing
- **Command Context Memory**: Maintains context from previous commands for smarter suggestions
- **Colored Terminal Output**: Beautiful, readable output with Dracula-themed color support
- **Shell Completions**: First-class support for bash, zsh, fish, and powershell
- **Opt-in Telemetry**: Privacy-respecting, local usage tracking for insights and improvements

## Installation

### From Crates.io

The easiest way to install RustShell:

```bash
cargo install rustshell
```

### Build from Source

Clone the repository and build locally:

```bash
git clone https://github.com/EfeDurmaz16/rustshell
cd rustshell
cargo install --path .
```

This will compile RustShell and add it to your Cargo bin directory (typically `~/.cargo/bin`).

## Quick Start

### Basic Usage

Start with interactive mode (no arguments):

```bash
rustshell
```

Execute a natural language command:

```bash
rustshell "list files in current directory"
```

With different execution modes:

```bash
# Approve mode (default) - confirms before execution
rustshell --mode approve "kill process on port 3000"

# Auto mode - executes immediately
rustshell --mode auto "create backup of config"

# Dry-run mode - preview without executing
rustshell --dry-run "compress all log files"
```

### Interactive Mode

Start an interactive session with tab completion and history:

```bash
rustshell
```

Features:
- Type natural language commands
- Press `Tab` for command suggestions and file completions
- Use arrow keys to navigate history
- Press `Ctrl+C` to exit
- Command context from previous commands for smarter suggestions

### Natural Language Examples

RustShell understands a wide variety of natural language descriptions:

```bash
# File operations
rustshell "create a new directory called my_project"
rustshell "show me all python files in the current folder"
rustshell "copy all text files to the backup directory"
rustshell "list files sorted by modification time"

# System operations
rustshell "check disk usage"
rustshell "show running processes"
rustshell "find large files in home directory"

# Development tasks
rustshell "install npm dependencies"
rustshell "build the project in release mode"
rustshell "run tests and show coverage"
```

## LLM Providers

RustShell supports multiple AI providers for natural language processing:

| Provider | Default Model | Environment Variable | Best For |
|----------|---------------|----------------------|----------|
| **Groq** | llama-3.1-70b-versatile | `GROQ_API_KEY` | Fast inference, free tier available |
| **OpenAI** | gpt-3.5-turbo | `OPENAI_API_KEY` | High accuracy, many models |
| **Anthropic** | claude-3-sonnet-20240229 | `ANTHROPIC_API_KEY` | Advanced reasoning capabilities |
| **Ollama** | llama2 | `OLLAMA_ENDPOINT` | Local/offline execution, privacy-focused |

### Setting Up Your Provider

1. Choose a provider and obtain an API key (or run Ollama locally)
2. Set the environment variable in your shell profile:

```bash
# For Groq (recommended for getting started)
export GROQ_API_KEY="your-api-key-here"

# For OpenAI
export OPENAI_API_KEY="sk-..."

# For Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# For Ollama (local/self-hosted)
export OLLAMA_ENDPOINT="http://localhost:11434"
```

3. Configure RustShell in `~/.rustshell/config.toml` (see Configuration section below)

## Configuration

### Configuration File

Create or edit `~/.rustshell/config.toml` to customize RustShell behavior:

```toml
[llm]
provider = "groq"                          # groq, ollama, openai, anthropic
model = "llama-3.1-70b-versatile"
api_key_env = "GROQ_API_KEY"               # Environment variable name
endpoint = ""                              # Optional custom endpoint
timeout_seconds = 30
max_tokens = 150
temperature = 0.1
enable_cache = true

[safety]
require_confirmation = ["rm", "delete", "format", "sudo"]
dangerous_patterns = ["rm -rf /", "format c:", "sudo rm"]
enable_dry_run = true
block_destructive = false

[features]
enable_llm = true
fallback_to_traditional = true
offline_mode = false
enable_history = true
context_commands = 3                       # Number of previous commands to use as context
execution_mode = "approve"

[ui]
show_hints = true
colored_output = true
verbose_mode = false
confirm_destructive = true
```

### Environment Variables

RustShell looks for configuration in this order:

1. `.env` file in current directory
2. `.env` file in `~/.rustshell/`
3. `.env` file in home directory
4. System environment variables

Example `.env` file:

```bash
GROQ_API_KEY=gsk_...
RUSTSHELL_MODE=approve
RUSTSHELL_COLORED_OUTPUT=true
```

## Advanced Features

### Alias System

Create shortcuts for frequently used commands:

```bash
# Create an alias
rustshell alias myfiles "list | grep .txt"

# Create a parametric alias
rustshell alias search "grep -r $1 ."

# Use the alias
rustshell myfiles
rustshell search "pattern"

# List all aliases
rustshell alias

# Remove an alias
rustshell unalias myfiles
```

Aliases are stored in `~/.rustshell_aliases` and persist across sessions.

### Script Mode

Write reusable scripts in `.rsh` format:

```bash
# script.rsh - Automated backup script
set BACKUP_DIR=/backup/data

# Comments start with #
create $BACKUP_DIR

# Natural language commands
copy ./data $BACKUP_DIR/$(date)
echo "Backup completed"

# Set and use variables
set ARCHIVE_NAME=backup-$(date +%Y%m%d)
compress $BACKUP_DIR $ARCHIVE_NAME
```

Execute the script:

```bash
rustshell script ./script.rsh
```

### Shell Completions

Install shell completions for faster command entry and better integration:

```bash
# Bash
rustshell completions bash --install

# Zsh
rustshell completions zsh --install

# Fish
rustshell completions fish --install

# PowerShell
rustshell completions powershell --install
```

Or generate completions manually:

```bash
rustshell completions bash > ~/.bash_completion.d/rustshell
rustshell completions zsh > ~/.zsh/completions/_rustshell
rustshell completions fish > ~/.config/fish/completions/rustshell.fish
```

### Plugin Development

Extend RustShell with custom plugins using a simple subprocess-based architecture.

#### Plugin Naming Convention

Plugins must follow the naming pattern: `rustshell-plugin-<name>`

#### Creating a Plugin

1. Create an executable program (in any language) named `rustshell-plugin-myfeature`
2. Place it in `~/.rustshell/plugins/` or anywhere in your `$PATH`
3. The plugin must support the `--rustshell-manifest` flag to return its capabilities

#### Plugin Manifest Format

Your plugin should return JSON when called with `--rustshell-manifest`:

```bash
./rustshell-plugin-myfeature --rustshell-manifest
```

Response format:

```json
{
  "name": "myfeature",
  "version": "1.0.0",
  "description": "Extended functionality for RustShell",
  "commands": [
    {
      "name": "advanced-search",
      "description": "Search files with advanced filters"
    }
  ]
}
```

#### Example Plugin (Bash)

```bash
#!/bin/bash
# rustshell-plugin-mytool

if [[ "$1" == "--rustshell-manifest" ]]; then
  cat <<EOF
{
  "name": "mytool",
  "version": "1.0.0",
  "description": "Custom utility plugin",
  "commands": [
    {
      "name": "custom-cmd",
      "description": "Do something custom"
    }
  ]
}
EOF
else
  # Handle actual command execution
  echo "Executing custom command with args: $@"
fi
```

RustShell automatically discovers plugins and makes their commands available in the natural language processor.

## Built-in Commands

RustShell includes cross-platform built-in commands that work consistently across Windows, Linux, and macOS:

| Command | Aliases | Description |
|---------|---------|-------------|
| `make_dir` | `mkdir` | Create a directory |
| `create_file` | `touch` | Create an empty file |
| `copy` | | Copy a file |
| `move` | | Move a file or directory |
| `delete_file` | `rm` | Delete a file |
| `delete_dir` | `rmdir` | Delete a directory |
| `change_dir` | `cd` | Change current directory |
| `list` | `ls` | List directory contents |
| `where_am_i` | `pwd` | Show current directory |
| `show` | `cat` | Display file contents |
| `find` | | Find files matching a pattern |
| `compress` | `zip` | Create a zip archive |
| `alias` | | Create or list aliases |
| `unalias` | | Remove an alias |
| `pipe` | | Connect commands with pipes |
| `plugin` | `plugins` | Manage and run plugins |
| `help` | | Show help message |
| `showall` | | Display all available commands |

These commands are translated to platform-specific implementations automatically.

## Safety Features

RustShell includes several safety mechanisms to prevent accidental command execution:

- **Confirmation Required**: Dangerous commands (rm, delete, format, sudo) require confirmation
- **Dry-Run Mode**: Preview commands before execution with `--dry-run` flag
- **Pattern Blocking**: Configure dangerous command patterns to block
- **Destructive Mode Control**: Enable/disable destructive operations via config
- **Natural Language Validation**: AI validates command translations before execution

## Performance Optimizations

- **LLM Response Caching**: Frequently used commands are cached to reduce API calls and latency
- **Fuzzy Matching**: Fast, intelligent command matching with typo correction
- **Cross-Platform Optimization**: Platform-specific implementations for best performance
- **Async I/O**: Non-blocking command execution and API calls using Tokio

## Built With

RustShell is built with excellent Rust libraries:

- **[Clap](https://docs.rs/clap/)** - Command-line argument parsing
- **[Crossterm](https://docs.rs/crossterm/)** - Terminal manipulation and colors
- **[Reqwest](https://docs.rs/reqwest/)** - HTTP client for LLM API calls
- **[Tokio](https://tokio.rs/)** - Async runtime for concurrent operations
- **[Rustyline](https://docs.rs/rustyline/)** - Interactive readline library
- **[Serde](https://serde.rs/)** - Serialization/deserialization framework
- **[Fuzzy Matcher](https://docs.rs/fuzzy-matcher/)** - Fuzzy string matching

## Contributing

We welcome contributions to RustShell! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:

- Filing issues and feature requests
- Submitting pull requests
- Development setup
- Code style and testing

## Community

- **GitHub Issues**: [Report bugs or request features](https://github.com/EfeDurmaz16/rustshell/issues)
- **Discussions**: [Join our community discussions](https://github.com/EfeDurmaz16/rustshell/discussions)

## Troubleshooting

### "LLM API key not found"
Make sure your API key is set in the environment. Check your configuration:
```bash
echo $GROQ_API_KEY    # or your provider's key variable
cat ~/.rustshell/config.toml
```

### "Command translation failed"
Try the `--dry-run` mode to see what command was generated:
```bash
rustshell --dry-run "your command"
```

### "Command not found"
Enable `fallback_to_traditional = true` in your config to allow traditional command parsing as a fallback.

### Shell completions not working
Ensure you've installed completions correctly:
```bash
rustshell completions bash --install
# Then restart your shell or source your profile
```

## License

RustShell is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes and features.

## Author

Created by [Efe Baran Durmaz](https://github.com/EfeDurmaz16)

---

Made with care for developers who want to code faster, smarter, and more intuitively.