GitHub Listen CLI (BETA)

🚀 Perform shell scripts when file changes occur on GitHub repositories

📌 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:

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:

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 (give it repo scope for private repositories).

2️⃣ Add a Listener

To start monitoring a file, use the interactive add command:

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:

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:

github-listen start <nickname>

Example:

github-listen start backend-env

5️⃣ Stop a Listener

To stop a running listener:

github-listen stop <nickname>

Example:

github-listen stop backend-env

6️⃣ Remove a Listener

To delete a listener:

github-listen remove <nickname>

Example:

github-listen remove backend-env

7️⃣ View Logs

To check logs for a specific listener:

github-listen logs <nickname>

8️⃣ Modify Conditions

To update the conditions for an existing listener:

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.

🔗 GitHub Repository: https://github.com/octamap/github-listen
📧 Contact: [email protected]

🚀 Start automating your workflows with GitHub Listen! 🚀