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

pip install shell-speak

Or from source:

pip install -e .

Quick Start

Single Command Conversion

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

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

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

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

Or via CLI:

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

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

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 file for details.