nip/docs/remote_cli_guide.md

# 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 <command> --help=examples`.