{"id":23392968,"url":"https://github.com/binarynoir/noirwatch","last_synced_at":"2025-10-28T13:17:43.618Z","repository":{"id":262711753,"uuid":"888106209","full_name":"binarynoir/noirwatch","owner":"binarynoir","description":"Monitor specified websites for changes and send notifications. It supports various notification methods including Pushover and native desktop notifications.","archived":false,"fork":false,"pushed_at":"2025-01-01T22:09:34.000Z","size":197,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T12:16:06.956Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://binarynoir.tech","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binarynoir.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"buy_me_a_coffee":"binarynoir","ko_fi":"binarynoir"}},"created_at":"2024-11-13T20:33:29.000Z","updated_at":"2025-01-01T22:09:30.000Z","dependencies_parsed_at":"2024-12-20T21:45:40.540Z","dependency_job_id":null,"html_url":"https://github.com/binarynoir/noirwatch","commit_stats":null,"previous_names":["binarynoir/noirwatch"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarynoir%2Fnoirwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarynoir%2Fnoirwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarynoir%2Fnoirwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarynoir%2Fnoirwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binarynoir","download_url":"https://codeload.github.com/binarynoir/noirwatch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247873845,"owners_count":21010545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-22T05:16:51.538Z","updated_at":"2025-10-28T13:17:43.534Z","avatar_url":"https://github.com/binarynoir.png","language":"Shell","readme":"# NoirWatch\n\nNoirWatch monitors specified websites for changes and sends notifications. It supports various notification methods including Pushover and native desktop notifications.\n\n[![Support me on Buy Me a Coffee](https://img.shields.io/badge/Support%20me-Buy%20Me%20a%20Coffee-orange?style=for-the-badge\u0026logo=buy-me-a-coffee)](https://buymeacoffee.com/binarynoir)\n[![Support me on Ko-fi](https://img.shields.io/badge/Support%20me-Ko--fi-blue?style=for-the-badge\u0026logo=ko-fi)](https://ko-fi.com/binarynoir)\n[![Visit my website](https://img.shields.io/badge/Website-binarynoir.tech-8c8c8c?style=for-the-badge)](https://binarynoir.tech)\n\n## Features\n\n- Monitor multiple websites for changes\n- Send notifications via Pushover and native desktop notifications (macOS, Linux, Windows)\n- Configurable check intervals\n- Verbose logging with different log levels\n- Background execution support\n- Customizable configuration and URL list files\n\n## Feature Roadmap\n\n- [x] Monitor multiple websites for changes\n- [x] Send notifications via Pushover\n- [x] Send notifications via native desktop notifications (macOS, Linux, Windows)\n- [x] Run as a background service\n- [x] Run a custom script on change detection\n- [x] Run the check a specific number of times and then exit\n- [x] Robust configuration using JSON which includes per URL options\n- [ ] Output change averages for all urls\n- [ ] Add averages to notifications\n- [ ] Full historical average change report\n- [ ] Add more notification methods (email, slack, discord, teams, Telegram etc.)\n\n## Requirements\n\n- Bash 4.0+\n- `curl` for fetching website content\n- `sed` for HTML content normalization\n- `shasum` for change comparisons\n- `timeout` for custom command files\n- `xmllint` for HTML content normalization\n- `powershell` for Windows desktop notifications\n- `notify-send` for Linux desktop notifications\n\n## Installation\n\n### macOS Using Homebrew\n\n1. Tap the repository (if not already tapped):\n\n   ```bash\n   brew tap binarynoir/noirwatch\n   ```\n\n2. Install NoirWatch:\n\n   ```bash\n   brew install noirwatch\n   ```\n\n### Manual Installation (Linux/macOS Only)\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/binarynoir/noirwatch.git\n   cd noirwatch\n   ```\n\n2. Make the script executable:\n\n   ```bash\n   chmod +x noirwatch\n   ```\n\n3. Install `notify-send` for desktop notifications (if not already installed) on Linux:\n\n   ```bash\n   # On Debian/Ubuntu-based systems\n   sudo apt install libnotify-bin\n\n   # On Fedora-based systems\n   sudo dnf install libnotify\n\n   # On Arch-based systems\n   sudo pacman -S libnotify\n   ```\n\n### Windows Installation\n\n1. Install [Git for Windows](https://gitforwindows.org/) (includes Git Bash, if not installed).\n\n2. Clone the repository:\n\n   ```bash\n   git clone https://github.com/binarynoir/noirwatch.git\n   cd noirwatch\n   ```\n\n3. Make the script executable (in Git Bash or similar terminal):\n\n   ```bash\n   chmod +x noirwatch\n   ```\n\n4. Ensure PowerShell is enabled in your Git Bash environment for notifications.\n\n### Installing the Man Page (Linux/macOS Only)\n\n1. Move the man file to the appropriate directory:\n\n   ```bash\n   sudo mv noirwatch.1 /usr/local/share/man/man1/\n   ```\n\n2. Update the man database:\n\n   ```bash\n   sudo mandb\n   ```\n\n3. View the man page:\n\n   ```bash\n   man noirwatch\n   ```\n\n## Setting Up as a Service\n\n### Linux\n\n1. Create a systemd service file:\n\n   ```bash\n   sudo nano /etc/systemd/system/noirwatch.service\n   ```\n\n2. Add the following content to the service file:\n\n   ```ini\n   [Unit]\n   Description=NoirWatch Service\n   After=network.target\n\n   [Service]\n   ExecStart=/path/to/noirwatch --start\n   WorkingDirectory=/path/to\n   StandardOutput=syslog\n   StandardError=syslog\n   Restart=always\n   User=your-username\n\n   [Install]\n   WantedBy=multi-user.target\n   ```\n\n   Replace `/path/to/noirwatch` with the actual path to the `noirwatch` script and `your-username` with your actual username.\n\n3. Reload systemd to apply the new service:\n\n   ```bash\n   sudo systemctl daemon-reload\n   ```\n\n4. Enable the service to start on boot:\n\n   ```bash\n   sudo systemctl enable noirwatch\n   ```\n\n5. Start the service:\n\n   ```bash\n   sudo systemctl start noirwatch\n   ```\n\n6. Check the status of the service:\n\n   ```bash\n   sudo systemctl status noirwatch\n   ```\n\n### macOS\n\n1. Create a launchd plist file:\n\n   ```bash\n   sudo nano /Library/LaunchDaemons/com.noirwatch.plist\n   ```\n\n2. Add the following content to the plist file:\n\n   ```xml\n   \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n   \u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n   \u003cplist version=\"1.0\"\u003e\n   \u003cdict\u003e\n       \u003ckey\u003eLabel\u003c/key\u003e\n       \u003cstring\u003ecom.noirwatch\u003c/string\u003e\n       \u003ckey\u003eProgramArguments\u003c/key\u003e\n       \u003carray\u003e\n           \u003cstring\u003e/path/to/noirwatch\u003c/string\u003e\n           \u003cstring\u003e--start\u003c/string\u003e\n       \u003c/array\u003e\n       \u003ckey\u003eWorkingDirectory\u003c/key\u003e\n       \u003cstring\u003e/path/to\u003c/string\u003e\n       \u003ckey\u003eRunAtLoad\u003c/key\u003e\n       \u003ctrue/\u003e\n       \u003ckey\u003eKeepAlive\u003c/key\u003e\n       \u003ctrue/\u003e\n       \u003ckey\u003eStandardOutPath\u003c/key\u003e\n       \u003cstring\u003e/var/log/noirwatch.log\u003c/string\u003e\n       \u003ckey\u003eStandardErrorPath\u003c/key\u003e\n       \u003cstring\u003e/var/log/noirwatch.log\u003c/string\u003e\n   \u003c/dict\u003e\n   \u003c/plist\u003e\n   ```\n\n   Replace `/path/to/noirwatch` with the actual path to the `noirwatch` script.\n\n3. Load the plist file to start the service:\n\n   ```bash\n   sudo launchctl load /Library/LaunchDaemons/com.noirwatch.plist\n   ```\n\n4. Check the status of the service:\n\n   ```bash\n   sudo launchctl list | grep com.noirwatch\n   ```\n\n5. To unload the service:\n\n   ```bash\n   sudo launchctl unload /Library/LaunchDaemons/com.noirwatch.plist\n   ```\n\n### Setting Up NoirWatch as a Service on Windows\n\n1. **Create a Task in Task Scheduler**:\n\n   - Open Task Scheduler and select \"Create Task\".\n   - In the \"General\" tab, name the task \"NoirWatch\" and select \"Run whether user is logged on or not\".\n   - In the \"Triggers\" tab, click \"New\" and set the trigger to \"At startup\".\n   - In the \"Actions\" tab, click \"New\" and set the action to \"Start a program\".\n     - In the \"Program/script\" field, enter the path to `bash.exe` (usually located in `C:\\Program Files\\Git\\bin\\bash.exe` if using Git Bash).\n     - In the \"Add arguments (optional)\" field, enter the path to the `noirwatch` script and the `--start` argument, e.g., `/path/to/noirwatch --start`.\n   - In the \"Conditions\" tab, uncheck \"Start the task only if the computer is on AC power\" to ensure it runs on battery power as well.\n   - In the \"Settings\" tab, ensure \"Allow task to be run on demand\" is checked.\n\n2. **Save and Test the Task**:\n\n   - Click \"OK\" to save the task.\n   - To test the task, right-click on the \"NoirWatch\" task in Task Scheduler and select \"Run\".\n\n3. **Verify the Task**:\n\n   - Check the status of the task in Task Scheduler to ensure it is running.\n   - Verify that NoirWatch is running by checking the log file or the expected notifications.\n\n## Usage\n\nRun the script with the desired options. Below are some examples:\n\n- Monitor a single URL:\n\n  ```bash\n  ./noirwatch https://example.com\n  ```\n\n- Monitor URLs from a file:\n\n  ```bash\n  ./noirwatch -f urls\n  ```\n\n- Run the script in the background:\n\n  ```bash\n  ./noirwatch -b https://example.com\n  ```\n\n- Send Pushover notifications:\n\n  ```bash\n  ./noirwatch -p -a YOUR_API_TOKEN -u YOUR_USER_KEY https://example.com\n  ```\n\n## Configuration\n\nNoirWatch uses a configuration file to store default settings. The default location is `~/.config/noirwatch.conf`. You can initialize a configuration file with default settings using:\n\n```bash\n./noirwatch --init\n```\n\n### Example Configuration File\n\n```json\n{\n\t\"configuration\": {\n\t\t\"CACHE_DIR\": \"/tmp/noirwatch_cache\",\n\t\t\"LOG_FILE\": \"/tmp/noirwatch_cache/noirwatch.log\",\n\t\t\"CHECK_INTERVAL\": \"60s\",\n\t\t\"TIMEOUT\": \"5s\",\n\t\t\"SYSTEM_NAME\": \"Test System\",\n\t\t\"PUSHOVER_NOTIFICATION\": \"false\",\n\t\t\"PUSHOVER_USER_KEY\": \"\",\n\t\t\"PUSHOVER_API_TOKEN\": \"\",\n\t\t\"DESKTOP_NOTIFICATION\": \"false\",\n\t\t\"VERBOSE\": \"true\",\n\t\t\"LOG_LEVEL\": \"DEBUG\",\n\t\t\"THRESHOLD\": \"0\"\n\t},\n\t\"urls\": {\n\t\t\"default\": [\n\t\t\t{\n\t\t\t\t\"NAME\": \"Apple Newsroom\",\n\t\t\t\t\"URL\": \"https://www.apple.com/newsroom/\",\n\t\t\t\t\"TIMEOUT\": \"5s\",\n\t\t\t\t\"THRESHOLD\": \"1\",\n\t\t\t\t\"UPDATED_CMD\": \"./test/test_cmd.sh\",\n\t\t\t\t\"CMD_TIMEOUT\": \"5s\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"NAME\": \"9to5mac Homepage\",\n\t\t\t\t\"URL\": \"https://9to5mac.com\",\n\t\t\t\t\"TIMEOUT\": \"10s\",\n\t\t\t\t\"THRESHOLD\": \"5\",\n\t\t\t\t\"UPDATED_CMD\": \"./test/test_cmd.sh\",\n\t\t\t\t\"CMD_TIMEOUT\": \"5s\"\n\t\t\t}\n\t\t]\n\t}\n}\n```\n\n## Options\n\n### General Options\n\n- `-h, --help`: Display the help message.\n- `-V, --version`: Display the script version.\n\n### Configuration and Initialization\n\n- `-c, --config \u003cconfig_file\u003e`: Specify a custom configuration file.\n- `-i, --init`: Initialize the configuration file.\n- `-f, --force-init`: Force initialize the configuration file if one exists.\n- `-S, --show-config`: Show the configuration settings.\n- `-e, --show-config-file`: Show the configuration file.\n\n### Cache Management\n\n- `-x, --clean`: Delete all cached files.\n- `-C, --cache-dir \u003cpath\u003e`: Specify a custom cache directory.\n\n### Notification Options\n\n- `-n, --system-name`: Name of the system running the script.\n- `-p, --pushover`: Send Pushover notifications.\n- `-u, --user-key \u003ckey\u003e`: Specify the user key for Pushover notifications.\n- `-a, --api-token \u003ctoken\u003e`: Specify the API token for Pushover notifications.\n- `-d, --desktop`: Send desktop notifications using AppleScript.\n\n### Logging and Output\n\n- `-v, --verbose`: Enable verbose output.\n- `-l, --log`: Log the log file to the screen.\n- `-o, --output \u003cfile\u003e`: Specify a custom log file location.\n- `-L, --log-level \u003clevel\u003e`: Set the log level (FATAL, ERROR, WARN, INFO, DEBUG).\n\n### Remote Connection Configuration\n\n- `-i, --interval \u003cminutes\u003e`: Set the interval between checks (default is 15 minutes).\n- `-T, --timeout \u003cseconds\u003e`: Set the timeout for ping and DNS tests (default: 5 seconds).\n- `-H, --threshold \u003cpercentage\u003e`: Set the threshold percentage for detecting changes (default: 0%).\n- `-U, --list-urls`: List all watched URLs.\n\n### Process Management\n\n- `-s, --start`: Start the AppName service in the background.\n- `-k, --stop`: Stop the AppName service.\n- `-r, --restart`: Restart the AppName service.\n- `-t, --status`: Check the current status of the AppName service.\n\n## Docker Deployment Instructions\n\nThis guide provides step-by-step instructions to deploy the NoirWatch service using Docker.\n\n### Docker Prerequisites\n\nEnsure you have the following installed on your system:\n\n- Docker\n\n### Using the Dockerfile\n\nTo download the `Dockerfile` from the GitHub repository, run the following command:\n\n```sh\ncurl -O https://raw.githubusercontent.com/binarynoir/noirwatch/main/Dockerfile\n```\n\n### Build and Deploy\n\nNavigate to the directory containing the `Dockerfile` and run the following command to build and start the service:\n\n```sh\ndocker build -t noirwatch-image .\ndocker run -d --restart unless-stopped --name noirwatch noirwatch-image\n```\n\n### Conclusion\n\nYou have successfully deployed the NoirWatch service using Docker. The service will automatically start when the container is created and will restart if it stops unexpectedly. For any further modifications or assistance, feel free to ask!\n\n## Instructions for Running the Tests\n\nTo run the tests for the `NoirWatch` script, follow these steps:\n\n### Prerequisites\n\nEnsure you have the following installed on your system:\n\n- Bash\n- Git (for cloning the repository)\n\n### Steps to Run the Tests\n\n1. **Navigate to the Test Directory**:\n\n   ```bash\n   cd test\n   ```\n\n2. **Update the Test Configuration File:** Open the test_noirwatch.conf file in your preferred text editor and ensure it contains the following configuration:\n\n   ```json\n   {\n   \t\"configuration\": {\n   \t\t\"CACHE_DIR\": \"./test/cache\",\n   \t\t\"LOG_FILE\": \"./test/cache/noirwatch.log\",\n   \t\t\"CHECK_INTERVAL\": \"60s\",\n   \t\t\"TIMEOUT\": \"5s\",\n   \t\t\"SYSTEM_NAME\": \"Test System\",\n   \t\t\"PUSHOVER_NOTIFICATION\": \"false\",\n   \t\t\"PUSHOVER_USER_KEY\": \"\",\n   \t\t\"PUSHOVER_API_TOKEN\": \"\",\n   \t\t\"DESKTOP_NOTIFICATION\": \"false\",\n   \t\t\"VERBOSE\": \"true\",\n   \t\t\"LOG_LEVEL\": \"DEBUG\",\n   \t\t\"THRESHOLD\": \"0\"\n   \t},\n   \t\"urls\": {\n   \t\t\"default\": [\n   \t\t\t{\n   \t\t\t\t\"NAME\": \"Apple Newsroom\",\n   \t\t\t\t\"URL\": \"https://www.apple.com/newsroom/\",\n   \t\t\t\t\"TIMEOUT\": \"5s\",\n   \t\t\t\t\"THRESHOLD\": \"1\",\n   \t\t\t\t\"UPDATED_CMD\": \"./test/test_cmd.sh\",\n   \t\t\t\t\"CMD_TIMEOUT\": \"5s\"\n   \t\t\t},\n   \t\t\t{\n   \t\t\t\t\"NAME\": \"9to5mac Homepage\",\n   \t\t\t\t\"URL\": \"https://9to5mac.com\",\n   \t\t\t\t\"TIMEOUT\": \"10s\",\n   \t\t\t\t\"THRESHOLD\": \"5\",\n   \t\t\t\t\"UPDATED_CMD\": \"./test/test_cmd.sh\",\n   \t\t\t\t\"CMD_TIMEOUT\": \"5s\"\n   \t\t\t}\n   \t\t]\n   \t}\n   }\n   ```\n\n3. **Update the Test URL File:** Open the test_urls.conf file in your preferred text editor and ensure it contains the following URLs:\n\n   ```bash\n   http://example.com\n   http://example.org\n   ```\n\n4. **Make the test script executable**:\n\n   ```bash\n   chmod +x test.sh\n   ```\n\n5. **Run the Test Script:**\n\n   ```bash\n   ./test.sh\n   ```\n\n6. **Run the Test Script with a Custom Configuration File**:\n\n   ```bash\n   ./test.sh /path/to/custom_config_file\n   ```\n\n7. **Clean Up Test Files (optional)**:\n\n   ```bash\n   rm -rf ./test_cache\n   rm -f ./test_noirwatch.log\n   ```\n\n### Summary\n\nThe `test.sh` script will:\n\n1. Create a test configuration file (default or custom).\n2. Run various tests to check the functionality of NoirWatch, including configuration initialization, cache directory creation, log file creation, and website monitoring.\n3. Clean up the test files and directories after the tests are completed, except for the custom configuration file if it was passed in.\n\nFollow these instructions to ensure that NoirWatch is functioning correctly. If you encounter any issues, please open an issue or submit a pull request on the GitHub repository.\n\n## Releases\n\n### Releasing new releases\n\n- Update the changelog with new features and fixes\n- Commit all changed files and create a pull request\n- Run the release script from the project repo's root directory\n\n  ```bash\n  ./scripts/publish-release.md\n  ```\n\n### Manually Releasing new releases\n\n- Create a new GitHub release using the new version number as the \"Tag version\". Use the exact version number and include a prefix `v`\n- Publish the release.\n\n  ```bash\n  git checkout main\n  git pull\n  git tag -a v1.y.z -m \"v1.y.z\"\n  git push --tags\n  ```\n\nRun shasum on the release for homebrew distribution.\n\n```bash\nshasum -a 256 noirwatch-1.x.x.tar.gz\n```\n\nThe release will automatically be drafted.\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.\n\n## Author\n\nJohn Smith III\n\n## Acknowledgments\n\nThanks to all contributors and users for their support and feedback.\n","funding_links":["https://buymeacoffee.com/binarynoir","https://ko-fi.com/binarynoir"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarynoir%2Fnoirwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinarynoir%2Fnoirwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarynoir%2Fnoirwatch/lists"}