shell-speak/README.md

# Shell Speak

A CLI tool that converts natural language descriptions into shell commands. Uses local pattern matching without APIs. Supports docker, kubectl, git, and unix utilities. Includes interactive mode, command history, and learning from user corrections.

## Features

- **Natural Language Parsing**: Convert plain English to shell commands
- **Multi-tool Support**: Docker, kubectl, Git, and Unix utilities
- **Interactive Mode**: REPL-like interface with auto-completion and history
- **Learning System**: Teach the tool new commands from your corrections
- **Command History**: Persistent history of all conversions
- **Rich Output**: Beautiful syntax-highlighted command display

## Installation

```bash
pip install shell-speak
```

Or from source:

```bash
pip install -e .
```

## Quick Start

### Single Command Conversion

```bash
# Convert a natural language query to a command
shell-speak "list running docker containers"

# Filter by specific tool
shell-speak --tool docker "show all containers"

# Get detailed explanation
shell-speak --explain "commit changes with message 'fix bug'"
```

### Interactive Mode

Enter interactive mode for a REPL-like experience:

```bash
shell-speak interactive
# or just
shell-speak
```

In interactive mode:
- Type natural language queries
- Use up/down arrows to navigate command history
- Tab for auto-completion
- `help` for available commands
- `exit` to quit

## Usage

### Command Reference

| Command | Description |
|---------|-------------|
| `shell-speak "query"` | Convert query to command |
| `shell-speak interactive` | Enter interactive mode |
| `shell-speak history` | View command history |
| `shell-speak learn "query" "command"` | Teach a new pattern |
| `shell-speak forget "query"` | Remove a learned pattern |
| `shell-speak tools` | List supported tools |
| `shell-speak reload` | Reload command libraries |

### Options

| Option | Description |
|--------|-------------|
| `--tool, -t` | Filter by tool (docker/kubectl/git/unix) |
| `--explain, -e` | Show detailed explanation |
| `--dry-run, -n` | Preview without executing |
| `--version, -V` | Show version |
| `--help` | Show help |

### Examples

```bash
# Docker commands
shell-speak "list running containers"
shell-speak "stop container nginx"
shell-speak "build image with tag myapp:latest"

# Kubernetes commands
shell-speak "get pods in default namespace"
shell-speak "describe deployment myapp"
shell-speak "scale deployment to 3 replicas"

# Git commands
shell-speak "commit changes with message 'fix bug'"
shell-speak "push to origin main"
shell-speak "create new branch feature/auth"

# Unix commands
shell-speak "list files with details"
shell-speak "find files named *.py"
shell-speak "search for pattern in files"
```

## Interactive Mode

Interactive mode provides a rich shell-like experience:

```
$ shell-speak
[shell-speak]>> list running containers
[docker] command
+------------------+
| docker ps        |
+------------------+

[shell-speak]>> help
[shell-speak]>> help
```

### Interactive Commands

| Command | Description |
|---------|-------------|
| `help` | Show help message |
| `clear` | Clear screen |
| `history` | Show command history |
| `repeat <n>` | Repeat nth command from history |
| `learn <query>::<command>::<tool>` | Learn new pattern |
| `forget <query>` | Forget a pattern |
| `exit` | Exit interactive mode |

## Learning from Corrections

Shell Speak can learn from your corrections. When the suggested command isn't quite right, teach it the correct version:

```bash
# In interactive mode
shell-speak>> learn "deploy to prod" "kubectl apply -f prod/" "kubectl"
```

Or via CLI:

```bash
shell-speak learn "deploy to prod" "kubectl apply -f prod/" --tool kubectl
```

## Command Library

Shell Speak includes extensive command libraries for:

### Docker
- Container management (ps, run, stop, rm)
- Image operations (pull, build, push)
- Docker Compose commands
- Volume and network management

### Kubernetes
- Pod operations (get, describe, logs, exec)
- Deployment management
- Service and ingress operations
- ConfigMaps and Secrets
- Cluster information

### Git
- Commit and push operations
- Branch management
- Merge and rebase
- Stash and tag operations
- Remote management

### Unix
- File and directory operations
- Search and find commands
- Process management
- Network utilities
- Archive operations

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SHELL_SPEAK_DATA_DIR` | Data directory for libraries | `~/.local/share/shell-speak` |
| `SHELL_SPEAK_HISTORY_FILE` | History file path | `~/.local/share/shell-speak/history.json` |
| `SHELL_SPEAK_CORRECTIONS_FILE` | Corrections file path | `~/.local/share/shell-speak/corrections.json` |

## Testing

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=shell_speak --cov-report=term-missing

# Run specific test file
pytest tests/test_pattern_matching.py -v
```

## Extending the Command Library

Add custom command patterns by creating YAML files in the data directory:

```yaml
version: "1.0"
description: Custom commands

patterns:
  - name: my_custom_command
    description: A custom command
    patterns:
      - do something custom
      - run my command
    template: my_command --option {value}
    explanation: What this command does
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your command patterns
4. Write tests
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.