PyRunner

A lightweight, cross-platform script runner inspired by npm scripts. Store reusable commands in scripts.json files and execute them by name from anywhere.

PyRunner supports both local and global script collections with automatic priority handling.

---

Installation

Via pip (Recommended)

pip install pyrunner-cli

Once installed, the pyr command will be available everywhere in your terminal:

pyr --help
pyr list
pyr build

From Source

git clone https://github.com/AbdullahAhmad-0/PyRunner.git
cd PyRunner
pip install -e .

Or run directly without installing:

• Windows: Use pyr.bat <script>
• Linux/macOS: Use ./pyr <script>

---

Manual PATH Setup (Without pip)

Windows (Using Batch File)

PyRunner includes a pyr.bat file so you can use pyr directly:

1. Place pyr.bat and runner.py in the same directory.
2. Add that directory to your system's PATH environment variable.
3. Open a new terminal.

Now you can run PyRunner from any location:

pyr build
pyr list

Linux / macOS (Using Shell Script)

PyRunner includes a pyr shell script:

1. Make the script executable:

   chmod +x pyr
   

2. Move it to a directory in your PATH (such as /usr/local/bin on Linux/Intel Macs or /opt/homebrew/bin on Apple Silicon Macs):

   sudo mv pyr /usr/local/bin/
   

   Note: Ensure runner.py remains in the same directory as the pyr script if not installed via pip.

---

Features

• 🚀 Run scripts by name (pyr <name>)
• 📁 Local and global script collections
• 🔍 Automatic script lookup
• ⭐ Local scripts take priority over global scripts
• 📋 List available local and global scripts (pyr list)
• 📄 Use a custom scripts.json file
• 💻 Cross-platform (Windows, Linux, macOS)
• ⚡ No external dependencies

---

Script Locations

PyRunner supports three sources of scripts.

Local Scripts

Located in the current working directory.

project/
│
├── scripts.json
└── ...

These scripts are intended for a single project.

---

Global Scripts

Stored in ~/.pyrunner/scripts.json (or next to the PyRunner executable in scripts/scripts.json).

~/.pyrunner/
└── scripts.json

These scripts are available from every directory.

---

Custom Script File

You may specify any scripts.json file:

pyr --file D:/Configs/scripts.json build

---

Configuration

Example scripts.json:

{
    "scripts": {
        "start": "python app.py",
        "build": "python build.py",
        "clean": "python clean.py",
        "test": "pytest"
    }
}

---

Running Scripts

Automatic Mode (Default)

pyr build

Search order:

1. Local scripts.json
2. Global scripts/scripts.json (or ~/.pyrunner/scripts.json)

If a script exists in both locations, the local script is executed.

If one of the configuration files doesn't exist, it is simply ignored.

---

Local Only

pyr --local build

or

pyr -l build

Only the local scripts.json is searched.

Global scripts are ignored.

---

Global Only

pyr --global build

or

pyr -g build

Only the global scripts are searched.

Local scripts are ignored.

---

Custom Configuration

pyr --file ./configs/scripts.json build

Only the specified configuration file is used.

---

Listing Scripts

Display every available script:

pyr list

Example:

Local Scripts
-------------
build      python build.py
clean      python clean.py
start      python app.py

Global Scripts
--------------
git-clean  git clean -fd
update     winget upgrade --all
serve      python -m http.server

Missing configuration files are skipped automatically.

---

List Local Scripts

pyr list --local

---

List Global Scripts

pyr list --global

---

List Custom File

pyr list --file ./configs/scripts.json

---

Priority Rules

Default behavior:

Local Script
    ↓
Global Script

Example:

Local:

{
    "scripts": {
        "build": "python build.py"
    }
}

Global:

{
    "scripts": {
        "build": "docker compose build"
    }
}

Running:

pyr build

executes:

python build.py

because local scripts always have higher priority.

---

Help

pyr --help

Displays every available command and option.

---

Future Features

• init — Create a new scripts.json
• add — Add a script from the command line
• remove — Remove a script
• edit — Open the configuration in your editor
• doctor — Validate configuration files
• aliases
• Environment variables
• Sequential execution
• Parallel execution
• Colored output
• Shell auto-completion
• YAML and TOML support

---

Contributing

Issues and pull requests are welcome! Feel free to visit the GitHub repository: https://github.com/AbdullahAhmad-0/PyRunner

---

License

MIT License. See LICENSE for details.