npm package: @octamap/github-listen
Description: Perform shell script when new commits occur on github
Author: octamap
Latest version: 1.0.7

# **GitHub Listen CLI (BETA)**  
🚀 **Perform shell scripts when file changes occur on GitHub repositories**  

[![npm version](https://img.shields.io/npm/v/@octamap/github-listen.svg)](https://www.npmjs.com/package/@octamap/github-listen)  
[![GitHub license](https://img.shields.io/github/license/octamap/github-listen)](LICENSE)  
[![GitHub issues](https://img.shields.io/github/issues/octamap/github-listen)](https://github.com/octamap/github-listen/issues)  

---

## **📌 Features**
- 🛠 **Automate tasks** when a file in a GitHub repository changes  
- ⏳ **Custom polling intervals** to check for updates  
- 📜 **Run shell scripts** when changes are detected  
- 💾 **Persistent storage** of listeners  
- 🔄 **Automatically restarts on system startup** (coming soon!)  
- ✅ **Easy-to-use CLI with interactive prompts**  

---

## **📦 Installation**  
Install the CLI globally via npm:  

```sh
npm install -g @octamap/github-listen
```

---

## **🚀 Usage**  

### **1️⃣ Authenticate with GitHub**
Before using the CLI, you need to provide a **GitHub Personal Access Token**.  
Run the following command:

```sh
github-listen login <your_github_token>
```

_If you don't provide a token in the command, the CLI will prompt you to enter it._  
👉 You can create a token [here](https://github.com/settings/tokens) (give it `repo` scope for private repositories).  

---

### **2️⃣ Add a Listener**
To start monitoring a file, use the interactive `add` command:

```sh
github-listen add
```

You'll be prompted to:  
✅ Select a GitHub repository  
✅ Choose a file to monitor  
✅ Set a condition (e.g., "modified")  
✅ Define how often the script should check (in seconds)  
✅ Specify a shell script to run when changes are detected  
✅ Assign a nickname for this listener  

---

### **3️⃣ List Active Listeners**
To view all configured listeners:

```sh
github-listen list
```

Example output:

```
Listeners:
- backend-env: Watching user/repo/.env every 30 sec
- build-script: Watching octamap/frontend/build.sh every 60 sec
```

---

### **4️⃣ Start a Listener**
To start monitoring a file:

```sh
github-listen start <nickname>
```

Example:

```sh
github-listen start backend-env
```

---

### **5️⃣ Stop a Listener**
To stop a running listener:

```sh
github-listen stop <nickname>
```

Example:

```sh
github-listen stop backend-env
```

---

### **6️⃣ Remove a Listener**
To delete a listener:

```sh
github-listen remove <nickname>
```

Example:

```sh
github-listen remove backend-env
```

---

### **7️⃣ View Logs**
To check logs for a specific listener:

```sh
github-listen logs <nickname>
```

---

### **8️⃣ Modify Conditions**
To update the conditions for an existing listener:

```sh
github-listen conditions <nickname>
```

---

## **🔧 How It Works**
1. The CLI **polls the GitHub API** every X seconds for the file's `sha` (a hash of the content).  
2. If the `sha` changes, the CLI **executes the specified script**.  
3. You can start multiple listeners for different repositories and files.  

---

## **🌎 Example Use Cases**
- **Auto-deploy** a project when `.env` is updated  
- **Restart a server** when a `config.json` file changes  
- **Trigger a build** when `package.json` is modified  
- **Notify a Slack channel** when a script is updated  

---

## **💡 Contributing**
We welcome contributions!  
1. Fork the repository  
2. Create a feature branch: `git checkout -b feature-name`  
3. Commit your changes: `git commit -m "Add new feature"`  
4. Push to the branch: `git push origin feature-name`  
5. Open a pull request  

---

## **📝 License**
This project is licensed under the [MIT License](LICENSE).  

---

🔗 **GitHub Repository:** [https://github.com/octamap/github-listen](https://github.com/octamap/github-listen)  
📧 **Contact:** support@octamap.com  

---

🚀 **Start automating your workflows with GitHub Listen!** 🚀