nl2cmd 1.1.0
Natural language to terminal command translation tool
Requires Python: >=3.8
Keywords: cli, natural-language, terminal, commands, translation

# nl2cmd

A natural language to terminal command translation tool that helps you convert plain English descriptions into appropriate terminal commands based on your operating system.

## Features

- **Multi-platform support**: Automatically detects and adapts to Linux, macOS, and Windows
- **Natural language processing**: Understands common phrases and descriptions
- **Smart intent detection**: Maps your description to the most appropriate command
- **Command explanations**: Provides detailed breakdowns of generated commands
- **Alternative suggestions**: Offers multiple approaches when available
- **CLI interface**: Easy-to-use command-line tool

## Installation

### From PyPI (when published)

```bash
pip install nl2cmd
```

### From source

```bash
git clone https://github.com/yourusername/nl2cmd.git
cd nl2cmd
pip install -e .
```

## Usage

### Command Line Interface

```bash
# Basic usage
nl2cmd "show current directory"
nl2cmd "list files in this folder"
nl2cmd "create a new directory called test"

# With options
nl2cmd --explain "remove all files in current directory"
nl2cmd --json "show running processes"
nl2cmd --os linux "list network connections"
```

### Python API

```python
from nl2cmd import NL2Cmd

# Initialize translator
translator = NL2Cmd()

# Translate natural language to command
result = translator.translate("show current directory")
print(f"Command: {result.command}")
print(f"Explanation: {result.explanation}")

# Override OS for testing
translator = NL2Cmd(forced_os="windows")
result = translator.translate("list files")
print(f"Windows command: {result.command}")
```

## Supported Commands

The tool recognizes and translates various types of operations:

### File Operations
- List files and directories (`ls`, `dir`)
- Change directories (`cd`)
- Create directories (`mkdir`)
- Remove files (`rm`, `del`)
- Copy files (`cp`, `copy`)
- Move/rename files (`mv`, `move`)

### System Information
- Current working directory (`pwd`, `cd`)
- Process management (`ps`, `tasklist`)
- Network information (`netstat`, `ss`)
- Disk and memory usage (`df`, `du`)

### Package Management
- Install packages (`apt`, `brew`, `winget`)
- Update packages (`apt update`, `brew upgrade`)

### Git Operations
- Status, pull, push, clone
- Branch management
- Commit history

### Docker Operations
- Container management
- Image operations
- Build and run commands

## Examples

| Natural Language | Linux/macOS | Windows | Explanation |
|------------------|-------------|---------|-------------|
| "show current directory" | `pwd` | `cd` | Display current working directory |
| "list files" | `ls` | `dir` | List contents of current directory |
| "create folder test" | `mkdir test` | `mkdir test` | Create a new directory |
| "remove file.txt" | `rm file.txt` | `del file.txt` | Delete a file |
| "copy source to dest" | `cp source dest` | `copy source dest` | Copy files |

## Development

### Setup Development Environment

```bash
git clone https://github.com/yourusername/nl2cmd.git
cd nl2cmd
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Code Formatting

```bash
black src/ tests/
flake8 src/ tests/
mypy src/
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by the need to make terminal commands more accessible
- Built with modern Python packaging standards
- Uses semantic matching for natural language understanding

## Roadmap

- [ ] Expand command coverage
- [ ] Add interactive mode
- [ ] Support for command chaining
- [ ] Integration with shell history
- [ ] Machine learning improvements
- [ ] Plugin system for custom commands