CLI Commands Unification and Rationalization

[peter7775]

Issue: CLI Commands Unification and Rationalization

🛠️ Feature Request: Unified and Clear CLI Interface

Problem Statement

Currently, the application lacks clear CLI commands structure, making it difficult for users to understand what exactly they are executing. Users face several challenges:

• Ambiguous execution modes: No clear distinction between regular transformation, live transformation with metrics, benchmark mode, etc.
• Configuration confusion: Unclear how to select, create, or validate configurations
• Mixed responsibilities: Single executable handles multiple distinct operations without clear separation
• Poor user experience: Users must guess what mode the application will run in based on configuration files
• Difficult debugging: Hard to isolate issues when all functionality is bundled into one command

Current State

# Current unclear approach
./sql-graph-visualizer                           # What does this do exactly?
CONFIG_PATH=config.yml ./sql-graph-visualizer   # Still unclear what mode

Proposed Solution

Implement a unified CLI interface with clear, purpose-specific commands that make execution intent explicit.

Proposed CLI Structure

1. Main Command Structure

sql-graph-visualizer [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]

2. Core Commands

Transform Commands

# Standard one-time transformation
sql-graph-visualizer transform [--config=path] [--dry-run] [--output=format]

# Live transformation with real-time updates
sql-graph-visualizer transform --live [--config=path] [--metrics] [--interval=5s]

# Transform with performance monitoring
sql-graph-visualizer transform --performance [--config=path] [--export-metrics]

Server Commands

# Start web server for visualization
sql-graph-visualizer serve [--config=path] [--port=3000] [--api-port=8080]

# Start with live performance monitoring
sql-graph-visualizer serve --live [--config=path] [--performance]

# Start in demo mode with simulated data
sql-graph-visualizer serve --demo [--sample-data=chinook]

Configuration Commands

# Create new configuration interactively
sql-graph-visualizer config create [--template=basic|advanced|mysql|postgresql]

# Validate existing configuration
sql-graph-visualizer config validate [--config=path]

# Show current configuration
sql-graph-visualizer config show [--config=path]

# List available configuration templates
sql-graph-visualizer config templates

# Generate configuration from database schema
sql-graph-visualizer config generate --database=connection_string

Performance Commands

# Run performance benchmarks
sql-graph-visualizer benchmark [--config=path] [--duration=60s] [--output=json]

# Start performance monitoring daemon
sql-graph-visualizer monitor [--config=path] [--interval=5s] [--export=prometheus]

# Analyze existing performance data
sql-graph-visualizer analyze [--data-path=path] [--format=report|json|html]

Utility Commands

# Check database connectivity
sql-graph-visualizer check [--config=path] [--database] [--neo4j]

# Export graph data
sql-graph-visualizer export [--config=path] [--format=json|cypher|graphml] [--output=file]

# Import graph data
sql-graph-visualizer import [--input=file] [--format=json|cypher] [--target=neo4j]

# Show version and build info
sql-graph-visualizer version [--verbose]

# Show help for specific command
sql-graph-visualizer help [command]

3. Global Options

--config, -c        Configuration file path (default: config/config.yml)
--verbose, -v       Verbose logging
--quiet, -q         Quiet mode (errors only)
--log-level         Set log level (debug|info|warn|error)
--log-format        Set log format (text|json)
--no-color          Disable colored output
--help, -h          Show help
--version           Show version

Usage Examples

Basic Transformation

# Simple one-time transformation
sql-graph-visualizer transform --config=config/mysql-prod.yml

# Dry run to see what would happen
sql-graph-visualizer transform --dry-run --config=config/test.yml

# Transform and export results
sql-graph-visualizer transform --output=json > results.json

Live Performance Monitoring

# Start live server with performance metrics
sql-graph-visualizer serve --live --performance --port=3000

# Transform with live performance injection
sql-graph-visualizer transform --live --metrics --interval=5s

Configuration Management

# Create new MySQL configuration
sql-graph-visualizer config create --template=mysql

# Generate config from existing database
sql-graph-visualizer config generate --database="mysql://user:pass@host/db"

# Validate configuration before use
sql-graph-visualizer config validate --config=config/production.yml

Performance Analysis

# Run comprehensive benchmark
sql-graph-visualizer benchmark --duration=300s --config=config/load-test.yml

# Start monitoring daemon
sql-graph-visualizer monitor --interval=10s --export=prometheus

# Analyze performance data
sql-graph-visualizer analyze --data-path=./metrics --format=html

Development and Debugging

# Check all connections
sql-graph-visualizer check --config=config/dev.yml --database --neo4j

# Start demo server with sample data
sql-graph-visualizer serve --demo --sample-data=chinook --port=3000

# Verbose transformation for debugging
sql-graph-visualizer transform --verbose --config=config/debug.yml

Implementation Requirements

1. CLI Framework

• Use cobra or similar CLI framework for Go
• Implement proper command hierarchy and help system
• Support completion for bash/zsh shells
• Provide man pages for documentation

2. Configuration System

# Enhanced configuration with mode specification
app:
  mode: "transform"  # transform|serve|benchmark|monitor
  
execution:
  dry_run: false
  live_mode: false
  performance_monitoring: false
  metrics_injection: false
  
server:
  enabled: false
  port: 3000
  api_port: 8080
  
performance:
  benchmarking:
    enabled: false
    duration: "60s"
    
  monitoring:
    enabled: false
    interval: "5s"
    export_format: "json"

3. Command Validation

• Validate command combinations (e.g., can't use --live with export)
• Check required dependencies for each command
• Provide helpful error messages with suggestions
• Implement configuration validation before execution

4. Output Formatting

# Structured output formats
--output=json       # Machine-readable JSON
--output=yaml       # Human-readable YAML  
--output=table      # Formatted table
--output=csv        # CSV for data analysis
--format=plain      # Plain text (default)
--format=colored    # Colored output

5. Error Handling

• Consistent error codes across commands
• Helpful error messages with next steps
• Proper exit codes for CI/CD integration
• Detailed error logging with context

Migration Strategy

Phase 1: Core Commands (Week 1-2)

• Implement basic CLI framework
• Add transform and serve commands
• Implement global options and help system
• Basic configuration validation

Phase 2: Configuration Management (Week 3)

• Implement config command group
• Add configuration templates
• Configuration generation from database schema
• Interactive configuration creation

Phase 3: Performance Commands (Week 4)

• Implement benchmark command
• Add monitor command for daemon mode
• Implement analyze command for data analysis
• Performance metrics export/import

Phase 4: Utilities and Polish (Week 5)

• Add check, export, import commands
• Implement shell completion
• Add comprehensive help documentation
• Create man pages

Benefits

1. 🎯 Clear Intent: Each command has a specific, well-defined purpose
2. 🔧 Better UX: Users know exactly what will happen before execution
3. 🐛 Easier Debugging: Issues can be isolated to specific functionality
4. 📚 Better Documentation: Each command can have detailed help and examples
5. 🔄 CI/CD Friendly: Clear commands work better in automation
6. 📈 Scalability: Easy to add new functionality without confusion
7. 🎓 Learning Curve: New users can discover functionality through help system

Backward Compatibility

To maintain compatibility during migration:

# Legacy support (deprecated warnings)
./sql-graph-visualizer                    # Shows deprecation warning, runs 'serve'
CONFIG_PATH=x ./sql-graph-visualizer     # Shows warning, runs 'transform --config=x'

# New clear commands
sql-graph-visualizer serve               # Clear intent
sql-graph-visualizer transform --config=x  # Explicit configuration

Success Metrics

• ✅ Reduced support requests about "what does this command do?"
• ✅ Improved onboarding time for new users
• ✅ Better CI/CD integration with clear exit codes
• ✅ Increased feature discoverability through help system
• ✅ Reduced configuration errors through validation commands

Related Issues

• Performance Graph Snapshot System (depends on clear benchmark commands)
• Configuration template system
• Documentation improvements

---

Priority: High
Complexity: Medium
Estimated Effort: 3-4 weeks
Dependencies: None (independent improvement)

Implementation Checklist

• Choose and integrate CLI framework (cobra recommended)
• Design command structure and help system
• Implement core transform and serve commands
• Add configuration management commands
• Implement performance-related commands
• Add utility commands (check, export, import)
• Create comprehensive help and documentation
• Add shell completion support
• Implement backward compatibility layer
• Write migration guide for existing users