Metadata-Version: 2.4
Name: pyrunner-cli
Version: 0.1.0
Summary: Lightweight cross-platform script runner inspired by npm scripts.
Author: Abdullah Ahmad
License-Expression: MIT
Project-URL: Homepage, https://github.com/AbdullahAhmad-0/PyRunner
Project-URL: Repository, https://github.com/AbdullahAhmad-0/PyRunner
Project-URL: Issues, https://github.com/AbdullahAhmad-0/PyRunner/issues
Keywords: scripts,script-runner,task-runner,npm-scripts,pyr,pyrunner,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PyRunner

[![PyPI version](https://img.shields.io/pypi/v/pyrunner-cli.svg)](https://pypi.org/project/pyrunner-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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)

```bash
pip install pyrunner-cli
```

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

```bash
pyr --help
pyr list
pyr build
```

## From Source

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

```bash
pyr build
pyr list
```

### Linux / macOS (Using Shell Script)

PyRunner includes a `pyr` shell script:

1. Make the script executable:
   ```bash
   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):
   ```bash
   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.

```text
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`).

```text
~/.pyrunner/
└── scripts.json
```

These scripts are available from every directory.

---

## Custom Script File

You may specify any `scripts.json` file:

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

---

# Configuration

Example `scripts.json`:

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

---

# Running Scripts

## Automatic Mode (Default)

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

```bash
pyr --local build
```

or

```bash
pyr -l build
```

Only the local `scripts.json` is searched.

Global scripts are ignored.

---

## Global Only

```bash
pyr --global build
```

or

```bash
pyr -g build
```

Only the global scripts are searched.

Local scripts are ignored.

---

## Custom Configuration

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

Only the specified configuration file is used.

---

# Listing Scripts

Display every available script:

```bash
pyr list
```

Example:

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

```bash
pyr list --local
```

---

## List Global Scripts

```bash
pyr list --global
```

---

## List Custom File

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

---

# Priority Rules

Default behavior:

```
Local Script
    ↓
Global Script
```

Example:

Local:

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

Global:

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

Running:

```bash
pyr build
```

executes:

```text
python build.py
```

because local scripts always have higher priority.

---

# Help

```bash
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](https://github.com/AbdullahAhmad-0/PyRunner)

---

## License

MIT License. See [LICENSE](LICENSE) for details.
