@stacksleuth/cli

Comprehensive Command-Line Interface for StackSleuth

🚀 What is StackSleuth CLI?

StackSleuth CLI is a powerful command-line interface that provides interactive dashboard, real-time monitoring, performance reports, CI/CD integration, and automated performance optimization recommendations. It's your one-stop tool for managing and monitoring application performance from the terminal.

✨ Key Features

• 📊 Interactive Dashboard: Beautiful terminal-based performance dashboard
• 🔄 Real-time Monitoring: Live performance metrics with auto-refresh
• 📈 Performance Reports: Comprehensive performance analysis and reporting
• 🔧 CI/CD Integration: Seamless integration with CI/CD pipelines
• ⚡ Performance Optimization: Automated optimization recommendations
• 🎯 Custom Alerts: Configurable performance alerts and notifications
• 📱 Multi-project Support: Manage multiple projects from a single interface
• 🔍 Deep Analysis: Detailed performance bottleneck analysis

📦 Installation

Global Installation (Recommended)

npm install -g @stacksleuth/cli

yarn global add @stacksleuth/cli

pnpm add -g @stacksleuth/cli

Local Installation

npm install @stacksleuth/cli

yarn add @stacksleuth/cli

🏁 Quick Start

Initialize a New Project

# Initialize StackSleuth in your project
stacksleuth init

# Initialize with specific configuration
stacksleuth init --type=express --database=mongodb

Start Real-time Monitoring

# Start the interactive dashboard
stacksleuth watch

# Watch specific metrics
stacksleuth watch --metrics=cpu,memory,response-time

# Watch with custom refresh interval
stacksleuth watch --interval=1000

Generate Performance Reports

# Generate a comprehensive performance report
stacksleuth report

# Generate report for specific time range
stacksleuth report --from="2024-01-01" --to="2024-01-31"

# Export report to file
stacksleuth report --output=performance-report.html --format=html

CI/CD Integration

# Run performance tests in CI/CD
stacksleuth test --threshold=95 --max-response-time=500ms

# Performance budget enforcement
stacksleuth budget --check --config=.stacksleuth/budget.json

📋 Available Commands

stacksleuth init

Initialize StackSleuth monitoring in your project.

stacksleuth init [options]

Options:
  --type <type>           Project type (express, react, vue, django, etc.)
  --database <db>         Primary database (mongodb, redis, mysql, postgres)
  --config <path>         Custom configuration file path
  --template <template>   Use predefined template
  --interactive           Interactive setup wizard

stacksleuth watch

Start real-time performance monitoring dashboard.

stacksleuth watch [options]

Options:
  --port <port>           Dashboard port (default: 3001)
  --host <host>           Dashboard host (default: localhost)
  --interval <ms>         Refresh interval in milliseconds (default: 2000)
  --metrics <list>        Comma-separated list of metrics to display
  --threshold <value>     Alert threshold for performance issues
  --silent               Run in background without UI

stacksleuth report

Generate comprehensive performance reports.

stacksleuth report [options]

Options:
  --output <file>         Output file path
  --format <format>       Report format (html, json, pdf, markdown)
  --from <date>           Start date (YYYY-MM-DD)
  --to <date>             End date (YYYY-MM-DD)
  --metrics <list>        Specific metrics to include
  --template <template>   Custom report template
  --open                  Open report after generation

stacksleuth test

Run performance tests and validations.

stacksleuth test [options]

Options:
  --threshold <value>     Performance score threshold (0-100)
  --max-response-time <ms> Maximum acceptable response time
  --max-memory <mb>       Maximum memory usage threshold
  --config <path>         Test configuration file
  --output <format>       Test result format (json, junit)
  --fail-fast            Stop on first test failure

stacksleuth optimize

Get automated performance optimization recommendations.

stacksleuth optimize [options]

Options:
  --auto-apply           Automatically apply safe optimizations
  --category <category>  Focus on specific optimization category
  --output <file>        Save recommendations to file
  --format <format>      Output format (json, markdown)
  --interactive          Interactive optimization wizard

📊 Interactive Dashboard

The StackSleuth CLI provides a beautiful, real-time dashboard accessible via your browser:

stacksleuth watch --port=3001

Dashboard features:

• Real-time Metrics: Live CPU, memory, and response time graphs
• Request Tracing: Visual request flow and bottleneck identification
• Performance Alerts: Instant notifications for performance issues
• Historical Data: Performance trends and comparisons
• Custom Widgets: Configurable dashboard layout

🔧 Configuration

Project Configuration (.stacksleuthrc.json)

{
  "project": {
    "name": "My Application",
    "type": "express",
    "version": "1.0.0"
  },
  "monitoring": {
    "enabled": true,
    "sampleRate": 0.1,
    "realTime": true
  },
  "agents": {
    "backend": true,
    "frontend": false,
    "database": ["mongodb", "redis"]
  },
  "alerts": {
    "responseTime": "500ms",
    "memoryUsage": "80%",
    "errorRate": "5%"
  },
  "dashboard": {
    "port": 3001,
    "refreshInterval": 2000,
    "theme": "dark"
  },
  "reports": {
    "outputDir": "./reports",
    "format": "html",
    "includeMetrics": ["performance", "errors", "usage"]
  }
}

Environment Variables

# StackSleuth configuration
export STACKSLEUTH_API_KEY="your-api-key"
export STACKSLEUTH_ENDPOINT="https://your-monitoring-endpoint.com"
export STACKSLEUTH_PROJECT_ID="project-123"
export STACKSLEUTH_ENV="production"

# Dashboard configuration
export STACKSLEUTH_DASHBOARD_PORT=3001
export STACKSLEUTH_DASHBOARD_HOST="0.0.0.0"
export STACKSLEUTH_DASHBOARD_THEME="dark"

📈 Performance Reports

HTML Report Example

stacksleuth report --format=html --output=performance-report.html

Generated report includes:

• Executive Summary: High-level performance overview
• Performance Metrics: Detailed statistics and trends
• Bottleneck Analysis: Identified performance issues
• Optimization Recommendations: Actionable improvement suggestions
• Comparative Analysis: Period-over-period comparisons

JSON Report for API Integration

stacksleuth report --format=json --output=performance-data.json

{
  "summary": {
    "performanceScore": 87,
    "totalRequests": 10524,
    "averageResponseTime": 245,
    "errorRate": 0.03
  },
  "metrics": {
    "cpu": { "avg": 45.2, "peak": 89.1 },
    "memory": { "avg": 512, "peak": 1024 },
    "responseTime": { "p50": 180, "p95": 850, "p99": 1200 }
  },
  "bottlenecks": [
    {
      "type": "database",
      "description": "Slow MongoDB queries detected",
      "impact": "high",
      "recommendation": "Add index on user_id field"
    }
  ]
}

🔄 CI/CD Integration

GitHub Actions

name: Performance Testing
on: [push, pull_request]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install StackSleuth CLI
        run: npm install -g @stacksleuth/cli
      
      - name: Run Performance Tests
        run: |
          stacksleuth test \
            --threshold=90 \
            --max-response-time=500ms \
            --output=junit \
            --config=.stacksleuth/ci-config.json
      
      - name: Generate Performance Report
        run: |
          stacksleuth report \
            --format=html \
            --output=performance-report.html
      
      - name: Upload Performance Report
        uses: actions/upload-artifact@v3
        with:
          name: performance-report
          path: performance-report.html

Jenkins Pipeline

pipeline {
    agent any
    
    stages {
        stage('Performance Testing') {
            steps {
                sh 'npm install -g @stacksleuth/cli'
                sh '''
                    stacksleuth test \
                        --threshold=85 \
                        --max-response-time=1000ms \
                        --fail-fast
                '''
            }
        }
        
        stage('Performance Report') {
            steps {
                sh '''
                    stacksleuth report \
                        --format=html \
                        --output=performance-report.html
                '''
                publishHTML([
                    allowMissing: false,
                    alwaysLinkToLastBuild: true,
                    keepAll: true,
                    reportDir: '.',
                    reportFiles: 'performance-report.html',
                    reportName: 'Performance Report'
                ])
            }
        }
    }
}

🎯 Performance Optimization

Automated Optimization

# Get optimization recommendations
stacksleuth optimize

# Apply safe optimizations automatically
stacksleuth optimize --auto-apply

# Focus on specific areas
stacksleuth optimize --category=database
stacksleuth optimize --category=memory
stacksleuth optimize --category=network

Optimization Categories

• Database Optimization: Query optimization, indexing suggestions
• Memory Management: Memory leak detection, garbage collection tuning
• Network Performance: Request optimization, caching strategies
• Code Performance: Hot path optimization, algorithmic improvements
• Infrastructure: Resource allocation, scaling recommendations

📱 Multi-Project Management

# List all monitored projects
stacksleuth projects list

# Switch between projects
stacksleuth projects switch my-api

# Add new project
stacksleuth projects add my-frontend --type=react

# Compare projects
stacksleuth projects compare my-api my-frontend

🔍 Advanced Features

Custom Dashboards

# Create custom dashboard
stacksleuth dashboard create --template=custom-api.json

# Share dashboard configuration
stacksleuth dashboard export --output=my-dashboard.json
stacksleuth dashboard import --config=my-dashboard.json

Performance Budgets

{
  "budgets": {
    "performance": {
      "responseTime": "< 500ms",
      "throughput": "> 1000 req/s",
      "errorRate": "< 1%"
    },
    "resources": {
      "cpu": "< 70%",
      "memory": "< 2GB",
      "diskIO": "< 100MB/s"
    }
  }
}

# Check performance budget
stacksleuth budget check
stacksleuth budget check --config=custom-budget.json

🛠️ Troubleshooting

Common Issues

CLI Not Found After Installation

# Verify installation
npm list -g @stacksleuth/cli

# Reinstall if necessary
npm uninstall -g @stacksleuth/cli
npm install -g @stacksleuth/cli

Dashboard Not Loading

# Check if port is available
stacksleuth watch --port=3002

# Check firewall settings
stacksleuth watch --host=0.0.0.0

Performance Data Missing

# Verify agent configuration
stacksleuth init --interactive

# Check agent status
stacksleuth status

Debug Mode

# Enable debug logging
DEBUG=stacksleuth:* stacksleuth watch

# Verbose output
stacksleuth watch --verbose

# Log to file
stacksleuth watch --log-file=debug.log

📖 Examples

Basic Express.js Setup

# Initialize in Express.js project
cd my-express-app
stacksleuth init --type=express

# Start monitoring
stacksleuth watch

# Generate daily report
stacksleuth report --from=yesterday --format=html

Microservices Monitoring

# Monitor multiple services
stacksleuth projects add user-service --type=express --port=3001
stacksleuth projects add order-service --type=fastapi --port=3002
stacksleuth projects add notification-service --type=django --port=3003

# Combined dashboard
stacksleuth watch --projects=all

Performance Testing Pipeline

# Run comprehensive performance test
stacksleuth test \
  --threshold=90 \
  --max-response-time=500ms \
  --max-memory=1GB \
  --config=.stacksleuth/perf-test.json

# Generate test report
stacksleuth report \
  --format=json \
  --output=test-results.json \
  --metrics=performance,errors

📚 Resources

• CLI Documentation
• Configuration Guide
• CI/CD Integration
• Performance Budgets

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/Jack-GitHub12/StackSleuth.git
cd StackSleuth
npm install
npm run build

Testing CLI Changes

# Build and link locally
npm run build
npm link

# Test changes
stacksleuth --version
stacksleuth init --help

📄 License

MIT License - see the LICENSE file for details.

Website • Documentation • NPM Registry • GitHub

Made with ⚡ by StackSleuth