nlsh 0.1.0

AI-powered cross-platform shell utility with natural language command processing
nlsh-0.1.0 is not a library.

RustShell

CI Crates.io License: MIT

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:

cargo install rustshell

Build from Source

Clone the repository and build locally:

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):

rustshell

Execute a natural language command:

rustshell "list files in current directory"

With different execution modes:

# 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:

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:

# 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:
# 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"
  1. Configure RustShell in ~/.rustshell/config.toml (see Configuration section below)

Configuration

Configuration File

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

[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:

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

Advanced Features

Alias System

Create shortcuts for frequently used commands:

# 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:

# 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:

rustshell script ./script.rsh

Shell Completions

Install shell completions for faster command entry and better integration:

# Bash
rustshell completions bash --install

# Zsh
rustshell completions zsh --install

# Fish
rustshell completions fish --install

# PowerShell
rustshell completions powershell --install

Or generate completions manually:

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:

./rustshell-plugin-myfeature --rustshell-manifest

Response format:

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

Example Plugin (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 - Command-line argument parsing
  • Crossterm - Terminal manipulation and colors
  • Reqwest - HTTP client for LLM API calls
  • Tokio - Async runtime for concurrent operations
  • Rustyline - Interactive readline library
  • Serde - Serialization/deserialization framework
  • Fuzzy Matcher - Fuzzy string matching

Contributing

We welcome contributions to RustShell! Please see CONTRIBUTING.md for guidelines on:

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

Community

Troubleshooting

"LLM API key not found"

Make sure your API key is set in the environment. Check your configuration:

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:

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:

rustshell completions bash --install
# Then restart your shell or source your profile

License

RustShell is licensed under the MIT License. See LICENSE for details.

Changelog

See CHANGELOG.md for a detailed history of changes and features.

Author

Created by Efe Baran Durmaz

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