@maxbbrown/shello

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)

curl -fsSL https://raw.githubusercontent.com/your-username/cli-assistant/main/install.sh | bash

Option 2: From Source

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)

npm install -g cli-assistant

Setup

• Set your OpenAI API key:

  cli-ai config set-api-key <your-openai-api-key>
  

• Start interactive mode:

  cli-ai
  

• Or use one-off commands:

  cli-ai ask "list all files modified in the last 24 hours"
  

💡 Usage Examples

Interactive Mode

$ 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

# 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

# See what command would run without executing
cli-ai ask "delete all node_modules folders" --dry-run

🔧 Configuration

View Current Config

cli-ai config show

Available Settings

# 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

# 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

# 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

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

Development Setup

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

🗺️ Roadmap

Phase 1 (MVP) ✅

• Natural language to command translation
• Context awareness (git, cwd, env)
• Safe execution with confirmations
• Error analysis and suggestions
• 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