mret

Enterprise-grade meta-CLI toolkit for modern development workflows

Table of Contents

• Overview
• Installation
• Quick Start
• Core Features
• Command Reference
  • Security & Compliance
  • Development Tools
  • Testing & Quality Assurance
  • Build & Deployment
  • Git Workflow
  • Analysis & Optimization
• Configuration
• Use Cases
• Best Practices
• Architecture
• Security
• Performance
• Contributing
• License

Overview

mret is a comprehensive command-line interface toolkit designed for modern software development teams. It consolidates 40+ essential development operations into a single, unified interface, eliminating context switching and streamlining workflows across security, testing, deployment, and code quality domains.

Key Capabilities

• Security-First Architecture: AES-256 encryption for sensitive data, automated secret detection, and vulnerability management
• CI/CD Integration: Local testing of GitHub Actions workflows before deployment
• Intelligent Code Analysis: Bundle size optimization, dependency graph visualization, and build performance profiling
• Enterprise Compliance: License auditing, security scanning, and configurable policy enforcement
• Cross-Platform Support: Seamless operation across macOS, Linux, and Windows environments
• Extensibility: Custom command framework and alias system for team-specific workflows

Installation

NPM (Recommended)

npm install -g mret

Yarn

yarn global add mret

Verification

mret --version
mret --help

System Requirements

• Node.js: 18.x or higher
• npm: 8.x or higher
• Operating System: macOS 10.15+, Ubuntu 20.04+, Windows 10+

Quick Start

Initialize a new project with best practices:

# Create project structure
mret init

# Configure security
mret env encrypt
mret secrets scan

# Set up quality gates
mret hooks install
mret coverage --threshold 80

# Verify dependencies
mret audit check
mret license

# Test deployment pipeline
mret act validate

Core Features

Security & Compliance

Environment Variable Encryption

Military-grade AES-256-CBC encryption for sensitive configuration data. Supports multiple environments with automatic backup and rollback capabilities.

Key Features:

• PBKDF2 key derivation for enhanced security
• Password confirmation to prevent accidental overwrites
• Temporary viewing mode without file persistence
• Environment comparison and diff visualization

Secret Detection

Pattern-based scanning for exposed credentials across your codebase. Detects AWS keys, GitHub tokens, API secrets, private keys, and custom patterns.

Supported Detection Patterns:

• AWS Access Keys & Secret Keys
• GitHub Personal Access Tokens
• OAuth Tokens
• Private SSH/RSA Keys
• Slack Tokens
• Stripe API Keys
• Google API Keys
• JWT Tokens
• Generic API Keys & Secrets

Vulnerability Management

Integrated dependency security auditing with npm, yarn, and pnpm support. Provides severity-based filtering, interactive remediation, and automated fix capabilities.

Capabilities:

• Real-time vulnerability scanning
• Severity classification (Critical, High, Moderate, Low, Info)
• Interactive fix workflows
• Automated patch application
• Breaking change detection
• CI/CD integration support

License Compliance

Automated license auditing for all project dependencies with configurable allow-lists and policy enforcement.

Development Tools

Interactive Command Builder

Visual command construction interface with pre-built templates for common development tasks. Supports Docker, Git, NPM, and framework-specific commands.

Template Categories:

• Container Operations (Docker build, run, compose)
• Version Control (Git commit, push, branch management)
• Package Management (NPM, Yarn, PNPM)
• Framework Scaffolding (React, Next.js, Vue, Vite)

Shell Auto-Completion

Native completion support for Bash, Zsh, and Fish shells with dynamic command discovery and argument suggestions.

Installation:

# Auto-detect shell and install
mret completion install

# Specific shell
mret completion install --shell zsh

# Generate script for manual installation
mret completion generate --shell bash > /etc/bash_completion.d/mret

Command Alias System

Create persistent shortcuts for frequently used command sequences with parameter support.

Example Usage:

# Define aliases
mret alias create deploy-staging "npm run build && firebase deploy --only hosting:staging"
mret alias create test-ci "npm run lint && npm test -- --coverage && npm run build"

# Execute aliases
mret run deploy-staging
mret run test-ci

Testing & Quality Assurance

GitHub Actions Local Testing

Execute GitHub Actions workflows locally using nektos/act, enabling pre-deployment validation and faster iteration cycles.

Workflow:

# Install act runtime
mret act setup

# List available workflows
mret act list

# Test specific workflow
mret act run ci

# Test specific job
mret act run ci --job build

# Dry run
mret act run ci --dry-run

# Validate syntax
mret act validate

Test Coverage Tracking

Parse and analyze test coverage reports from Jest, NYC, and other coverage tools. Enforce minimum coverage thresholds in CI/CD pipelines.

Configuration:

# Check coverage with default threshold (80%)
mret coverage

# Set custom threshold
mret coverage --threshold 90

# Integrate with CI
mret coverage --threshold 85 || exit 1

Build & Deployment

Multi-Platform Deployment

Unified deployment interface for Vercel, Netlify, and Firebase with automatic platform detection and configuration.

Supported Platforms:

• Vercel: Automatic project detection and deployment
• Netlify: Site configuration and build optimization
• Firebase: Hosting, Functions, and Firestore deployment

Usage:

# Auto-detect platform
mret deploy

# Explicit platform
mret deploy --provider vercel
mret deploy --provider netlify
mret deploy --provider firebase

Build Performance Profiling

Measure and analyze build times to identify bottlenecks and optimization opportunities.

# Profile build command
mret profile "npm run build"

# Output includes:
# - Total build time
# - Performance recommendations
# - Bottleneck identification

Database Backup Automation

Automated backup solutions for PostgreSQL, MySQL, and MongoDB with configurable retention policies.

Supported Databases:

# PostgreSQL
mret db backup --type postgres --db myapp --user admin

# MySQL
mret db backup --type mysql --host db.example.com --db production

# MongoDB
mret db backup --type mongo --host localhost --port 27017 --db myapp

Git Workflow

Branch Management

Intelligent cleanup of merged branches with safety checks and remote synchronization.

Features:

# Clean local merged branches
mret git cleanup

# Include remote branches
mret git cleanup --remote

# Preview changes
mret git cleanup --dry-run

Conventional Commits

Interactive commit message builder following Conventional Commits specification.

Commit Types:

• feat: New features
• fix: Bug fixes
• docs: Documentation updates
• style: Code style changes
• refactor: Code refactoring
• perf: Performance improvements
• test: Test additions or modifications
• chore: Maintenance tasks

Workflow:

mret git commit

# Interactive prompts for:
# 1. Commit type
# 2. Scope (optional)
# 3. Description
# 4. Body (optional)
# 5. Breaking changes flag

Changelog Generation

Automatic CHANGELOG.md generation from commit history with categorization and linking.

# Generate full changelog
mret changelog

# Between versions
mret changelog --from v1.0.0 --to v2.0.0

.gitignore Management

Template-based .gitignore generation from gitignore.io with project type detection.

# Interactive selection
mret gitignore

# Specific templates
mret gitignore --templates node,vscode,macos

# List available
mret gitignore --list

Analysis & Optimization

Bundle Size Analysis

Detailed bundle composition analysis with size tracking and budget enforcement.

Capabilities:

# Analyze bundle
mret bundle analyze

# Custom build command
mret bundle analyze --build-command "webpack --mode production"

# Size budget check
mret bundle check --max-size 500

# CI integration
mret bundle check --max-size 1000 || exit 1

Docker Image Optimization

Dockerfile analysis with best practice recommendations and security improvements.

Analysis Includes:

• Multi-stage build detection
• Layer optimization suggestions
• Base image version pinning
• Security hardening recommendations
• Size optimization tips

# Analyze Dockerfile
mret docker optimize

# Analyze specific file
mret docker optimize -f Dockerfile.prod

# Image size analysis
mret docker size
mret docker size myapp:latest

Dependency Graph Visualization

Visual representation of package dependency tree with circular dependency detection.

# Display graph
mret deps

# Save to file
mret deps --output dependencies.txt

Port Management

Process identification and management for network ports.

# Check port availability
mret port check 3000

# Kill process on port
mret port kill 3000

# Find free port
mret port find

# Find in range
mret port find --start 8000 --end 9000

Command Reference

Security & Compliance

Environment Management

Encryption:

mret env encrypt [--file .env] [--output .env.encrypted]

Decryption:

mret env decrypt [--file .env.encrypted] [--output .env]

Temporary Viewing:

mret env view [--file .env.encrypted]

Environment Comparison:

mret env diff <file1> <file2>

Environment Switching:

mret env use <environment>  # dev, staging, prod, etc.

Secret Scanning

Scan Project:

mret secrets scan [--path ./src] [--exclude node_modules,dist]

Output: Lists all detected secrets with:

• Secret type
• File location and line number
• Preview snippet
• Remediation recommendations

Dependency Audit

Security Scan:

mret audit check [--level <low|moderate|high|critical>] [--production] [--json]

Interactive Fix:

mret audit fix [--force]

Outdated Packages:

mret audit outdated [--major] [--json]

License Compliance

Audit Licenses:

mret license [--allowed <comma-separated-licenses>]

Example:

mret license --allowed MIT,Apache-2.0,BSD-3-Clause,MIT

Development Tools

Custom Commands

Add Command:

mret add <name> <command>

Remove Command:

mret remove <name>

List Commands:

mret list

Execute Command:

mret run <name> [args...]

Command Builder

Interactive Mode:

mret build-cmd

Category Filter:

mret build-cmd --category docker

Aliases

Create:

mret alias create <name> <command>

List:

mret alias list

Remove:

mret alias remove <name>

Testing & Quality Assurance

GitHub Actions

Setup:

mret act setup

Run Workflow:

mret act run [workflow] [--job <job>] [--event <event>] [--dry-run]

List Workflows:

mret act list [--json]

Validate:

mret act validate

Coverage

Check Coverage:

mret coverage [--threshold <percent>]

Pre-commit Hooks

Install:

mret hooks install

Uninstall:

mret hooks uninstall

Build & Deployment

Deployment

Deploy:

mret deploy [--provider <vercel|netlify|firebase>]

Profiling

Profile Build:

mret profile <command>

SSL Certificates

Generate:

mret ssl generate [--domain <domain>] [--days <days>]

Database Backup

Backup:

mret db backup --type <postgres|mysql|mongo> [--host <host>] [--port <port>] [--db <database>] [--user <user>] [--output <path>]

Git Workflow

Branch Management

Cleanup:

mret git cleanup [--remote] [--dry-run]

Commits

Conventional Commit:

mret git commit

Changelog

Generate:

mret changelog [--from <tag>] [--to <tag>]

Gitignore

Generate:

mret gitignore [--templates <templates>] [--list]

Analysis & Optimization

Bundle Analysis

Analyze:

mret bundle analyze [--build-command <cmd>] [--open]

Check Budget:

mret bundle check [--max-size <kb>]

Docker Optimization

Optimize:

mret docker optimize [-f <dockerfile>]

Size Analysis:

mret docker size [image]

Dependency Graph

Visualize:

mret deps [--output <file>]

Port Management

Check:

mret port check <port>

Kill:

mret port kill <port>

Find Free:

mret port find [--start <port>] [--end <port>]

Utility Commands

Auto-fix

Run Fixes:

mret fix [--all]

Includes:

• npm audit fix
• ESLint auto-fix
• Prettier formatting

Configuration

Setup:

mret config setup

Get/Set:

mret config get <key>
mret config set <key> <value>
mret config unset <key>

List:

mret config list

Configuration

Configuration File: mret.config.js

Define custom commands and workflows:

module.exports = {
  // Simple string commands
  test: 'npm test',
  build: 'npm run build',
  lint: 'eslint . --ext .ts,.tsx',
  
  // Multi-step commands
  deploy: 'npm run build && npm run test && firebase deploy',
  
  // Platform-specific commands
  'docker:build': 'docker build -t myapp:latest .',
  'docker:run': 'docker run -p 3000:3000 myapp:latest',
  
  // Function-based commands for complex logic
  greet: async (...args) => {
    console.log(`Hello, ${args.join(' ')}!`);
  },
  
  // Conditional commands
  'deploy:prod': async () => {
    const { execSync } = require('child_process');
    if (process.env.NODE_ENV !== 'production') {
      throw new Error('Must be in production environment');
    }
    execSync('npm run build && firebase deploy --only hosting:production');
  }
};

Configuration Storage: .mretconfig

Managed automatically by mret:

{
  "firebase": {
    "apiKey": "...",
    "projectId": "..."
  },
  "aliases": {
    "dp": "deploy --provider vercel",
    "tc": "test && coverage"
  },
  "preferences": {
    "defaultShell": "zsh",
    "theme": "default"
  }
}

Use Cases

Enterprise Development Team

Scenario: Large development team with strict security and compliance requirements.

Implementation:

# Initial setup
mret init
mret hooks install
mret completion install

# Security baseline
mret env encrypt
mret secrets scan
mret audit check --level high
mret license --allowed MIT,Apache-2.0

# Quality gates
mret coverage --threshold 90
mret bundle check --max-size 500

# CI/CD pipeline testing
mret act validate
mret act run ci

Open Source Project

Scenario: Public repository requiring automated changelog and contribution guidelines.

Implementation:

# Setup contribution workflow
mret gitignore --templates node,vscode,macos
mret hooks install

# Generate documentation
mret changelog
mret license

# Quality checks
mret audit check
mret secrets scan

Microservices Architecture

Scenario: Multiple services with independent deployment pipelines.

Implementation:

# Per-service commands in mret.config.js
module.exports = {
  'service:user:build': 'cd services/user && npm run build',
  'service:user:test': 'cd services/user && npm test',
  'service:user:deploy': 'cd services/user && firebase deploy --only functions:user',
  
  'service:api:build': 'cd services/api && npm run build',
  'service:api:test': 'cd services/api && npm test',
  'service:api:deploy': 'cd services/api && firebase deploy --only functions:api'
};

Best Practices

Environment Management

DO:

• Always encrypt production secrets
• Use environment-specific files (.env.dev, .env.prod)
• Maintain backups before switching environments
• Regular secret rotation

DON'T:

• Commit unencrypted .env files
• Share encryption passwords via insecure channels
• Use same secrets across environments

Security Scanning

Recommended Workflow:

# Pre-commit
mret secrets scan
mret audit check --level high

# Pre-deployment
mret bundle check
mret coverage --threshold 80
mret license

CI/CD Integration

GitHub Actions Example:

name: Quality Gates
on: [push, pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g mret
      - run: mret secrets scan
      - run: mret audit check --level moderate
      - run: mret license --allowed MIT,Apache-2.0,MIT
      - run: mret coverage --threshold 80

Git Workflow

Recommended:

# Before commit
mret git commit  # Use conventional commits

# Regular maintenance
mret git cleanup

# Release preparation
mret changelog

Architecture

Plugin System

mret uses a modular architecture with independent command modules:

src/
├── commands/          # Command implementations
│   ├── security/     # Security-related commands
│   ├── testing/      # Testing and QA commands
│   ├── build/        # Build and deployment
│   └── git/          # Git utilities
├── utils/            # Shared utilities
│   ├── encryption.ts # Cryptography functions
│   ├── firebase.ts   # Firebase integration
│   └── loader.ts     # Configuration loading
└── index.ts          # CLI entry point

Extension Points

Custom commands can be added via:

1. Configuration File: mret.config.js
2. Alias System: mret alias create
3. Plugin System: (Planned for v2.0)

Security

Encryption Specification

Algorithm: AES-256-CBC
Key Derivation: PBKDF2
Iterations: 10,000
Salt Length: 16 bytes
IV Length: 16 bytes

Secret Detection Patterns

Regular expression patterns for common secret types are maintained in src/commands/secrets.ts. Custom patterns can be added by extending the SECRET_PATTERNS array.

Data Privacy

• All encrypted data remains local
• No telemetry or analytics collection
• Firebase integration is optional and user-controlled
• No external API calls without explicit user action

Privacy & Security

Privacy-First Design

mret is built with privacy as a core principle:

• Zero Telemetry: No analytics, tracking, or data collection
• Local-First: All operations performed on your machine
• No Cloud Dependencies: Works completely offline (except optional features)
• Transparent: Open source with auditable code

Data Handling

What We DON'T Collect:

• Personal information
• Usage statistics
• System information
• File contents
• IP addresses
• Any identifiable data

What Stays Local:

• Configuration files (~/.mretconfig)
• Encrypted environment files
• Command aliases
• All project data

Optional Cloud Features

Firebase Integration (Optional):

• Requires explicit setup: mret config setup
• Only used for mret world commands
• You control what data to publish
• Can be deleted anytime: mret world delete

Compliance

mret complies with major data protection regulations:

• GDPR (EU): Privacy by design, local data processing
• DPDP (India): Explicit consent, user data control
• CCPA (California): No data sales, user rights respected
• PIPEDA (Canada): Transparent data practices

Full Details: See PRIVACY.md

Security Features

Encryption:

• Algorithm: AES-256-CBC
• Key Derivation: PBKDF2 (10,000 iterations)
• Industry-standard implementation

Secret Detection:

• Pattern-based scanning for exposed credentials
• No data transmission
• Local analysis only

Vulnerability Management:

• Integrated with npm/yarn/pnpm audits
• Severity-based filtering
• Automated remediation

Responsible Disclosure:

• Security issues: [email protected]
• See SECURITY.md for details

Performance

Benchmarks

Command execution times (approximate):

| Command | Duration | Notes | |---------|----------|-------| | mret env encrypt | < 100ms | Depends on file size | | mret secrets scan | 1-3s | Depends on project size | | mret audit check | 2-5s | Network dependent | | mret bundle analyze | Varies | Depends on build time | | mret git cleanup | < 500ms | Local operation |

Optimization Tips

• Use --exclude patterns for faster scanning
• Enable caching for repeated operations
• Run expensive operations (bundle analysis) in dedicated CI steps

Contributing

Contributions are welcome! Please follow these guidelines:

Development Setup

git clone https://github.com/yourusername/mret.git
cd mret
npm install
npm run build
npm link

Testing

npm test
npm run lint

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes using conventional commits
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• TypeScript strict mode
• ESLint configuration
• Prettier formatting
• Conventional Commits

License

MIT License - see LICENSE file for details.

Maintainers

• @mreshank

Acknowledgments

Built with:

• Commander.js - CLI framework
• Inquirer.js - Interactive prompts
• Chalk - Terminal styling
• Ora - Terminal spinners
• nektos/act - GitHub Actions testing
• crypto-js - Cryptography

GitHub Repository • Report Issues • Privacy Policy • Security

Made with care for developers worldwide