script-magic 1.0.0

Command-line script utility toolkit that simplifies common scripting tasks with AI-powered script generation, GitHub Gist integration for cross-device synchronization, and automatic dependency management. Create, run, and manage scripts with natural language prompts.

Script Magic 🪄

Script Magic is a CLI tool for creating, managing, and running Python scripts with GitHub Gists integration and AI-powered script generation.

Features

• 🤖 AI-Powered Script Generation: Create Python scripts from natural language prompts using OpenAI's GPT models
• ☁️ GitHub Gist Integration: Store and manage scripts in GitHub Gists for easy sharing and versioning
• 🔄 Simple Script Management: Run, update, and manage your scripts with easy commands
• 📦 Automatic Dependency Management: Script execution with uv handles dependencies automatically
• 🚀 Interactive Mode: Refine generated scripts interactively before saving
• 🔄 Cross-Device Synchronization: Automatically find and sync your script inventory across devices using GitHub Gists
• 🔎 Smart Gist Detection: Automatically finds your existing script mappings on GitHub
• 🌐 Multi-Environment Support: Works seamlessly across different machines with the same GitHub account
• 🖋️ Syntax Highlighting: Built-in code editor with syntax highlighting (requires optional dependencies)

Installation

Prerequisites

• Python 3.9+
• uv for Python package management and script execution
• GitHub account with a Personal Access Token
• OpenAI API key

Quick Install

# Clone the repository
git clone https://github.com/yourusername/script-magic.git
cd script-magic

# Install with uv
uv venv
uv pip install -e .

# Set up your environment variables
export OPENAI_API_KEY="your-openai-api-key"
export MY_GITHUB_PAT="your-github-personal-access-token"

Optional Dependencies

For enhanced features such as syntax highlighting in the editor:

pip install 'script-magic[syntax]'

Usage

Creating Scripts

Generate a new script from a natural language prompt:

sm create hello-world "Create a script that prints 'Hello, World!' with timestamp"

Generate with interactive preview:

sm create fibonacci --preview "Generate a script to print the first 10 Fibonacci numbers"

Running Scripts

Run a script that has been previously created:

sm run hello-world

Pass parameters to the script:

sm run hello-world --name="John"

Force refresh from GitHub before running:

sm run hello-world --refresh

Run a script in a new terminal window:

sm run visualize-data --in-terminal

The --in-terminal (-t) option will run the script in a new terminal window that remains open until closed by the user. This is particularly useful for scripts with interactive elements or those that produce visual output.

Listing Scripts

View all scripts in your inventory:

sm list

Show detailed information about your scripts:

sm list --verbose

Pull the latest scripts from GitHub before listing:

sm list --pull

Push your local script inventory to GitHub while listing:

sm list --push

Syncing Scripts

Sync your local inventory to GitHub:

sm sync

Pull the latest mapping from GitHub:

sm pull

Deleting Scripts

Remove a script from both local inventory and GitHub Gists:

sm delete script-name

Force deletion without confirmation:

sm delete script-name --force

Editing Scripts

Edit a script with syntax highlighting (if dependencies are installed):

script-magic edit myscript

GitHub Integration

Script Magic automatically handles GitHub synchronization:

• First-time users: Script Magic creates a new private Gist to store your script inventory
• Existing users: Script Magic finds your existing script inventory Gists automatically
• Multiple devices: Script Magic detects existing mappings and asks which version to keep

Configuration

Script Magic stores configuration in the ~/.sm directory:

• ~/.sm/mapping.json: Maps script names to GitHub Gist IDs
• ~/.sm/gist_id.txt: Stores the ID of the GitHub Gist containing your mapping file
• ~/.sm/logs/: Log files for debugging

Structure

script-magic/
├── src/
│   └── script_magic/
│       ├── __init__.py                # CLI entry point with command registration
│       ├── create.py                  # Script creation command
│       ├── run.py                     # Script execution command
│       ├── list.py                    # Script listing command
│       ├── delete.py                  # Script deletion command
│       ├── github_integration.py      # GitHub Gist API integration
│       ├── github_gist_finder.py      # Finds existing mapping Gists
│       ├── pydantic_ai_integration.py # AI script generation
│       ├── mapping_manager.py         # Script mapping management
│       ├── mapping_setup.py           # Initializes mapping with GitHub sync
│       ├── logger.py                  # Logging configuration
│       └── rich_output.py             # Terminal output formatting

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key
• MY_GITHUB_PAT: GitHub Personal Access Token with Gist permissions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some 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 file for details.

Acknowledgments

• PydanticAI for AI integration
• Click for the CLI interface
• PyGitHub for GitHub API integration
• Rich for beautiful terminal output

Development

To install development dependencies:

pip install -e '.[dev,syntax]'