Mavusi.ConfigGuard.CLI 1.0.0

ConfigGuard CLI

Command-line tool for ConfigGuard - configuration validation and environment comparison from your terminal.

Installation

As a .NET Global Tool

dotnet tool install --global Mavusi.ConfigGuard.CLI

From Source

cd Mavusi.ConfigGuard.CLI
dotnet pack
dotnet tool install --global --add-source ./bin/Release Mavusi.ConfigGuard.CLI

Verify Installation

configguard --version
configguard --help

Commands

validate - Validate Configuration Files

Validates configuration files for format errors and common issues.

Usage:

configguard validate --file <path> [options]

Options:

• -f, --file <path> - Configuration file path to validate (required)
• -s, --schema <path> - Path to validation schema file (future feature)
• --strict - Enable strict validation mode

Examples:

# Basic validation
configguard validate -f appsettings.json

# Strict validation (fails on warnings)
configguard validate -f appsettings.Production.json --strict

# Validate with schema (planned feature)
configguard validate -f config.json -s config-schema.json

Exit Codes:

• 0 - Success, no errors
• 1 - Validation failed
• 11 - File not found
• 12 - Invalid format
• 99 - General error

---

compare - Compare Configurations

Compares configurations between environments and generates detailed reports.

Usage:

configguard compare --source <path> --target <path> [options]

Options:

• -s, --source <path> - Source configuration file path (required)
• -t, --target <path> - Target configuration file path (required)
• -se, --source-env <name> - Source environment name (default: "Source")
• -te, --target-env <name> - Target environment name (default: "Target")
• -sec, --section <name> - Configuration section to compare (optional)
• -f, --format <format> - Output format: console, json, markdown (default: console)
• -o, --output <path> - Output file path (optional, outputs to console if not specified)
• -fod, --fail-on-diff - Exit with error code if differences found (default: true)

Examples:

# Compare two configuration files
configguard compare -s appsettings.Development.json -t appsettings.Production.json

# Specify environment names
configguard compare \
  -s dev-config.json -t prod-config.json \
  -se "Development" -te "Production"

# Compare specific section
configguard compare \
  -s appsettings.Development.json \
  -t appsettings.Production.json \
  --section "DatabaseConfig"

# Generate JSON report
configguard compare \
  -s dev.json -t prod.json \
  -f json -o comparison-report.json

# Generate Markdown report
configguard compare \
  -s dev.json -t prod.json \
  -f markdown -o comparison.md

# Don't fail on differences (useful for information only)
configguard compare \
  -s dev.json -t staging.json \
  --fail-on-diff false

Exit Codes:

• 0 - Success (configurations identical or --fail-on-diff=false)
• 2 - Differences found (when --fail-on-diff=true)
• 10 - Invalid arguments
• 11 - File not found
• 99 - General error

---

Output Formats

Console (default)

Beautiful terminal-friendly output with colors and formatting:

╔══════════════════════════════════════════════════════════════╗
║            Configuration Comparison Report                   ║
╚══════════════════════════════════════════════════════════════╝

Configuration Type: DatabaseConfig
Source Environment: Development
Target Environment: Production

✗ DIFFERENCES FOUND: 3

JSON

Machine-readable format perfect for automation:

{
  "configType": "DatabaseConfig",
  "isIdentical": false,
  "differenceCount": 3,
  "differences": [...]
}

Markdown

Documentation-ready format for PRs and wikis:

# Configuration Comparison Report

**Configuration Type:** `DatabaseConfig`

## ⚠️ Status: DIFFERENCES FOUND (3)

---

CI/CD Integration

GitHub Actions

name: Config Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0.x'

      - name: Install ConfigGuard
        run: dotnet tool install --global Mavusi.ConfigGuard.CLI

      - name: Validate Configurations
        run: |
          configguard validate -f appsettings.json
          configguard validate -f appsettings.Production.json --strict

      - name: Compare Environments
        run: |
          configguard compare \
            -s appsettings.Development.json \
            -t appsettings.Production.json \
            -f markdown -o config-comparison.md

      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: config-comparison
          path: config-comparison.md

Azure DevOps

steps:
- task: UseDotNet@2
  displayName: 'Use .NET 8'
  inputs:
    version: '8.0.x'

- script: dotnet tool install --global Mavusi.ConfigGuard.CLI
  displayName: 'Install ConfigGuard'

- script: |
    configguard validate -f appsettings.json
    configguard compare \
      -s appsettings.Development.json \
      -t appsettings.Production.json \
      -f json -o $(Build.ArtifactStagingDirectory)/config-comparison.json
  displayName: 'Validate and Compare Configs'

- task: PublishBuildArtifacts@1
  displayName: 'Publish Comparison Report'
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)'
    ArtifactName: 'config-reports'

GitLab CI

config-validation:
  stage: test
  image: mcr.microsoft.com/dotnet/sdk:8.0
  script:
    - dotnet tool install --global Mavusi.ConfigGuard.CLI
    - export PATH="$PATH:$HOME/.dotnet/tools"
    - configguard validate -f appsettings.json
    - configguard compare -s dev.json -t prod.json -f json -o report.json
  artifacts:
    paths:
      - report.json
    when: always

---

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash

echo "Validating configuration files..."

# Find all appsettings files
for file in $(find . -name "appsettings*.json"); do
    echo "Checking $file..."
    configguard validate -f "$file"
    if [ $? -ne 0 ]; then
        echo "❌ Configuration validation failed"
        exit 1
    fi
done

echo "✅ All configurations valid"

---

Exit Code Reference

Code	Meaning	Description
0	Success	Operation completed successfully
1	Validation Failed	Configuration validation errors found
2	Differences Found	Configuration comparison found differences
10	Invalid Arguments	Invalid command-line arguments provided
11	File Not Found	Specified file does not exist
12	Invalid Format	Configuration file format is invalid
99	General Error	Unexpected error occurred

---

Global Options

• -v, --verbose - Enable verbose output (future feature)
• --help - Show help information
• --version - Show version information

---

Examples

Basic Workflow

# 1. Validate your configuration
configguard validate -f appsettings.json

# 2. Compare with production
configguard compare \
  -s appsettings.json \
  -t appsettings.Production.json

# 3. Generate a report for the team
configguard compare \
  -s appsettings.json \
  -t appsettings.Production.json \
  -f markdown -o config-changes.md

Deployment Script

#!/bin/bash

echo "Pre-deployment configuration check..."

# Validate target config
configguard validate -f config/production.json --strict
if [ $? -ne 0 ]; then
    echo "❌ Production config validation failed"
    exit 1
fi

# Compare with previous version
configguard compare \
  -s config/production-previous.json \
  -t config/production.json \
  -f json -o deployment-config-diff.json

echo "✅ Configuration checks passed"

Multi-Environment Check

# Compare staging and production
configguard compare \
  -s staging.json \
  -t production.json \
  -se "Staging" -te "Production" \
  -f markdown -o staging-vs-prod.md

# Compare development and staging
configguard compare \
  -s development.json \
  -t staging.json \
  -se "Development" -te "Staging" \
  -f markdown -o dev-vs-staging.md

---

Troubleshooting

Command not found

If configguard command is not found after installation:

# Check if tools are in PATH
dotnet tool list --global

# Add to PATH (Linux/macOS)
export PATH="$PATH:$HOME/.dotnet/tools"

# Add to PATH (Windows PowerShell)
$env:Path += ";$HOME\.dotnet\tools"

Update Tool

dotnet tool update --global Mavusi.ConfigGuard.CLI

Uninstall Tool

dotnet tool uninstall --global Mavusi.ConfigGuard.CLI

---

See Also

• ConfigGuard Library Documentation
• Environment Comparison Guide
• Quick Start Guide

---

License

MIT