1  # KeepSync User Migration Guide
  2  
  3  ## Overview
  4  
  5  This guide helps users migrate from legacy KeepSync CLI implementations to the new **unified CLI architecture**. The migration provides significant benefits including improved performance, simplified usage, and enhanced security with quantum-resistant encryption by default.
  6  
  7  ## Migration Benefits
  8  
  9  ### **Before: Legacy Architecture (17+ CLIs)**
 10  - Multiple CLI binaries with different interfaces
 11  - Provider registration spam at startup
 12  - Complex provider selection process
 13  - Inconsistent command structures
 14  - Manual quantum encryption configuration
 15  - Subprocess-based AWS CLI security risks
 16  - Hardcoded credentials in various locations
 17  
 18  ### **After: Unified CLI Architecture** ✨ **Updated June 2025**
 19  - ✅ **Single CLI binary** (`keepsync`) for all operations
 20  - ✅ **Security Hardened** - Zero hardcoded credentials, native SDK integration
 21  - ✅ **Performance Optimized** - Unified performance manager with auto-tuning
 22  - ✅ **Clean, professional interface** without registration messages
 23  - ✅ **Dynamic provider loading** - only requested providers instantiated
 24  - ✅ **Quantum encryption by default** - enhanced security automatically
 25  - ✅ **Consistent command structure** across all operations
 26  - ✅ **Enterprise-grade security** - Hardware TPM + credential chain management
 27  
 28  ## Quick Migration Summary
 29  
 30  | Legacy CLI | New Unified Command | Notes |
 31  |------------|-------------------|--------|
 32  | `keepsync-cli` | `keepsync sync` | Core sync functionality |
 33  | `keepsync-cli-standalone` | `keepsync sync` | Same unified interface |
 34  | `keepsync-backup` | `keepsync sync --backup` | Backup mode integrated |
 35  | `daemon-standalone` | `keepsync server` | Daemon functionality |
 36  | `tpm-secured-*-demo` | `keepsync security tpm` | TPM management unified |
 37  
 38  ## Step-by-Step Migration
 39  
 40  ### **1. Backup Current Configuration**
 41  
 42  ```bash
 43  # Backup existing configurations
 44  mkdir -p ~/keepsync-migration-backup
 45  cp -r ~/.config/keepsync* ~/keepsync-migration-backup/
 46  cp -r ~/.local/share/keepsync* ~/keepsync-migration-backup/
 47  
 48  # Backup any custom scripts or configurations
 49  cp ~/.bashrc ~/keepsync-migration-backup/bashrc-backup
 50  cp ~/.profile ~/keepsync-migration-backup/profile-backup
 51  ```
 52  
 53  ### **2. Install Unified CLI**
 54  
 55  ```bash
 56  # Stop any running legacy services
 57  systemctl --user stop keepsync-cli 2>/dev/null || true
 58  systemctl --user stop keepsync-daemon 2>/dev/null || true
 59  
 60  # Build and install unified CLI
 61  ./scripts/integrated-build.sh build
 62  make install
 63  
 64  # Verify installation
 65  keepsync version
 66  keepsync --help
 67  ```
 68  
 69  ### **3. Migrate Configuration Files**
 70  
 71  The unified CLI uses standard configuration locations:
 72  - **Config**: `~/.config/keepsync/config.json`
 73  - **Data**: `~/.local/share/keepsync/`
 74  - **Service**: `~/.config/systemd/user/keepsync.service`
 75  
 76  ```bash
 77  # Create unified configuration directory
 78  mkdir -p ~/.config/keepsync
 79  
 80  # Migrate existing configurations (example)
 81  # Note: Adjust paths based on your legacy configuration
 82  if [ -f ~/.config/keepsync-cli/config.json ]; then
 83      cp ~/.config/keepsync-cli/config.json ~/.config/keepsync/config.json
 84  fi
 85  
 86  # Update configuration for unified CLI format
 87  keepsync config migrate --from-legacy
 88  ```
 89  
 90  ### **4. Update Provider Configurations**
 91  
 92  The unified CLI includes 3 quantum-enhanced providers with secure credential management:
 93  
 94  ```bash
 95  # Test provider availability
 96  keepsync sync --list-providers
 97  
 98  # Configure S3 provider (credentials via AWS credential chain - SECURE)
 99  keepsync provider s3 config \
100    --endpoint s3.amazonaws.com \
101    --region us-east-1
102  
103  # Set S3 credentials securely (choose one method):
104  # Method 1: Environment variables
105  export AWS_ACCESS_KEY_ID=your_access_key
106  export AWS_SECRET_ACCESS_KEY=your_secret_key
107  
108  # Method 2: AWS credentials file
109  aws configure
110  
111  # Method 3: IAM instance profile (automatic on EC2)
112  
113  # Configure WebDAV provider
114  keepsync config provider webdav \
115    --url https://your-webdav-server.com \
116    --auth oauth
117  
118  # Configure SFTP provider
119  keepsync config provider sftp \
120    --host your-sftp-server.com \
121    --user your-username \
122    --key ~/.ssh/id_rsa
123  ```
124  
125  **🔒 Security Improvement:** The unified CLI no longer accepts credential flags for enhanced security. All credentials are managed through standard credential chains.
126  
127  ### **5. Migrate Sync Operations**
128  
129  #### **Legacy S3 Sync Commands**
130  ```bash
131  # OLD: Multiple different CLI tools
132  keepsync-cli s3 sync /local/path s3://bucket/path
133  tpm-secured-s3-demo /local/path s3://bucket/path --tpm-enable
134  
135  # NEW: Unified command with quantum encryption by default
136  keepsync sync /local/path s3://bucket/path
137  keepsync sync /local/path s3://bucket/path --tpm-device /dev/tpmrm0
138  ```
139  
140  #### **Legacy WebDAV Sync Commands**
141  ```bash
142  # OLD: Separate CLI with manual configuration
143  keepsync-cli-standalone webdav sync /local/path webdav://server/path
144  tpm-secured-webdav-demo /local/path webdav://server/path
145  
146  # NEW: Unified command with enhanced authentication
147  keepsync sync /local/path webdav://server/path --auth oauth
148  keepsync sync /local/path webdav://server/path --mfa-enabled
149  ```
150  
151  #### **Legacy SFTP Sync Commands**
152  ```bash
153  # OLD: Multiple SFTP tools
154  keepsync-cli sftp sync /local/path sftp://user@server:/path
155  tpm-secured-sftp-demo /local/path sftp://user@server:/path
156  
157  # NEW: Unified command with connection pooling
158  keepsync sync /local/path sftp://user@server:/path --key ~/.ssh/id_rsa
159  keepsync sync /local/path sftp://user@server:/path --connection-pool 20
160  ```
161  
162  ### **6. Migrate Daemon Services**
163  
164  #### **Legacy Daemon Services**
165  ```bash
166  # OLD: Multiple daemon services
167  systemctl --user stop daemon-standalone
168  systemctl --user stop keepsync-cli-daemon
169  systemctl --user disable daemon-standalone
170  systemctl --user disable keepsync-cli-daemon
171  ```
172  
173  #### **New Unified Daemon**
174  ```bash
175  # NEW: Single unified daemon service
176  systemctl --user start keepsync
177  systemctl --user enable keepsync
178  
179  # Check service status
180  systemctl --user status keepsync
181  
182  # View logs
183  journalctl --user -u keepsync -f
184  ```
185  
186  ### **7. Migrate Security Settings**
187  
188  #### **Legacy TPM Configuration**
189  ```bash
190  # OLD: Multiple TPM demo applications
191  go run cmd/tpm-secured-s3-demo/main.go --setup
192  go run cmd/tpm-secured-webdav-demo/main.go --setup
193  go run cmd/tpm-secured-sftp-demo/main.go --setup
194  ```
195  
196  #### **New Unified Security Management**
197  ```bash
198  # NEW: Unified TPM management
199  keepsync security tpm status
200  keepsync security tpm enable --device /dev/tpmrm0
201  keepsync security tpm key-generate --key-name main-sync-key
202  
203  # Quantum encryption is enabled by default
204  keepsync security quantum status
205  keepsync security quantum configure --algorithms ML-KEM,XMSS
206  ```
207  
208  ## Command Reference Migration
209  
210  ### **Core Sync Operations**
211  
212  | Legacy Command | New Unified Command | Notes |
213  |---------------|-------------------|--------|
214  | `keepsync-cli sync` | `keepsync sync` | Same functionality, better performance |
215  | `keepsync-cli-standalone sync` | `keepsync sync` | Unified interface |
216  | `keepsync-backup backup` | `keepsync sync --backup` | Backup mode integrated |
217  | `daemon-standalone` | `keepsync server` | Background daemon service |
218  
219  ### **Provider Management**
220  
221  | Legacy Command | New Unified Command | Notes |
222  |---------------|-------------------|--------|
223  | `keepsync-cli list-providers` | `keepsync sync --list-providers` | All 3 providers shown |
224  | `keepsync-cli configure s3` | `keepsync config provider s3` | Unified configuration |
225  | `keepsync-cli test-connection` | `keepsync sync --test-connection` | Built-in connectivity test |
226  
227  ### **Security & TPM**
228  
229  | Legacy Command | New Unified Command | Notes |
230  |---------------|-------------------|--------|
231  | `tpm-secured-*-demo --setup` | `keepsync security tpm enable` | Unified TPM setup |
232  | `tpm-hardware-test` | `keepsync security tpm status` | Hardware status check |
233  | `quantum-encryption-demo` | `keepsync security quantum` | Quantum crypto management |
234  
235  ### **Performance & Monitoring**
236  
237  | Legacy Command | New Unified Command | Notes |
238  |---------------|-------------------|--------|
239  | `keepsync-cli --performance` | `keepsync status --performance` | Performance monitoring |
240  | `daemon-standalone --metrics` | `keepsync metrics` | Comprehensive metrics |
241  | Manual optimization | `keepsync optimize` | Automatic optimization recommendations |
242  
243  ## Advanced Migration Scenarios
244  
245  ### **Multi-Provider Environments**
246  
247  If you previously used multiple provider-specific CLIs:
248  
249  ```bash
250  # OLD: Multiple binaries and configurations
251  keepsync-s3-cli config --setup
252  keepsync-webdav-cli config --setup  
253  keepsync-sftp-cli config --setup
254  
255  # NEW: Single configuration, multiple providers
256  keepsync config provider s3 --setup
257  keepsync config provider webdav --setup
258  keepsync config provider sftp --setup
259  
260  # Use providers as needed
261  keepsync sync /data s3://bucket/data --provider s3
262  keepsync sync /docs webdav://server/docs --provider webdav
263  keepsync sync /files sftp://server:/files --provider sftp
264  ```
265  
266  ### **Enterprise Environments**
267  
268  For enterprise deployments with multiple users:
269  
270  ```bash
271  # System-wide installation (requires sudo)
272  sudo make install
273  
274  # Configure TPM for enterprise use
275  sudo keepsync security tpm setup --enterprise
276  sudo usermod -a -G tss alice
277  sudo usermod -a -G tss bob
278  
279  # Enterprise attestation setup
280  keepsync security attestation configure --enterprise-policy
281  ```
282  
283  ### **Performance Optimization Migration**
284  
285  The unified CLI includes automatic performance optimization:
286  
287  ```bash
288  # OLD: Manual performance tuning required
289  keepsync-cli sync /huge/dataset s3://bucket/data --workers 8 --chunk-size 64MB
290  keepsync-cli sync /small/files s3://bucket/files --workers 2 --chunk-size 1MB
291  
292  # NEW: Automatic optimization with manual override available
293  keepsync sync /huge/dataset s3://bucket/data  # Automatic optimization
294  keepsync sync /huge/dataset s3://bucket/data --workers 16 --chunk-size adaptive  # Manual tuning
295  ```
296  
297  ## Verification & Testing
298  
299  ### **1. Verify Migration Success**
300  
301  ```bash
302  # Test basic functionality
303  keepsync version
304  keepsync --help
305  keepsync sync --list-providers
306  
307  # Test each provider
308  keepsync sync --test-connection s3://your-bucket/
309  keepsync sync --test-connection webdav://your-server/
310  keepsync sync --test-connection sftp://your-server/
311  
312  # Test TPM integration
313  keepsync security tpm status
314  keepsync security tpm key-list
315  ```
316  
317  ### **2. Performance Comparison**
318  
319  ```bash
320  # Compare sync performance
321  time keepsync sync /test/directory s3://bucket/test --dry-run
322  
323  # Check optimization recommendations
324  keepsync optimize --analyze /your/sync/path
325  
326  # View performance metrics
327  keepsync metrics --provider s3 --timespan 24h
328  ```
329  
330  ### **3. Security Validation**
331  
332  ```bash
333  # Verify quantum encryption
334  keepsync security quantum status
335  
336  # Check TPM hardware integration
337  keepsync security tpm hardware-test
338  
339  # Validate attestation capability
340  keepsync security attestation verify --export-report security-status.json
341  ```
342  
343  ## Common Migration Issues & Solutions
344  
345  ### **Issue: "Command not found" after installation**
346  
347  ```bash
348  # Solution: Update PATH
349  echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
350  source ~/.bashrc
351  
352  # Or check installation location
353  which keepsync
354  ```
355  
356  ### **Issue: Configuration not migrated correctly**
357  
358  ```bash
359  # Solution: Manual configuration migration
360  keepsync config reset
361  keepsync config provider s3 --interactive-setup
362  keepsync config provider webdav --interactive-setup
363  keepsync config provider sftp --interactive-setup
364  ```
365  
366  ### **Issue: TPM access denied**
367  
368  ```bash
369  # Solution: Check TPM permissions
370  ls -la /dev/tpm*
371  groups  # Check if you're in 'tss' group
372  sudo usermod -a -G tss $USER
373  # Log out and back in for group changes to take effect
374  ```
375  
376  ### **Issue: Legacy services still running**
377  
378  ```bash
379  # Solution: Stop all legacy services
380  systemctl --user list-units | grep keepsync
381  systemctl --user stop keepsync-cli 2>/dev/null || true
382  systemctl --user stop daemon-standalone 2>/dev/null || true
383  systemctl --user disable keepsync-cli 2>/dev/null || true
384  systemctl --user disable daemon-standalone 2>/dev/null || true
385  systemctl --user daemon-reload
386  
387  # Start unified service
388  systemctl --user start keepsync
389  ```
390  
391  ## Rollback Plan
392  
393  If you encounter issues and need to rollback:
394  
395  ### **1. Stop Unified CLI**
396  
397  ```bash
398  systemctl --user stop keepsync
399  systemctl --user disable keepsync
400  ```
401  
402  ### **2. Restore Legacy Configuration**
403  
404  ```bash
405  # Restore backed up configurations
406  cp -r ~/keepsync-migration-backup/.config/keepsync* ~/.config/
407  cp -r ~/keepsync-migration-backup/.local/share/keepsync* ~/.local/share/
408  ```
409  
410  ### **3. Reinstall Legacy CLIs** (if needed)
411  
412  ```bash
413  # Restore from backup directories
414  # Note: Legacy CLIs are preserved in backup/old-cli-implementations/
415  cd backup/old-cli-implementations/
416  # Follow previous installation procedures for legacy CLIs
417  ```
418  
419  ## Migration Checklist
420  
421  - [ ] **Backup current configuration and data**
422  - [ ] **Install unified CLI** (`make install`)
423  - [ ] **Verify installation** (`keepsync version`)
424  - [ ] **Migrate configuration files**
425  - [ ] **Update provider settings**
426  - [ ] **Test each provider connection**
427  - [ ] **Migrate daemon services**
428  - [ ] **Configure TPM security** (if applicable)
429  - [ ] **Verify quantum encryption** enabled
430  - [ ] **Test sync operations**
431  - [ ] **Check performance metrics**
432  - [ ] **Update any scripts or automation**
433  - [ ] **Remove legacy CLI references**
434  - [ ] **Document any custom configurations**
435  
436  ## Post-Migration Optimization
437  
438  ### **1. Enable Advanced Features**
439  
440  ```bash
441  # Enable performance optimization
442  keepsync optimize --auto-tune
443  
444  # Configure advanced security
445  keepsync security attestation enable
446  
447  # Setup monitoring
448  keepsync metrics configure --export-interval 1h
449  ```
450  
451  ### **2. Update Scripts and Automation**
452  
453  Update any existing scripts to use the unified CLI:
454  
455  ```bash
456  #!/bin/bash
457  # OLD script
458  keepsync-cli s3 sync /data s3://bucket/data
459  keepsync-cli-standalone webdav sync /docs webdav://server/docs
460  
461  # NEW script  
462  keepsync sync /data s3://bucket/data
463  keepsync sync /docs webdav://server/docs
464  ```
465  
466  ### **3. Configure Monitoring and Alerts**
467  
468  ```bash
469  # Setup performance monitoring
470  keepsync metrics configure --alerts-enabled
471  keepsync metrics thresholds --sync-speed 10MB/s --error-rate 1%
472  
473  # Configure log monitoring
474  journalctl --user -u keepsync --follow
475  ```
476  
477  ## Benefits Achieved
478  
479  After successful migration, you'll have:
480  
481  ✅ **Simplified Management** - Single CLI for all operations  
482  ✅ **Enhanced Performance** - Multi-layered optimization system  
483  ✅ **Improved Security** - Quantum-resistant encryption by default  
484  ✅ **Better User Experience** - Clean, professional interface  
485  ✅ **Easier Maintenance** - Single codebase and configuration  
486  ✅ **Future-Proof Architecture** - Built for long-term scalability
487  
488  ## Support & Resources
489  
490  - **Installation Guide**: [docs/INSTALLATION-GUIDE.md](INSTALLATION-GUIDE.md)
491  - **Production Readiness**: [docs/PRODUCTION-READINESS-SUMMARY.md](PRODUCTION-READINESS-SUMMARY.md)
492  - **Security Architecture**: [docs/MULTI-TIER-HARDWARE-SECURITY-ARCHITECTURE.md](MULTI-TIER-HARDWARE-SECURITY-ARCHITECTURE.md)
493  - **Build System**: `./scripts/integrated-build.sh --help`
494  - **CLI Help**: `keepsync --help`, `keepsync sync --help`, `keepsync security --help`
495  
496  ---
497  
498  **Migration completed successfully!** You now have access to enterprise-grade file synchronization with simplified management and enhanced security.