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

Fork the repository
Create a feature branch
Add your command patterns
Write tests
Submit a pull request

License

MIT License - see LICENSE file for details.