🔒 CloudSync-CLI

An open-source, Git-like version control CLI for secure cloud-to-local synchronization via encrypted SSH tunnels.

"Your configs, your cloud, your rules — no public repos required."

---

🚀 Quick Installation

Option 1: One-Line Automated Installers (Recommended)

🐧 Linux & 🍏 macOS (curl / bash)

curl -fsSL https://raw.githubusercontent.com/Tech4File/cloudsync-cli/main/installer/install.sh | bash

🪟 Windows (PowerShell)

irm https://raw.githubusercontent.com/Tech4File/cloudsync-cli/main/installer/Install-CloudSync.ps1 | iex

Option 2: Install via npm (Global CLI)

npm install -g cloudsync-cli

Option 3: Install via GitHub Packages (GPR)

npm install -g @tech4file/cloudsync-cli --registry=https://npm.pkg.github.com

Option 4: Download Standalone Binaries (Windows / Linux / macOS)

Download single-executable binaries directly from the latest GitHub Releases:

• 🪟 cloudsync.exe / cloudsync-windows-x64.zip (Windows)
• 🐧 cloudsync-linux-x64 (Linux x64)
• 🍏 cloudsync-macos-x64 (macOS x64 / ARM64)

---

📋 Quick Start

# 1. Initialize configuration
cloudsync init --host your-server.com --user username --port 22

# 2. Generate .cloudsyncignore file
cloudsync ignore --template node

# 3. Stage files for version control
cloudsync stage .env config.json

# 4. Commit staged changes locally
cloudsync commit "Update database config"

# 5. Securely upload to remote target
cloudsync upload --profile default

# 6. Share and receive files over peer-to-peer sessions
cloudsync share ./data --port 8095 --password mysecret
cloudsync fetch http://192.168.1.5:8095/share/abc1234 --password mysecret

# 7. Check operational health & network connectivity
cloudsync doctor

🌐 Universal Deployment: Where & When to Use

CloudSync-CLI enables anywhere-to-anywhere synchronization across trusted and untrusted environments without compromising credentials:

Environment & Use-Case	Scenario & Threat Model	How CloudSync-CLI Protects You
🤖 Untrusted AI Agent Sandboxes	Transferring code, logs, and datasets to/from ephemeral AI agent sandboxes (Docker, VM, E2B, Modal) where you cannot risk storing permanent SSH private keys or cloud credentials.	Use ephemeral cloudsync share and cloudsync fetch with user-defined passwords. The sandbox connects over an encrypted, time-limited tunnel with zero exposure of your permanent credentials.
☁️ Cloud Server & VPS Sync	Synchronizing .env, microservice certificates, and database configs between staging and production VPS instances (AWS, GCP, DigitalOcean).	Direct pure SSH2 encrypted tunnels with memory-only stream transfers. No sensitive configuration data ever touches third-party public Git repositories.
🛡️ Air-Gapped & High-Security Nodes	Maintaining version history on machines with restricted or no internet access.	Native AES-256-GCM encrypted local history snapshots with Scrypt key derivation. Staged changes are stored as encrypted blobs on disk requiring --passphrase to unpack.
⚡ CI/CD Build Pipelines & Runners	Transferring large pre-built binaries or caches between distributed CI workers without vendor lock-in.	Multi-stream parallel concurrency (-j, --concurrency) with streaming 64KB chunk SHA-256 integrity verification.
👥 Peer-to-Peer Developer Handoff	Sharing database dumps, debug logs, or staging configs directly between team members behind NATs or firewalls.	Ephemeral HTTP sharing with rate limiting (60 req/min), CORS protection, security headers, and SHA-256 password authentication.

---

📁 Repository Structure

Path	Description
cloudsync-cli/	The npm package directory containing CLI source, commands, transport engine, and VCS modules.
.github/workflows/ci.yml	Continuous Integration matrix testing Node 18, 20, 22 on Ubuntu, Windows, and macOS.
.github/workflows/release.yml	Automated build & publication pipeline — produces standalone binaries, releases to npmjs, publishes to GitHub Packages (GPR), and creates GitHub Releases.

---

⚙️ Automated CI/CD & Release Pipeline

Pipeline	Trigger	Automated Operations
PR Verification (ci.yml)	Pull Request to dev / main	Runs multi-node test matrix across Node.js LTS and current.
Release & Promotion (release.yml)	Push to dev	Runs full test matrix $\rightarrow$ builds standalone binaries (Windows .exe, Linux, macOS) $\rightarrow$ publishes to npmjs $\rightarrow$ publishes to GitHub Packages $\rightarrow$ creates GitHub Release $\rightarrow$ automatically promotes release & verified commits to main with zero duplicate triggers ([skip ci]).

---

🛡️ Security & Hardening Highlights

• AES-256-GCM Encrypted Snapshots: Local history snapshot archives encrypted on disk via Scrypt key derivation with authenticated AES-256-GCM (cloudsync commit --encrypt --passphrase <secret>).
• Streaming 64KB Chunk Integrity: Stream-based SHA-256 checksum hashing for large file archives without memory spikes.
• Zero-Dependency Security Core: Hardened with prototype pollution protection (safeJsonParse), path traversal filtering (safePath), and SSRF-safe hostname validation.
• Encrypted SSH Channels: Native ssh2 transport layer supporting keypair auth, custom ports, and SCP/SFTP/RSYNC protocols with multi-stream concurrency (-j, --concurrency).
• HTTP Share Server Security: Built-in HTTP sharing with rate limiting (60 req/min), CORS restriction, password authentication, and security headers (CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff).

---

📄 License

Distributed under the MIT License. See LICENSE for details.

Security Policy: SECURITY.md | Contributing Guidelines: CONTRIBUTING.md