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:

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

Perfect for:

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

Commands Reference

Command	Description	Features
`synchronize init`	Interactive configuration setup	Synq key, wallet, sync name configuration
`synchronize start`	Run synchronizer Docker container	Auto platform detection, Docker checks
`synchronize service`	Generate systemd service file	Headless operation, auto-start configuration
`synchronize service-web`	Generate web dashboard service	Persistent web monitoring, NPX path detection
`synchronize status`	Show service status and logs	Color-coded status, recent logs, helpful commands
`synchronize web`	Start web dashboard	Performance metrics, QoS monitoring, port configuration
`synchronize install-docker`	Auto-install Docker (Linux)	Multi-distro support, service configuration
`synchronize fix-docker`	Fix Docker permissions	User group management, permission troubleshooting
`synchronize test-platform`	Test Docker compatibility	Platform testing, architecture validation
`synchronize points`	Show wallet lifetime points	Points breakdown, container stats, API status
`synchronize set-password`	Configure dashboard password	Password setting, security management
`synchronize validate-key [key]`	Validate a synq key	Local format check, remote API validation
`synchronize api`	Interactive Enterprise API setup	Guided enterprise key provisioning with prompts
`synchronize --api <key>`	Automatic Enterprise API setup	Zero-prompt setup using API preferences

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:

Component	Version	Description
synchronizer-cli	2.2.5	The npm package version of this CLI tool
Croquet	2.1.3	The version of Croquet used in the Docker image
Docker Image	latest	The cdrakep/synqchronizer Docker image tag
Launcher ID	cli-2.2.5	The launcher identifier used for the Croquet session

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

Platform	Docker Install	Permission Fix	Service Generation	Web Dashboard	Architecture
Ubuntu/Debian	✅ Auto	✅ Auto	✅ Full	✅ Full	AMD64/ARM64
CentOS/RHEL	✅ Auto	✅ Auto	✅ Full	✅ Full	AMD64/ARM64
Fedora	✅ Auto	✅ Auto	✅ Full	✅ Full	AMD64/ARM64
macOS	📖 Manual	N/A	N/A	✅ Full	AMD64/ARM64
Windows	📖 Manual	N/A	N/A	✅ Full	AMD64

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
xtras		xtras
.DS_Store		.DS_Store
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
COMMAND_FIX_SUMMARY.md		COMMAND_FIX_SUMMARY.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
DEPLOYMENT_SUMMARY.md		DEPLOYMENT_SUMMARY.md
ENTERPRISE.md		ENTERPRISE.md
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
pre-publish-check.js		pre-publish-check.js
security-scan.sh		security-scan.sh
startup-synchronizer-service.sh		startup-synchronizer-service.sh
startup-synchronizer.sh		startup-synchronizer.sh
test-websocket-direct.js		test-websocket-direct.js
websocket-test.js		websocket-test.js

Uh oh!

Folders and files

Latest commit

History

Repository files navigation