9.1 KiB

Raw Blame History

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Overview of all commands
nip --help

# Category-based command listing
nip repo --help

# Detailed help with examples
nip repo --help=examples

Command-Specific Help

# Repository management help
nip repo add --help

# Installation options
nip install --help

# Cache management options
nip cache --help

Global Options

Output Formats

# 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

# 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

# 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

# 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:

# 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

# 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

# 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

Repository Trust Verification Failed

# Re-add with explicit trust level
nip repo add https://example.com --trust=prompt

Sync Performance Issues

# Use bandwidth limiting
nip repo sync --max-bw=5MB/s

# Check mirror health
nip mirror list

Cache Issues

# Check cache status
nip cache status

# Clean old entries
nip cache clean --dry-run

Debug Mode

# Enable verbose logging for troubleshooting
nip --verbose repo sync

# JSON output for detailed analysis
nip --verbose --output=json mirror list

Best Practices

Repository Management
- Always verify repository fingerprints manually
- Use appropriate trust levels for different environments
- Regularly sync repositories to stay current
Installation Strategy
- Prefer binary packages for faster installation
- Use repository-specific installs for critical packages
- Monitor trust scores and update policies accordingly
Cache Management
- Regular cache cleanup to manage disk space
- Monitor cache hit rates for performance optimization
- Use dry-run mode before major cleanup operations
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.

9.1 KiB Raw Blame History

NimPak Remote-Aware CLI Guide

Overview

Repository Management

Adding Repositories

Listing Repositories

Synchronizing Repositories

Enhanced Package Installation

Binary-First Installation

Source Build Fallback

Cache Management

Cache Status

Cache Cleanup

Mirror Management

Adding Mirrors

Listing Mirrors

Mirror Synchronization

Progressive Help System

General Help

Command-Specific Help

Global Options

Output Formats

Bandwidth Management

Verbose Mode

Trust and Security Features

Trust Badges

Trust Policy Integration

Security Event Logging

Performance Optimizations

Bloom Filter Synchronization

Binary Cache Support

Bandwidth Management

Integration with Existing Systems

Task 11 Security Integration

Task 15.1d Sync Engine Integration

Configuration System Integration

Troubleshooting

Common Issues

Debug Mode

Best Practices

9.1 KiB

Raw Blame History