npm package: @maxbbrown/shello
Description: Your AI shell companion - natural language to shell commands
Author: CLI Assistant Team
Latest version: 1.13.1

# CLI Assistant 🤖

An AI-powered terminal assistant that transforms natural language into shell commands. Built for developers who want to work faster and smarter in the terminal.

## 🌟 Features

### MVP (Current)
- **Natural Language Translation**: Convert plain English to shell commands
- **Context Awareness**: Understands your current directory, git status, and environment
- **Safe Execution**: Dry-run mode and confirmation prompts for destructive commands
- **Error Analysis**: AI-powered error explanation and fixing suggestions
- **Session Memory**: Persistent command history and context
- **Plugin System**: Extensible architecture with Docker and Git plugins

### Coming Soon
- **Multi-step Workflows**: Chain commands together intelligently
- **Cloud Integration**: AWS, GCP, Azure command assistance
- **Team Collaboration**: Shared workflows and best practices
- **Predictive Suggestions**: AI suggests next steps before you ask

## 🚀 Quick Start

### Installation

#### Option 1: Easy Install (Recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/your-username/cli-assistant/main/install.sh | bash
```

#### Option 2: From Source
```bash
git clone https://github.com/your-username/cli-assistant.git
cd cli-assistant
npm install
npm run build
npm link
```

#### Option 3: Via npm (when published)
```bash
npm install -g cli-assistant
```

### Setup

1. **Set your OpenAI API key:**
   ```bash
   cli-ai config set-api-key <your-openai-api-key>
   ```

2. **Start interactive mode:**
   ```bash
   cli-ai
   ```

3. **Or use one-off commands:**
   ```bash
   cli-ai ask "list all files modified in the last 24 hours"
   ```

## 💡 Usage Examples

### Interactive Mode
```bash
$ cli-ai
🤖 CLI Assistant
Your AI-powered terminal assistant

You: show me all git branches
AI: git branch -a
Execute "git branch -a"? (y/N) y
```

### One-off Commands
```bash
# File operations
cli-ai ask "find all JavaScript files larger than 1MB"
cli-ai ask "compress all images in the current directory"

# Git operations  
cli-ai ask "create a new branch called feature-auth"
cli-ai ask "show me what changed in the last commit"

# Docker operations
cli-ai ask "list all running containers with their ports"
cli-ai ask "build and run the app in development mode"

# System operations
cli-ai ask "show me the top 10 processes using the most memory"
cli-ai ask "find which process is using port 3000"
```

### Dry Run Mode
```bash
# See what command would run without executing
cli-ai ask "delete all node_modules folders" --dry-run
```

## 🔧 Configuration

### View Current Config
```bash
cli-ai config show
```

### Available Settings
```bash
# Set API key
cli-ai config set-api-key <key>

# Enable/disable dry run by default
cli-ai config set dry-run true

# Set default model
cli-ai config set model gpt-4

# Set safety level (strict/moderate/permissive)
cli-ai config set safety-level strict
```

## 📚 Advanced Features

### Session Management
```bash
# List recent sessions
cli-ai session list

# Clean up old sessions (older than 30 days)
cli-ai session cleanup --days 30
```

### Plugin System
The CLI Assistant supports plugins for enhanced functionality:

- **Git Plugin**: Enhanced git workflow assistance
- **Docker Plugin**: Container management and operations
- **More coming soon**: AWS, Kubernetes, Terraform plugins

### Safety Features
- **Destructive Command Detection**: Automatically identifies potentially dangerous commands
- **Confirmation Prompts**: Asks for confirmation before executing destructive operations
- **Dry Run Mode**: Preview commands without executing them
- **Command Validation**: Plugins can validate commands before execution

## 🏗️ Development

### Project Structure
```
src/
├── core/           # Core functionality
│   ├── ai-service.ts      # LLM integration
│   ├── context.ts         # Context awareness
│   ├── executor.ts        # Command execution
│   ├── session-manager.ts # Session persistence
│   └── config.ts          # Configuration management
├── plugins/        # Plugin system
│   ├── base-plugin.ts     # Plugin base class
│   ├── docker-plugin.ts   # Docker integration
│   ├── git-plugin.ts      # Git integration
│   └── plugin-manager.ts  # Plugin management
├── types/          # TypeScript definitions
└── cli.ts          # CLI interface
```

### Running in Development
```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint
```

### Creating Plugins
```typescript
import { BasePlugin } from './base-plugin';
import { CommandContext, AIResponse } from '../types';

export class MyPlugin extends BasePlugin {
  name = 'my-plugin';
  version = '1.0.0';
  description = 'My custom plugin';

  async suggestCommands(userInput: string, context: CommandContext): Promise<AIResponse[]> {
    // Your plugin logic here
    return [];
  }
}
```

## 🔒 Privacy & Security

- **Local First**: All session data stored locally on your machine
- **API Key Security**: Keys stored securely in local config
- **Command Validation**: Multiple safety checks before execution
- **No Data Collection**: We don't collect or store your commands or data

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

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

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/maxbbrown03/cli-assistant/issues)
- **Discussions**: [GitHub Discussions](https://github.com/maxbbrown03/cli-assistant/discussions)
- **Email**: support@cli-assistant.dev

## 🗺️ Roadmap

### Phase 1 (MVP) ✅
- [x] Natural language to command translation
- [x] Context awareness (git, cwd, env)
- [x] Safe execution with confirmations
- [x] Error analysis and suggestions
- [x] Basic plugin system

### Phase 2 (3-6 months)
- [ ] Multi-step workflow automation
- [ ] Cloud provider integrations (AWS, GCP, Azure)
- [ ] Enhanced plugin ecosystem
- [ ] Team collaboration features
- [ ] Performance optimizations

### Phase 3 (6-12 months)
- [ ] Predictive command suggestions
- [ ] Enterprise features (audit logs, policies)
- [ ] Advanced workflow templates
- [ ] Integration with popular DevOps tools
- [ ] Mobile companion app

## 🙏 Acknowledgments

- OpenAI for providing the GPT models
- The open-source community for inspiration and tools
- Early beta testers for feedback and bug reports

---

**Made with ❤️ for developers who love the terminal**