CLI Monitor is a cross-platform Python tool that repeatedly runs a command, captures its output, optionally logs it, and can even trigger a secondary command whenever a regex pattern is matched.
Because repetitive tasks should be automated...
Unittests status for Win/Lin/Mac environments: 
📖 Table of Contents (expandable)
CLI Monitor is designed to help automate command execution, log outputs, and monitor for specific patterns using regex. If a match is found, the tool can execute an additional command. It handles logging, error reporting, and summary generation with ease.
- Flexible Command Execution: Run any CLI command at a chosen frequency.
- Pattern Matching with Regex: Detect specific output patterns and trigger follow-up actions.
- Smart Log Management: Automatically rotate logs to prevent excessive file sizes.
- Auto-Stop Timer: Set a duration for execution or let it run indefinitely.
- Cross-Platform Compatibility: Works on Windows, Linux, and macOS with Python 3.
- Download cli_monitor.py. Or clone:
git clone https://github.com/Dimos082/cli-monitor.git cd cli-monitor - Run with an argument:
python cli_monitor.py --command "echo Hello" - Stop it at any time (e.g., Ctrl + C) or specify a timer with
--timer. - Check the summary in terminal (or in log file if
--output-filespecified) after. Example:
----- Execution Summary -----
Start Time: 2025-01-04 22:43:24.021834
End Time: 2025-01-04 22:43:25.574156
Duration: 0:00:01.552322
Total Executions: 2
Exceptions: 0
Regex Matches: 0
Number of successful commands executed upon regex match: 0
Number of failed executed commands upon regex match: 0
Termination Reason: Manual termination by userpython cli_monitor.py --command "pgrep my_app || echo NOT_FOUND" --frequency 10 --regex NOT_FOUND --regex-execute bash /path/to/start_my_app.shThis command checks every 10 seconds if my_app is running. If not, it triggers a script to restart it.
Example for Windows:
python cli_monitor.py --command "tasklist | findstr notepad || echo NOT_FOUND" --frequency 5 --regex NOT_FOUND --regex-execute start notepad.exepython cli_monitor.py --frequency 3 --command echo 'Checking System'Prints "Checking System" every 3 seconds.
python cli_monitor.py --output-file memory_log.txt --max-log-size 5 --command echo 'Memory Status: OK'Keeps logs within 5 KB by trimming older entries.
python cli_monitor.py --command "cat /var/log/syslog" --regex "error|fail" --regex-execute "echo 'An issue was detected!'" --timer 10Runs for 10 seconds, searching for "error" or "fail" and executing an alert command when found.
Shells interpret spaces and characters such as | unless they are quoted. Wrap values that include spaces or special characters in quotes when using the CLI.
The --regex-execute flag now accepts multi-word commands without quotes (e.g., --regex-execute echo Match), but quoting remains a safe default across different shells and platforms.
| Argument | Required? | Default | Description |
|---|---|---|---|
--command |
Yes | None | The main command to run repeatedly. |
--output-file |
No | None | Full path to a log file. If omitted, logs appear in the console only. |
--frequency |
No | 1.0 | Time interval in seconds between each execution (Min: 0.1; Max: 100000). |
--max-log-size |
No | 1024 | Max log file size in KB. If exceeded, the script prunes oldest lines. |
--timer |
No | 0 | Stops automatically after N seconds. 0 means run indefinitely. |
--regex |
No | None | A regex pattern to find in the command output. |
--regex-execute |
No | None | A command to run once per iteration if the regex pattern is matched. |
This project uses pytest for unit testing. To run the tests locally, ensure you have pytest installed, and then execute:
pytest testsThis will run all the test cases in the tests directory and display the results.
The script uses the following exit codes:
0: Success1: General error2: Regex validation error
GitHub Actions will:
- Run tests in several environments
- Bump version in cli_monitor.py
- Create a GitHub Release
- Attach cli_monitor.py for download
GitHub Actions automatically bumps versions when commit messages include specific keywords:
- Patch (X.Y.Z+1********) → PATCH: Fixed issue
- Minor (X.Y+1.0********) → MINOR: Added logging
- Major (X+1.0.0********) → MAJOR: Breaking change
Triggering a Release:
To increment a patch number 1.0.1+:
git commit -m "PATCH: Fixed issue in regex matching"
git push origin mainTo increment major number 1+.0.0, commit a major change:
git commit -m "MAJOR: Refactored CLI to use POSIX structure"
git push origin mainIf you find a bug or have a feature request, check out open issues or create a new one. Your feedback is valuable!
I welcome contributions to make CLI Monitor even better! If you have an idea for an improvement or new test cases, feel free to:
- Fork the repository
- Create a new feature branch:
git checkout -b feature/NewFeature - Write your code and include tests if applicable
- Run
pytestto ensure all tests pass. - Make your changes and commit with the version number incrementation:
git commit -m "MINOR: Added feature XYZ" - Push your changes:
git push origin feature/NewFeature - Open a pull request 🐈⬛
Internally, cli_monitor.py uses an Observer design pattern to keep modules loosely coupled:
The controller (subject) runs commands, logs output, and notifies other modules (observers) like the RegexMonitor, ErrorHandler, and LoggerModule about data or events. This structure makes the code more maintainable and extensible. To add a new “observer” (e.g., a custom notification module), simply attach it to the flow in the controller without modifying existing logic significantly.
This project is licensed under the Apache 2.0 - see the LICENSE file for details.
If you find cli_monitor.py useful, consider giving it a ⭐ on GitHub!