CLI Monitor 🖥️

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)

• Overview
• Features
• Quick Start
• Example Commands
• Arguments Overview
• Testing
• Exit Codes
• Automated Version Bumping, Testing and Release
• Contributing
• License

Overview

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.

Features

• 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.

▶️ Quick Start

1. Download cli_monitor.py. Or clone:

   git clone https://github.com/Dimos082/cli-monitor.git
   cd cli-monitor

2. Run with an argument:

   python cli_monitor.py --command "echo Hello"

3. Stop it at any time (e.g., Ctrl + C) or specify a timer with --timer.
4. Check the summary in terminal (or in log file if --output-file specified) 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 user

🔼 Back to top

🎛️ Example Commands

Process Monitoring (babysit/watchdog mode)

python cli_monitor.py --command "pgrep my_app || echo NOT_FOUND" --frequency 10 --regex "NOT_FOUND" --regex-execute "bash /path/to/start_my_app.sh"

This 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.exe"

Repeating Echo

python cli_monitor.py --frequency 3 --command echo 'Checking System'

Prints "Checking System" every 3 seconds.

Log File Management

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.

Detecting Errors in Logs

python cli_monitor.py --command "cat /var/log/syslog" --regex "error|fail" --regex-execute "echo 'An issue was detected!'" --timer 10

Runs for 10 seconds, searching for "error" or "fail" and executing an alert command when found.

🔼 Back to top

💬 Arguments Overview

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.

🔼 Back to top

🧪 Testing

This project uses pytest for unit testing. To run the tests locally, ensure you have pytest installed, and then execute:

pytest tests

This will run all the test cases in the tests directory and display the results.

---

🚦 Exit Codes

The script uses the following exit codes:

• 0: Success
• 1: General error
• 2: Regex validation error

🔼 Back to top

🔄 Automated Version Bumping, Testing and Release

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 main

To increment major number 1+.0.0, commit a major change:

git commit -m "MAJOR: Refactored CLI to use POSIX structure"
git push origin main

🔼 Back to top

🤝 Contributing

If 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 pytest to 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 🐈‍⬛

Observer Design Pattern

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.

📜 License

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!

🔼 Back to top