A powerful CLI tool for real-time system performance monitoring
Project Sentinel is a modern Command-Line Interface (CLI) tool designed to monitor real-time system performance metrics, specifically CPU and memory utilization. Built with TypeScript and Node.js, it provides system administrators, developers, and DevOps engineers with an accessible, efficient way to gather, display, and export system performance data directly from the terminal.
- Live Terminal Updates: Continuous monitoring with configurable refresh intervals
- Visual Progress Bars: Color-coded metrics with threshold-based warning indicators
- Auto-Termination: Optional duration-based monitoring with graceful shutdown
- Point-in-Time Metrics: Instant system state capture
- Multiple Output Formats: Text or JSON output for scripting integration
- Verbose Mode: Detailed system information including uptime and swap usage
- CSV Format: Spreadsheet-compatible exports for analysis
- JSON Format: Structured data for programmatic consumption
- Multi-Sample Collection: Gather historical data with configurable intervals
- Append Mode: Add new samples to existing export files
- Windows (PowerShell & CMD)
- macOS (Intel & Apple Silicon)
- Linux (all major distributions)
- Node.js >= 18.0.0 (LTS recommended)
- npm or yarn package manager
# Clone the repository
git clone https://github.com/your-org/project-sentinel.git
cd project-sentinel
# Install dependencies
npm install
# Build the project
npm run build
# Install globally (optional)
npm install -g .# Install dependencies
npm install
# Run in development mode
npm run devStart real-time system monitoring with live terminal updates:
# Basic monitoring with default settings (1 second refresh)
sentinel monitor
# Monitor every 500ms for 60 seconds
sentinel monitor -i 500 -d 60
# Quiet mode with custom thresholds
sentinel monitor --quiet --cpu 90 --mem 75
# All options specified
sentinel monitor --interval 1000 --duration 300 --threshold-cpu 80 --threshold-memory 85Monitor Output:
╔══════════════════════════════════════╗
║ SENTINEL - System Monitor ║
╠══════════════════════════════════════╣
║ CPU Usage: ███████░░░ 72.5% ⚠️ ║
║ Memory: ██░░░░░░░░ 12.3% ✅ ║
║ Disk I/O: 125 MB/s ║
║ Network: 45 MB/s in / 12 MB/s out ║
╚══════════════════════════════════════╝
Capture a single point-in-time metrics snapshot:
# Simple snapshot with text output
sentinel snapshot
# Verbose mode with JSON output
sentinel snapshot --verbose --format json
# Short flags equivalent
sentinel snapshot -v -f jsonSnapshot Output (text):
System Snapshot - 2026-04-16T14:30:00.000Z
===========================================
CPU: 45.2% (4 of 8 cores active)
Memory: 8.2 GB / 16 GB (51.2%)
Swap: 0.5 GB / 4 GB (12.5%)
Uptime: 7 days, 3 hours, 22 minutes
Snapshot Output (JSON):
{
"timestamp": "2026-04-16T14:30:00.000Z",
"cpu": {
"usage": 45.2,
"cores": 8,
"active": 4,
"frequency": 2400
},
"memory": {
"used": 8589934592,
"total": 17179869184,
"percentage": 51.2,
"free": 8589934592
}
}Export metrics data to file for external analysis:
# Export single snapshot as JSON
sentinel export metrics.json
# Collect 100 samples every 5 seconds as CSV
sentinel export performance.csv -f csv -n 100 -i 5000
# Append new samples to existing file
sentinel export metrics.json --append
# All options specified
sentinel export output.json --format json --samples 50 --interval 2000 --appendCSV Export Example:
timestamp,cpu_usage,cpu_cores,memory_used,memory_total,memory_percentage
2026-04-16T14:30:00.000Z,45.2,8,8589934592,17179869184,51.2
2026-04-16T14:30:05.000Z,48.7,8,8796093040,17179869184,51.2| Option | Short | Default | Description |
|---|---|---|---|
--interval <ms> |
-i |
1000 |
Refresh interval in milliseconds |
--duration <sec> |
-d |
null |
Auto-stop after duration (seconds) |
--quiet |
-q |
false |
Suppress colored output |
--threshold-cpu <pct> |
--cpu |
80 |
CPU warning threshold (%) |
--threshold-memory <pct> |
--mem |
80 |
Memory warning threshold (%) |
| Option | Short | Default | Description |
|---|---|---|---|
--verbose |
-v |
false |
Include detailed metrics |
--format <fmt> |
-f |
text |
Output format (text/json) |
| Option | Short | Default | Description |
|---|---|---|---|
<output-file> |
— | (required) | Output file path |
--format <fmt> |
-f |
json |
Export format (json/csv) |
--samples <n> |
-n |
1 |
Number of samples to collect |
--interval <ms> |
-i |
1000 |
Interval between samples |
--append |
-a |
false |
Append to existing file |
Create a .env file in the project root for custom configuration:
# Environment configuration
NODE_ENV=production
LOG_LEVEL=info
# Custom thresholds
CPU_WARNING_THRESHOLD=80
MEMORY_WARNING_THRESHOLD=80For advanced use cases, configure Sentinel programmatically:
import { setupCLI } from './src/cli';
// Custom configuration
const config = {
defaultInterval: 1000,
defaultDuration: null,
thresholds: {
cpu: 80,
memory: 80
},
output: {
colored: true,
format: 'text'
}
};Project Sentinel follows a modular, service-oriented architecture designed for maintainability and testability:
┌─────────────────────────────────────────────────────────────┐
│ CLI Layer │
│ (commander.js) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ monitor │ │ snapshot │ │ export │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Command Layer │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ monitor.ts │ │ snapshot.ts │ │ export.ts │ │
│ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │
└──────────┼──────────────────┼──────────────────┼─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Service Layer │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ MetricsCollector │ │ ReportGenerator │ │
│ └────────┬───────────┘ └────────┬───────────┘ │
│ │ │ │
│ ┌────────────────────┐ │ │
│ │ FileExporter │◄─────────┘ │
│ └────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Model Layer │
│ (src/models/metrics.ts) │
│ SystemMetrics | CpuMetrics | MemoryMetrics │
│ MetricsHistory | ExportOptions | MonitorOptions │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Utility Layer │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ logger.ts │ │constants.ts│ │formatters.ts│ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
monitor.ts: Handles continuous monitoring loop with interval-based updatessnapshot.ts: Captures single-point metrics with format selectionexport.ts: Manages file export operations with multi-sample support
metrics-collector.ts: Core service interfacing withsysteminformationpackagereport-generator.ts: Formats output usingchalkandmustachefile-exporter.ts: Handles file I/O operations with append mode support
- Type-safe TypeScript interfaces for all data structures
- Strong typing for metrics, configuration, and export options
logger.ts: Centralized logging with severity levelsconstants.ts: Platform detection and configuration constantsformatters.ts: Byte/duration formatting helpers
User Input → CLI Parser → Command Handler → Services → Models → External APIs
↓
Report Generator → Terminal/File Output
- Service Layer Pattern: Separates business logic from command handlers
- Factory Pattern: ReportGenerator creates different output formats
- Strategy Pattern: MetricsCollector adapts to platform differences
- Async/await: Non-blocking I/O for responsive terminal experience
| Risk | Severity | Mitigation |
|---|---|---|
| Privilege Escalation | Medium | No elevated permissions required for basic metrics |
| Path Traversal | Low | Input validation and path sanitization |
| Information Disclosure | Low | Sensitive data excluded from default output |
- All file paths validated (prevents directory traversal)
- User input sanitized for file operations
- No sensitive system data logged
- Safe file writing with proper encoding
- Memory usage bounded for large exports
- Standard User: Full functionality for basic metrics
- Administrator/Root: Required for detailed hardware metrics on some platforms
-
Fork the repository
git clone https://github.com/your-org/project-sentinel.git cd project-sentinel -
Install dependencies
npm install
-
Run tests before making changes
npm test -
Make your changes and run the development server
npm run dev
-
Run the full test suite
npm run test:coverage
-
Lint and format your code
npm run lint npm run format
-
Type check
npm run type-check
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests
npm run test:integration
# Run tests with coverage report
npm run test:coverage
# Watch mode for development
npm run test:watchThis project uses ESLint and Prettier for code consistency:
- ESLint: Code linting rules
- Prettier: Code formatting
- TypeScript: Strict mode enabled
Please follow the existing code style and conventions when contributing.
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2026 Project Sentinel Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Built with TypeScript
- CLI framework: commander
- System metrics: systeminformation
- Terminal styling: chalk
- Loading indicators: ora
- Template engine: mustache
Project Sentinel v1.0.0 | © 2026 Project Sentinel - Created by Sapthesh