ScriptMate

🤖 Your Intelligent Script Partner - Making command-line collaboration as seamless as working with a trusted companion

Overview

ScriptMate is your intelligent script partner, making command-line collaboration as seamless as working with a trusted companion. It understands natural language descriptions and generates corresponding shell commands. Whether you're a beginner or an experienced developer, ScriptMate helps you quickly find and execute the right commands.

✨ Features

• 🤖 Natural Language Understanding: Supports natural language descriptions to understand user intent
• 🔧 Cross-Platform: Works on Windows, macOS, and Linux
• 🛡️ Safe Execution: Requires user confirmation before execution for security
• 📝 Detailed Explanations: Provides detailed explanations and reasoning process
• ⚙️ Flexible Configuration: Supports multiple LLM service providers
• 🎨 Rich Interface: Beautiful terminal output with colors and icons
• 📊 Command History: Track and review executed commands
• 🔍 Dry Run Mode: Preview commands without execution

🚀 Installation

Using pip

pip install scriptmate

Using uv

uv add scriptmate

From Source

git clone https://github.com/your-username/scriptmate.git
cd scriptmate
uv sync
uv pip install -e .

🎯 Quick Start

1. Initial Setup

On first use, ScriptMate will guide you through the configuration:

scriptmate generate "show current user"

You'll be prompted to enter:

• API Key: Your LLM service API key
• Model Name: e.g., gpt-3.5-turbo, gpt-4
• Base URL: e.g., https://api.openai.com/v1

2. Basic Usage

# Generate and execute commands
scriptmate generate "show current user"
scriptmate generate "list files in current directory"
scriptmate generate "check disk usage"

# Preview without execution (dry run)
scriptmate generate --dry-run "find all Python files"

# Auto-confirm execution
scriptmate generate -y "show system time"

3. Configuration Management

# Show current configuration
scriptmate config show

# Setup new configuration
scriptmate config setup

# Test configuration
scriptmate config test

# Reset configuration
scriptmate config reset

4. System Information

# Show version
scriptmate --version

# Show system info
scriptmate info

# Show command history
scriptmate history

📋 Command Examples

# File Operations
scriptmate generate "find all .py files recursively"
scriptmate generate "show file permissions of current directory"
scriptmate generate "compress folder into zip"

# System Monitoring
scriptmate generate "show memory usage"
scriptmate generate "list running processes"
scriptmate generate "check network connections"

# Git Operations
scriptmate generate "show git status with colors"
scriptmate generate "create new branch and switch to it"

# Network Operations
scriptmate generate "ping google.com 5 times"
scriptmate generate "download file from URL"

⚙️ Configuration

Configuration is stored in ~/.scriptmate/config.json:

{
    "api_key": "your-api-key",
    "model_name": "gpt-3.5-turbo",
    "base_url": "https://api.openai.com/v1",
    "created_at": "2024-01-01T00:00:00Z"
}

🔌 Supported LLM Services

ScriptMate supports all OpenAI API-compatible services:

• OpenAI: GPT-3.5, GPT-4, GPT-4 Turbo
• Azure OpenAI: Enterprise OpenAI services
• Anthropic Claude: Via compatible interfaces
• Local Models: Ollama, LocalAI, etc.
• Other Services: Any OpenAI API-compatible service

🛡️ Security Features

• User Confirmation: All commands require confirmation before execution
• Dangerous Command Detection: Automatic detection of potentially harmful commands
• Safe Storage: Secure API key storage with masked display
• Dry Run Mode: Preview commands without execution
• Error Handling: Comprehensive error handling and validation

🏗️ Architecture

scriptmate/
├── cli.py          # Command-line interface (Click framework)
├── config.py       # Configuration management (JSON storage)
├── llm_client.py   # LLM client (OpenAI-compatible API)
├── executor.py     # Command executor (Safe execution)
└── utils.py        # Utility functions

🧪 Development

Setup Development Environment

git clone https://github.com/your-username/scriptmate.git
cd scriptmate
uv sync --dev

Run Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=scriptmate

# Run linting
uv run flake8 src/ tests/
uv run black --check src/ tests/

Build and Publish

# Build package
uv build

# Publish to PyPI (requires credentials)
uv publish

📚 Documentation

• Design Document: Detailed architecture and design decisions
• Contributing Guide: How to contribute to the project
• Changelog: Version history and updates
• Examples: Detailed usage examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter issues or have suggestions:

1. Check the FAQ
2. Search existing Issues
3. Create a new Issue

🙏 Acknowledgments

• Built with Click for CLI interface
• Powered by Rich for beautiful terminal output
• Managed with uv for fast Python packaging

---

ScriptMate - Your intelligent script partner, making command-line collaboration as seamless as working with a trusted companion! 🚀✨

中文文档 | English