scriptmate

Name	scriptmate JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	ScriptMate - Intelligent Script Companion
upload_time	2025-10-14 09:16:16
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	None
keywords	ai cli command natural-language shell
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # ScriptMate

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

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/scriptmate.svg)](https://badge.fury.io/py/scriptmate)

## 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

```bash
pip install scriptmate
```

### Using uv

```bash
uv add scriptmate
```

### From Source

```bash
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# Show version
scriptmate --version

# Show system info
scriptmate info

# Show command history
scriptmate history
```

## 📋 Command Examples

```bash
# 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`:

```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

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

### Run Tests

```bash
# 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

```bash
# Build package
uv build

# Publish to PyPI (requires credentials)
uv publish
```

## 📚 Documentation

- **[Design Document](DESIGN.md)**: Detailed architecture and design decisions
- **[Contributing Guide](CONTRIBUTING.md)**: How to contribute to the project
- **[Changelog](CHANGELOG.md)**: Version history and updates
- **[Examples](examples/)**: Detailed usage examples

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](LICENSE) file for details.

## 🆘 Support

If you encounter issues or have suggestions:

1. Check the [FAQ](docs/FAQ.md)
2. Search existing [Issues](https://github.com/your-username/scriptmate/issues)
3. Create a new Issue

## 🙏 Acknowledgments

- Built with [Click](https://click.palletsprojects.com/) for CLI interface
- Powered by [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- Managed with [uv](https://github.com/astral-sh/uv) for fast Python packaging

---

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

[中文文档](README_CN.md) | [English](README.md)
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "scriptmate",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "ai, cli, command, natural-language, shell",
    "author": null,
    "author_email": "ScriptMate Team <jubaoliang@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/24/2d/0a954b92ee0bed3a0dee792587055483c4a999fe29401528e22d746c109c/scriptmate-0.1.0.tar.gz",
    "platform": null,
    "description": "# ScriptMate\n\n\ud83e\udd16 **Your Intelligent Script Partner** - Making command-line collaboration as seamless as working with a trusted companion\n\n[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/scriptmate.svg)](https://badge.fury.io/py/scriptmate)\n\n## Overview\n\nScriptMate 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.\n\n## \u2728 Features\n\n- \ud83e\udd16 **Natural Language Understanding**: Supports natural language descriptions to understand user intent\n- \ud83d\udd27 **Cross-Platform**: Works on Windows, macOS, and Linux\n- \ud83d\udee1\ufe0f **Safe Execution**: Requires user confirmation before execution for security\n- \ud83d\udcdd **Detailed Explanations**: Provides detailed explanations and reasoning process\n- \u2699\ufe0f **Flexible Configuration**: Supports multiple LLM service providers\n- \ud83c\udfa8 **Rich Interface**: Beautiful terminal output with colors and icons\n- \ud83d\udcca **Command History**: Track and review executed commands\n- \ud83d\udd0d **Dry Run Mode**: Preview commands without execution\n\n## \ud83d\ude80 Installation\n\n### Using pip\n\n```bash\npip install scriptmate\n```\n\n### Using uv\n\n```bash\nuv add scriptmate\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/your-username/scriptmate.git\ncd scriptmate\nuv sync\nuv pip install -e .\n```\n\n## \ud83c\udfaf Quick Start\n\n### 1. Initial Setup\n\nOn first use, ScriptMate will guide you through the configuration:\n\n```bash\nscriptmate generate \"show current user\"\n```\n\nYou'll be prompted to enter:\n- **API Key**: Your LLM service API key\n- **Model Name**: e.g., `gpt-3.5-turbo`, `gpt-4`\n- **Base URL**: e.g., `https://api.openai.com/v1`\n\n### 2. Basic Usage\n\n```bash\n# Generate and execute commands\nscriptmate generate \"show current user\"\nscriptmate generate \"list files in current directory\"\nscriptmate generate \"check disk usage\"\n\n# Preview without execution (dry run)\nscriptmate generate --dry-run \"find all Python files\"\n\n# Auto-confirm execution\nscriptmate generate -y \"show system time\"\n```\n\n### 3. Configuration Management\n\n```bash\n# Show current configuration\nscriptmate config show\n\n# Setup new configuration\nscriptmate config setup\n\n# Test configuration\nscriptmate config test\n\n# Reset configuration\nscriptmate config reset\n```\n\n### 4. System Information\n\n```bash\n# Show version\nscriptmate --version\n\n# Show system info\nscriptmate info\n\n# Show command history\nscriptmate history\n```\n\n## \ud83d\udccb Command Examples\n\n```bash\n# File Operations\nscriptmate generate \"find all .py files recursively\"\nscriptmate generate \"show file permissions of current directory\"\nscriptmate generate \"compress folder into zip\"\n\n# System Monitoring\nscriptmate generate \"show memory usage\"\nscriptmate generate \"list running processes\"\nscriptmate generate \"check network connections\"\n\n# Git Operations\nscriptmate generate \"show git status with colors\"\nscriptmate generate \"create new branch and switch to it\"\n\n# Network Operations\nscriptmate generate \"ping google.com 5 times\"\nscriptmate generate \"download file from URL\"\n```\n\n## \u2699\ufe0f Configuration\n\nConfiguration is stored in `~/.scriptmate/config.json`:\n\n```json\n{\n    \"api_key\": \"your-api-key\",\n    \"model_name\": \"gpt-3.5-turbo\",\n    \"base_url\": \"https://api.openai.com/v1\",\n    \"created_at\": \"2024-01-01T00:00:00Z\"\n}\n```\n\n## \ud83d\udd0c Supported LLM Services\n\nScriptMate supports all OpenAI API-compatible services:\n\n- **OpenAI**: GPT-3.5, GPT-4, GPT-4 Turbo\n- **Azure OpenAI**: Enterprise OpenAI services\n- **Anthropic Claude**: Via compatible interfaces\n- **Local Models**: Ollama, LocalAI, etc.\n- **Other Services**: Any OpenAI API-compatible service\n\n## \ud83d\udee1\ufe0f Security Features\n\n- **User Confirmation**: All commands require confirmation before execution\n- **Dangerous Command Detection**: Automatic detection of potentially harmful commands\n- **Safe Storage**: Secure API key storage with masked display\n- **Dry Run Mode**: Preview commands without execution\n- **Error Handling**: Comprehensive error handling and validation\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nscriptmate/\n\u251c\u2500\u2500 cli.py          # Command-line interface (Click framework)\n\u251c\u2500\u2500 config.py       # Configuration management (JSON storage)\n\u251c\u2500\u2500 llm_client.py   # LLM client (OpenAI-compatible API)\n\u251c\u2500\u2500 executor.py     # Command executor (Safe execution)\n\u2514\u2500\u2500 utils.py        # Utility functions\n```\n\n## \ud83e\uddea Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/your-username/scriptmate.git\ncd scriptmate\nuv sync --dev\n```\n\n### Run Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=scriptmate\n\n# Run linting\nuv run flake8 src/ tests/\nuv run black --check src/ tests/\n```\n\n### Build and Publish\n\n```bash\n# Build package\nuv build\n\n# Publish to PyPI (requires credentials)\nuv publish\n```\n\n## \ud83d\udcda Documentation\n\n- **[Design Document](DESIGN.md)**: Detailed architecture and design decisions\n- **[Contributing Guide](CONTRIBUTING.md)**: How to contribute to the project\n- **[Changelog](CHANGELOG.md)**: Version history and updates\n- **[Examples](examples/)**: Detailed usage examples\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udd98 Support\n\nIf you encounter issues or have suggestions:\n\n1. Check the [FAQ](docs/FAQ.md)\n2. Search existing [Issues](https://github.com/your-username/scriptmate/issues)\n3. Create a new Issue\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [Click](https://click.palletsprojects.com/) for CLI interface\n- Powered by [Rich](https://rich.readthedocs.io/) for beautiful terminal output\n- Managed with [uv](https://github.com/astral-sh/uv) for fast Python packaging\n\n---\n\n**ScriptMate - Your intelligent script partner, making command-line collaboration as seamless as working with a trusted companion!** \ud83d\ude80\u2728\n\n[\u4e2d\u6587\u6587\u6863](README_CN.md) | [English](README.md)",
    "bugtrack_url": null,
    "license": null,
    "summary": "ScriptMate - Intelligent Script Companion",
    "version": "0.1.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/scriptmate/scriptmate/issues",
        "Documentation": "https://scriptmate.readthedocs.io",
        "Homepage": "https://github.com/scriptmate/scriptmate",
        "Repository": "https://github.com/scriptmate/scriptmate.git"
    },
    "split_keywords": [
        "ai",
        " cli",
        " command",
        " natural-language",
        " shell"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "6b951dab4fce082ef742f33f8ece6ec38863586a7a04c7b532549c583cf1a6a6",
                "md5": "a1f05a6c2b2d1f6ace9f3872e90022b5",
                "sha256": "c4c3bf1b4cca412008f8a2b95869d3665ee5b3b345bce272d5cf00c990c7bcb0"
            },
            "downloads": -1,
            "filename": "scriptmate-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a1f05a6c2b2d1f6ace9f3872e90022b5",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 14649,
            "upload_time": "2025-10-14T09:16:14",
            "upload_time_iso_8601": "2025-10-14T09:16:14.408140Z",
            "url": "https://files.pythonhosted.org/packages/6b/95/1dab4fce082ef742f33f8ece6ec38863586a7a04c7b532549c583cf1a6a6/scriptmate-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "242d0a954b92ee0bed3a0dee792587055483c4a999fe29401528e22d746c109c",
                "md5": "1b858af8486c258913e1c07250c32eec",
                "sha256": "dd3775c99baff93c912333fb036d5e07a552320a9ebb42ec3dbae7a21de9a33a"
            },
            "downloads": -1,
            "filename": "scriptmate-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "1b858af8486c258913e1c07250c32eec",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 14734,
            "upload_time": "2025-10-14T09:16:16",
            "upload_time_iso_8601": "2025-10-14T09:16:16.259741Z",
            "url": "https://files.pythonhosted.org/packages/24/2d/0a954b92ee0bed3a0dee792587055483c4a999fe29401528e22d746c109c/scriptmate-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-14 09:16:16",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "scriptmate",
    "github_project": "scriptmate",
    "github_not_found": true,
    "lcname": "scriptmate"
}