# NimPak Remote-Aware CLI Guide ## Overview The enhanced NimPak CLI provides comprehensive remote repository management with trust-first security, bloom filter-optimized synchronization, and intelligent binary caching. This guide covers the new remote-aware commands implemented in Task 15.1e. ## Repository Management ### Adding Repositories ```bash # Basic repository addition with interactive trust verification nip repo add https://packages.nexusos.org # Add with custom priority and auto-trust nip repo add https://community.nexusos.org --priority=75 --trust=auto # Add private repository with prompt-based trust nip repo add https://private.company.com --trust=prompt --name=company-internal ``` **Interactive Trust Flow:** ``` πŸ”‘ Fetching repository manifest…done (BLAKE3: a1b2…) πŸ”’ Repository signing key fingerprint: 7A2F 3C9D 4EBA 11B4 9F32 8C77 E1A4 57C9 B912 0AF3 ─────────────────────────────────────────────────── Compare this with https://packages.nexusos.org/fingerprint or verify through official channels. Do you trust this key? [y/N] y βœ… Repository added successfully πŸš€ Repository 'packages.nexusos.org' is ready for use ``` ### Listing Repositories ```bash # Human-readable format with trust badges nip repo list # Machine-readable JSON output nip repo list --output=json # YAML format for configuration management nip repo list --output=yaml ``` **Example Output:** ``` Configured Repositories: ================================================== βœ… 🟒 official URL: https://packages.nexusos.org Type: RepoCommunity, Priority: 100 Trust Score: 0.95 Last Sync: 2025-01-08 14:30 🟑 🟒 community URL: https://community.nexusos.org Type: RepoCommunity, Priority: 75 Score: 0.72 Last Sync: 2025-01-08 14:25 ``` ### Synchronizing Repositories ```bash # Sync all repositories with bloom filter optimization nip repo sync # Sync specific repository nip repo sync official # Bandwidth-limited sync nip repo sync --max-bw=5MB/s ``` ## Enhanced Package Installation ### Binary-First Installation ```bash # Install with binary preference (default) nip install nginx # Force binary installation nip install nginx --prefer-binary # Install from specific repository nip install nginx --repo=community # Install with trust level requirement nip install nginx --trust-level=0.8 ``` **Installation Flow with Trust Verification:** ``` πŸ“¦ Installing package: nginx πŸš€ Preferring binary packages for faster installation πŸ“‹ Package: nginx v1.24.0 πŸ”’ Trust Score: 0.87 🎯 Binary package available - using pre-compiled version ⬇️ Downloading package... βœ… Package installed successfully ``` ### Source Build Fallback ```bash # Force source build even if binary available nip install nginx --no-binary # Install with bandwidth limit nip install nginx --max-bw=10MB/s ``` ## Cache Management ### Cache Status ```bash # Display cache statistics nip cache status # JSON output for monitoring nip cache status --output=json ``` **Example Output:** ``` Cache Status: ============================== πŸ“Š Size: 2.4 GB πŸ“¦ Objects: 15,420 🎯 Hit Rate: 87.0% πŸ—œοΈ Compression: 65.0% 🧹 Last Cleanup: 2025-01-07T14:30:00Z ``` ### Cache Cleanup ```bash # Clean cache entries older than 30 days nip cache clean # Preview cleanup without deleting nip cache clean --dry-run # Custom age threshold nip cache clean --max-age=7 ``` ## Mirror Management ### Adding Mirrors ```bash # Add mirror for load balancing nip mirror add edge https://edge.nexusos.org # Add with custom priority nip mirror add local http://local-mirror:8080 --priority=90 ``` ### Listing Mirrors ```bash # Display mirror health status nip mirror list # JSON output for monitoring nip mirror list --output=json ``` **Example Output:** ``` Configured Mirrors: ================================================== 🟒 official (Priority: 100) URL: https://packages.nexusos.org Latency: 45.2ms Reliability: 98.5% Last Sync: 2025-01-08 14:30 🟑 edge (Priority: 75) URL: https://edge.nexusos.org Latency: 120.8ms Reliability: 92.1% Last Sync: 2025-01-08 14:28 ``` ### Mirror Synchronization ```bash # Sync all mirrors with load balancing nip mirror sync # Sync specific mirror nip mirror sync edge # Sync with progress display nip mirror sync --show-progress ``` ## Progressive Help System ### General Help ```bash # Overview of all commands nip --help # Category-based command listing nip repo --help # Detailed help with examples nip repo --help=examples ``` ### Command-Specific Help ```bash # Repository management help nip repo add --help # Installation options nip install --help # Cache management options nip cache --help ``` ## Global Options ### Output Formats ```bash # JSON output for scripting nip repo list --output=json # YAML output for configuration nip cache status --output=yaml # KDL output (NexusOS native) nip mirror list --output=kdl ``` ### Bandwidth Management ```bash # Global bandwidth limit nip --max-bw=10MB/s repo sync # Per-command bandwidth limit nip install nginx --max-bw=5MB/s # Bandwidth window configuration nip --max-bw=peak:20MB/s,avg:10MB/s mirror sync ``` ### Verbose Mode ```bash # Enable detailed logging nip --verbose repo add https://example.com # Combine with other options nip --verbose --output=json cache status ``` ## Trust and Security Features ### Trust Badges - βœ… **Green**: High trust score (β‰₯0.8), verified signatures - 🟑 **Yellow**: Medium trust score (0.5-0.8), some verification - πŸ”΄ **Red**: Low trust score (<0.5), unverified or revoked ### Trust Policy Integration ```bash # Install with minimum trust requirement nip install package --trust-level=0.8 # Repository addition with trust verification nip repo add https://example.com --trust=prompt ``` ### Security Event Logging All remote operations are logged to the security event log for audit trails: - Repository additions and trust decisions - Package installations with trust scores - Mirror synchronization events - Cache operations and cleanup activities ## Performance Optimizations ### Bloom Filter Synchronization The CLI uses bloom filter handshake for O(changes) synchronization efficiency: ```bash # Efficient sync using bloom filters nip repo sync # Only transfers changed objects # Mirror sync with bloom optimization nip mirror sync # Automatic bloom filter handshake ``` ### Binary Cache Support ```bash # Automatic binary selection with CPU compatibility nip install nginx # Detects CPU flags, libc, allocator # Binary cache statistics nip cache status # Shows hit rate and efficiency ``` ### Bandwidth Management ```bash # Rate limiting for network-constrained environments nip --max-bw=1MB/s repo sync # Time-window based bandwidth allocation nip mirror sync --max-bw=peak:10MB/s,avg:5MB/s ``` ## Integration with Existing Systems ### Task 11 Security Integration - **Trust Policy Manager**: Repository trust verification - **Keyring Manager**: Key storage and validation - **Event Logger**: Audit trail and compliance tracking ### Task 15.1d Sync Engine Integration - **Bloom Filter Handshake**: Efficient synchronization - **Delta Object Compression**: Bandwidth optimization - **Mirror Network**: Load balancing and failover ### Configuration System Integration - **Hierarchical Configuration**: `/etc/nexus/` β†’ `~/.config/nexus/` β†’ `.nexus/` - **Modular Configuration Files**: `nip-repositories.kdl`, `nip-trust.kdl` - **Policy-Based Configuration**: Trust policies and repository settings ## Troubleshooting ### Common Issues 1. **Repository Trust Verification Failed** ```bash # Re-add with explicit trust level nip repo add https://example.com --trust=prompt ``` 2. **Sync Performance Issues** ```bash # Use bandwidth limiting nip repo sync --max-bw=5MB/s # Check mirror health nip mirror list ``` 3. **Cache Issues** ```bash # Check cache status nip cache status # Clean old entries nip cache clean --dry-run ``` ### Debug Mode ```bash # Enable verbose logging for troubleshooting nip --verbose repo sync # JSON output for detailed analysis nip --verbose --output=json mirror list ``` ## Best Practices 1. **Repository Management** - Always verify repository fingerprints manually - Use appropriate trust levels for different environments - Regularly sync repositories to stay current 2. **Installation Strategy** - Prefer binary packages for faster installation - Use repository-specific installs for critical packages - Monitor trust scores and update policies accordingly 3. **Cache Management** - Regular cache cleanup to manage disk space - Monitor cache hit rates for performance optimization - Use dry-run mode before major cleanup operations 4. **Mirror Configuration** - Configure multiple mirrors for redundancy - Set appropriate priorities based on network topology - Monitor mirror health and adjust as needed This guide covers the essential features of the enhanced remote-aware CLI. For additional information, use the built-in help system with `nip --help` or `nip --help=examples`.