synchronizer-cli

🚀 Complete CLI toolkit for Multisynq Synchronizer - Docker container management, auto-installation, systemd service generation, and real-time web dashboard with performance monitoring.

✨ Features

🎯 Core Functionality

• 🔧 Interactive Setup - Guided configuration with prompts for Synq key and wallet
• 🐳 Smart Docker Management - Auto-install Docker on Linux with multi-distro support
• 🔐 Permission Handling - Automatic Docker permissions fix with user group management
• ⚙️ Systemd Integration - Generate service files for headless operation
• 🌐 Cross-platform - Full support for Linux, macOS, and Windows
• 🏗️ Platform Detection - Automatic Docker architecture detection (ARM64/AMD64)

🌐 Web Dashboard & Monitoring

• 📊 Performance Metrics - Real-time traffic, sessions, and user monitoring
• 🎯 Quality of Service (QoS) - Visual monitoring with reliability, availability, and efficiency scores
• 📈 Live Charts - Circular progress indicators with color-coded status (green/yellow/red)
• 📋 Real-time Logs - Systemd logs with syntax highlighting and auto-refresh
• 🔗 API Documentation - Built-in endpoint documentation with method badges
• 🔄 Auto-refresh - Dashboard updates every 5 seconds automatically

🔧 Advanced Features

• 🛠️ Built-in Troubleshooting - Comprehensive error handling and helpful solutions
• 🔍 Dynamic NPX Detection - Smart detection of npm/npx installation paths
• 📦 Lightweight - Only ~16KB package size with minimal dependencies
• 🚀 Enhanced Help - Comprehensive feature documentation in CLI help
• 🔒 Security Features - Masked sensitive data display with click-to-reveal

🏢 Enterprise Features

• 🔑 Enterprise API Integration - Automatic synq key provisioning via Enterprise API
• ⚡ Automated Setup - Zero-prompt configuration using API preferences (synchronize --api <key>)
• 🌐 Cloud Deployment Script - Ready-to-use startup-synchronizer.sh for EC2, DigitalOcean, etc.
• 🏗️ Multi-cloud Support - Automated deployment across AWS, Azure, Google Cloud, DigitalOcean
• 📋 Enterprise Dashboard - Centralized management of multiple synchronizers
• 🔐 Enterprise Security - API key-based authentication and secure credential storage

Prerequisites

• Node.js v10 or higher
• Docker (can be auto-installed on Linux)
• Synq key from Multisynq platform

Installation

npm install -g synchronizer-cli

Quick Start

# Interactive configuration (recommended for first-time users)
synchronize init

# Or Enterprise API setup
synchronize api

# Or one-command deployment (perfect for automation)

# Start synchronizer container
synchronize start

# Launch web dashboard
synchronize web

🚀 One-Command Deployment

Perfect for automation, deployment scripts, and VPS installations:

# Basic deployment

# Full deployment with all options
  --key your-synq-key \
  --wallet your-wallet-address \
  --name "My Production Sync" \
  --port 8080 \
  --metrics-port 8081 \
  --password secure-dashboard-password

🔧 Deploy Command Options

• --key <synq-key> or -k - Required: Your Synq key
• --wallet <address> or -w - Required: Your wallet address
• --name <name> or -n - Optional: Sync name for reference
• --port <port> or -p - Optional: Dashboard port (default: 3000)
• --metrics-port <port> or -m - Optional: Metrics port (default: 3001)
• --password <password> - Optional: Dashboard password for security

What it does:

1. 📝 Creates configuration from command line parameters
2. 🐳 Starts synchronizer Docker container
3. 🌐 Launches web dashboard on specified ports
4. ✅ Ready to use in under 30 seconds

Perfect for:

• VPS deployments
• CI/CD pipelines
• Automated setups
• Docker environments
• Quick testing

Commands Reference

Web Dashboard

The comprehensive web dashboard provides real-time monitoring and system insights:

# Start with automatic port detection
synchronize web

# Use custom dashboard port
synchronize web --port 8080

# Use custom metrics port  
synchronize web --metrics-port 8081

# Use both custom ports
synchronize web --port 8080 --metrics-port 8081

🌐 Port Configuration

Automatic Port Detection (default behavior):

• Dashboard starts on port 3000, finds next available if busy
• Metrics starts on dashboard port + 1, finds next available if busy
• Prevents conflicts by ensuring different ports for each service

Manual Port Configuration:

• --port <number> or -p <number>: Set dashboard port
• --metrics-port <number> or -m <number>: Set metrics port
• CLI validates ports don't conflict and exits with error if they match
• Useful for firewall rules, reverse proxies, or multi-instance deployments

🎨 Dashboard Features

📊 Performance Metrics

• Total Traffic: Cumulative data transfer with smart formatting (KB/MB/GB)
• Active Sessions: Real-time session count monitoring
• Traffic Rates: Live in/out traffic with bytes per second
• User Count: Connected users tracking
• Smart Data: Metrics reflect actual service status

🎯 Quality of Service (QoS)

• Overall Score: Circular progress indicator with color coding
  • 🟢 Excellent (80%+): Green indicator for optimal performance
  • 🟡 Good (60-79%): Yellow indicator for acceptable performance
  • 🔴 Poor (<60%): Red indicator requiring attention
• Individual Metrics:
  • Reliability: Service stability percentage
  • Availability: Uptime and accessibility percentage
  • Efficiency: Performance optimization score

🔗 API Endpoints Documentation

• Method Badges: Clear GET/POST indicators
• Endpoint Paths: Monospace formatting for clarity
• Descriptions: Detailed functionality explanations
• Live Links: Direct access to API endpoints

⚙️ System Information

• Service Status: Real-time running/stopped/failed indicators
• Configuration Display: Masked Synq key with click-to-reveal
• Platform Details: Architecture and hostname information
• Quick Actions: One-click access to common operations

🌐 Server Architecture

The web dashboard runs on dual servers:

• Dashboard Server (default port 3000): Main web interface
• Metrics Server (default port 3001): JSON API endpoints

Automatic port detection prevents conflicts, or use custom ports with --port and --metrics-port options

📡 API Endpoints

Dashboard API (Port 3000)

• GET / - Main dashboard interface
• GET /api/status - System and service status JSON
• GET /api/logs - Recent systemd logs JSON
• GET /api/performance - Performance metrics and QoS data
• POST /api/install-web-service - Generate web dashboard systemd service

Metrics API (Port 3001)

• GET /metrics - Comprehensive system metrics JSON
• GET /health - Health check endpoint for monitoring

Docker Management

Automatic Installation

If Docker is not installed, synchronizer-cli offers automatic installation:

synchronize install-docker

Supported Linux distributions:

• Ubuntu/Debian: APT package management with GPG key verification
• CentOS/RHEL/Fedora: YUM/DNF package management
• Automatic service setup: Docker daemon start and enable
• User group management: Automatic docker group addition

Permission Management

Fix Docker permission issues automatically:

synchronize fix-docker

This command:

• Adds your user to the docker group
• Provides logout/login instructions
• Offers testing commands for verification

Platform Compatibility

Test Docker platform compatibility across architectures:

synchronize test-platform

Testing includes:

• linux/amd64 compatibility testing
• linux/arm64 compatibility testing
• Platform recommendation based on system architecture
• Comprehensive error reporting and troubleshooting

Systemd Service Management

Synchronizer Service

Generate and install the main synchronizer service:

synchronize service
sudo cp ~/.synchronizer-cli/synchronizer-cli.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable synchronizer-cli
sudo systemctl start synchronizer-cli

Web Dashboard Service

Generate a persistent web dashboard service:

synchronize service-web
sudo cp ~/.synchronizer-cli/synchronizer-cli-web.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable synchronizer-cli-web
sudo systemctl start synchronizer-cli-web

Features:

• Dynamic NPX Detection: Automatically finds npm/npx installation path
• Path Verification: Tests multiple common installation locations
• Fallback Support: Handles various Node.js installation methods (nvm, homebrew, etc.)

Configuration

Configuration is stored in ~/.synchronizer-cli/config.json:

{
  "userName": "optional-sync-name",
  "key": "your-synq-key",
  "wallet": "your-wallet-address", 
  "secret": "generated-secret",
  "hostname": "system-hostname",
  "syncHash": "generated-sync-hash",
  "depin": "wss://api.multisynq.io/depin",
  "launcher": "cli"
}

Cloud Deployment

For automated cloud instance deployment, synchronizer-cli includes a production-ready startup script:

startup-synchronizer.sh

Ready-to-deploy cloud automation script for Enterprise API users

# Download and customize for your environment
curl -o startup-synchronizer.sh https://raw.githubusercontent.com/multisynq/synchronizer-cli/main/startup-synchronizer.sh

# Replace API key placeholder
sed -i 's/\[your-api-key\]/your-enterprise-api-key/g' startup-synchronizer.sh

# Deploy to cloud instance (AWS EC2, DigitalOcean, Google Cloud, etc.)
# Use as User Data script during instance creation

Features:

• ✅ Complete automation - from fresh instance to running synchronizer
• ✅ Multi-cloud compatible - AWS EC2, DigitalOcean, Google Cloud, Azure
• ✅ Enterprise API integration - uses synchronize --api for hands-free setup
• ✅ Error handling - robust deployment with failure detection
• ✅ Progress logging - visual feedback during installation

Supported Platforms:

• AWS EC2 (Ubuntu AMI)
• DigitalOcean Droplets
• Google Cloud Compute Engine
• Azure Virtual Machines
• Any Ubuntu/Debian cloud instance

See ENTERPRISE.md for complete deployment examples and multi-cloud instructions.

Version Information

The synchronizer-cli ecosystem uses several versioned components:

When using the CLI, the launcher ID is automatically set to match the CLI version (e.g., cli-2.2.5/docker-2.1.3) to ensure session compatibility. The Docker image is configured to use the correct Croquet version internally.

Version History

• 2.2.12: Added Port config
• 2.2.5: Added cloud deployment startup script and enhanced Enterprise documentation
• 2.2.4: Enhanced Enterprise API integration with web interface support and automatic setup
• 2.2.3: Added Enterprise API integration with automatic synq key provisioning
• 2.2.2: Improved wallet points API integration and intelligent container management
• 2.0.8: Fixed API validation to properly include synchronizer nickname
• 2.0.7: Improved lifetime points tracking with direct registry API integration
• 2.0.6: Added synq key validation with both local format checking and remote API verification
• 2.0.5: Added version information to documentation and improved README
• 2.0.4: Added intelligent Docker image update checking to avoid unnecessary downloads
• 2.0.3: Fixed Docker image to use Croquet 2.0.1 and added version identification in launcher ID
• 2.0.2: Added multi-architecture Docker image support (ARM64/AMD64)
• 2.0.1: Initial stable release with web dashboard

Enhanced CLI Experience

Comprehensive Help Output

Run synchronize --help for detailed feature information:

• 🎯 Feature highlights with emoji indicators
• 🌐 Web dashboard capabilities overview
• 🔧 Troubleshooting features summary
• 📦 Package information with links
• 🔗 Homepage and issues direct links

Smart Error Handling

• Docker not found: Automatic installation prompts
• Permission denied: Clear fix instructions with commands
• Platform mismatch: Architecture-specific troubleshooting
• Service failures: Detailed error analysis and solutions

Troubleshooting Guide

Common Issues & Solutions

Docker Installation Issues

# Auto-install Docker (Linux only)
synchronize install-docker

# Manual installation check
docker --version

Permission Problems

# Fix Docker permissions
synchronize fix-docker

# Verify after logout/login
docker run hello-world

Platform Architecture Issues

# Test platform compatibility
synchronize test-platform

# Check system architecture
uname -m

Service Status Problems

# Check detailed service status
synchronize status

# View live logs
journalctl -u synchronizer-cli -f

NPX/Node.js Issues

# Check NPX detection
synchronize service-web

# Verify Node.js installation
node --version
npm --version

Platform Support Matrix

Performance & Monitoring

Real-time Metrics

• Traffic Monitoring: Bytes transferred with smart formatting
• Session Tracking: Active connection monitoring
• User Analytics: Connected user statistics
• QoS Scoring: Automated quality assessment

Health Monitoring

• Service Status: Running/stopped/failed detection
• Docker Health: Container and daemon status
• System Resources: Memory, CPU, and load monitoring
• Uptime Tracking: Service availability metrics

Security Features

• Masked Credentials: Synq keys hidden by default with click-to-reveal
• Secure Storage: Configuration stored in user home directory
• Permission Validation: Docker access verification
• Service Isolation: Systemd service runs with user permissions

Development & Contributing

Package Information

• Size: ~16KB package, ~65KB unpacked
• Dependencies: Minimal (chalk, commander, inquirer, express)
• Node.js: Compatible with v10+
• License: Apache-2.0

Contributing

• Issues: Report bugs and feature requests on GitHub
• Pull Requests: Contributions welcome
• Documentation: Help improve this README

License

Apache-2.0 © ceedeepee

Latest Version: Check npm for the most recent release with new features and improvements.