Skip to main content

version = "2.0.2"

RunSH

Transform your shell scripts into powerful CLI tools with autocomplete, help messages, and argument validation.

✨ Features

  • 🔧 Zero Configuration: Add simple comments to your scripts
  • 🌍 GitHub Integration: Run scripts directly from GitHub repositories
  • 💾 Smart Caching: Offline support with automatic cache management
  • 🎯 Auto-completion: Rich CLI experience with argument validation
  • 📁 Organized: All files managed in .runsh/ directory

🚀 Quick Start

Installation

pip install runsh

Basic Usage

  1. Create a script with metadata comments:
#!/bin/bash
# @description: Deploy application to production
# @arg environment: Target environment (staging/prod)
# @option verbose,v [flag]: Show detailed output
# @option dry-run,d [flag]: Preview changes without executing

echo "Deploying to $ENVIRONMENT..."
[ "$VERBOSE" = "1" ] && echo "Verbose mode enabled"
  1. Run with RunSH:
# Auto-discovers scripts in ./scripts/
runsh deploy production --verbose

# Get help automatically
runsh deploy --help

GitHub Integration

# Initialize configuration
runsh config init

# Edit .runsh/config.yaml
scripts_dir: "https://github.com/user/repo/tree/main/scripts"

# Use scripts from GitHub
runsh list
runsh deploy --help

📖 Documentation

🎯 Key Commands

# Script Management
runsh list                    # List available scripts
runsh <script-name> --help    # Get script help

# Configuration  
runsh config show             # Show current config
runsh config init             # Create config file

# Cache Management
runsh cache list              # List cached scripts
runsh cache clean             # Clean expired cache
runsh cache clean --all       # Clean all cache

📁 Project Structure

.runsh/
├── config.yaml              # Main configuration
└── cache/                    # GitHub script cache
    └── github_user_repo_main_scripts/
        ├── script1.sh
        └── .metadata

🔧 Script Metadata

Add these comments to your shell scripts:

# @description: Brief description of what the script does
# @arg name [optional] [default=value]: Argument description  
# @option name,short [flag]: Option description
# @option timeout [default=30]: Value option with default

→ Complete syntax reference

🌍 Remote Scripts

# .runsh/config.yaml
scripts_dir: "https://github.com/team/devops-scripts/tree/main/tools"
default_shell: "bash"

→ GitHub integration guide

📚 Examples

Python Package Publishing

#!/bin/bash
# @description: Publish Python package to PyPI
# @option test,t [flag]: Upload to TestPyPI instead
# @option skip-build,s [flag]: Skip building step

# Build and publish logic here...
runsh publish-python --test  # Test on TestPyPI first
runsh publish-python         # Publish to PyPI

→ More examples

🛠️ Configuration

Environment Variables

export RUNSH_SCRIPTS_DIR="~/my-scripts"
export RUNSH_SHELL="zsh"

Config File

# .runsh/config.yaml
scripts_dir: "./tools"        # Local directory
# scripts_dir: "https://github.com/user/repo/tree/main/scripts"  # GitHub
default_shell: "bash"

→ Full configuration options

🤝 Contributing

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


Transform your shell scripts into professional CLI tools! 🚀

Metadata

Release files for runsh 2.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for runsh 2.0.4
File Size Uploaded Provenance Actions
runsh-2.0.4.tar.gz 26.2 kB Without provenance Details for runsh-2.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for runsh 2.0.4
File Interpreter ABI Platform Actions
runsh-2.0.4-py3-none-any.whl Python 3 none any Details for runsh-2.0.4-py3-none-any.whl

Total release size: 52.7 kB

Release files / runsh-2.0.4.tar.gz

Download URL runsh-2.0.4.tar.gz
Size 26.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7270bac5599807ad8b6255b5145692e9ecf2f87d75d3409d681fb8a0d9363c53
BLAKE2b-256 checksum
How to use checksums
30751bc13b07bf96a0e751113ce01a83ffd581827ba4f125e9bd84a377098be5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.0

Release files / runsh-2.0.4-py3-none-any.whl

Download URL runsh-2.0.4-py3-none-any.whl
Size 26.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7591d683d4079f133dbc75185defba977cf64234ba9bba18489fe69f8d6c956
BLAKE2b-256 checksum
How to use checksums
320cabe783f817fd966c4c3052e0906b8dea1487331835e2871f8c0ee52d4220
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.0

Security for runsh 2.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page