https://docs.rs/ipfrs-cli

ipfrs-cli

Command-line interface for IPFRS.

Overview

ipfrs-cli provides a user-friendly CLI for interacting with IPFRS:

• Kubo-Compatible Commands: Drop-in replacement for ipfs CLI
• Enhanced Features: TensorLogic-specific operations
• Interactive Mode: REPL for exploration
• Daemon Management: Start/stop IPFRS node

Key Features

Kubo-Compatible Commands

Standard IPFS commands work out of the box:

ipfrs add <file>              # Add file to IPFRS
ipfrs cat <cid>               # Retrieve file by CID
ipfrs get <cid>               # Download file/directory
ipfrs ls <cid>                # List directory contents
ipfrs dag get <cid>           # Get DAG node
ipfrs block get <cid>         # Get raw block
ipfrs swarm peers             # List connected peers
ipfrs dht findprovs <cid>     # Find providers

TensorLogic Extensions

Advanced operations for AI workloads:

ipfrs tensor add <file>       # Add tensor with metadata
ipfrs tensor get <cid>        # Retrieve tensor (zero-copy)
ipfrs logic put <term>        # Store logic term
ipfrs logic query <goal>      # Run distributed inference
ipfrs gradient push <cid>     # Publish gradient update
ipfrs model checkpoint        # Create versioned snapshot

Daemon Management

Control IPFRS node lifecycle:

ipfrs daemon                  # Run node in foreground
ipfrs daemon start            # Start background daemon
ipfrs daemon stop             # Stop background daemon
ipfrs daemon status           # Check daemon status
ipfrs init                    # Initialize repository

Interactive Mode

REPL for experimentation:

ipfrs shell
ipfrs> add my_file.txt
added QmHash... my_file.txt
ipfrs> cat QmHash...
[file contents]
ipfrs> exit

Terminal UI Dashboard

Interactive dashboard for real-time monitoring:

ipfrs tui

Features:

• Overview Tab: Peer count, storage usage, bandwidth gauges, node info
• Network Tab: Network activity sparkline, connected peers list
• Storage Tab: Block statistics, recent blocks, cache metrics
• Help Tab: Keyboard shortcuts and navigation guide

Navigation:

• Tab or ←/→ - Switch between tabs
• 1-4 - Jump directly to a tab
• q or Ctrl+C - Exit the dashboard

Architecture

The CLI is organized into modular components for maintainability and reusability:

ipfrs-cli/
├── src/
│   ├── commands/          # Modular command implementations (15+ modules)
│   │   ├── mod.rs        # Module organization and exports
│   │   ├── common.rs     # Shared validation utilities
│   │   ├── file.rs       # File operations (init, add, get, cat, ls)
│   │   ├── block.rs      # Block operations (get, put, stat, rm)
│   │   ├── dag.rs        # DAG operations (get, put, resolve, export/import)
│   │   ├── daemon.rs     # Daemon management (start, stop, status, restart)
│   │   ├── pin.rs        # Pin management (add, rm, ls, verify)
│   │   ├── repo.rs       # Repository management (gc, stat, fsck)
│   │   ├── network.rs    # Network operations (swarm, dht, bootstrap)
│   │   ├── stats.rs      # Statistics (repo, bw, bitswap)
│   │   ├── tensor.rs     # Tensor operations (add, get, info, export)
│   │   ├── logic.rs      # Logic programming (infer, prove, kb-*)
│   │   ├── semantic.rs   # Semantic search (search, index, similar)
│   │   ├── model.rs      # Model management (add, checkpoint, diff)
│   │   ├── gradient.rs   # Gradient operations (push, pull, aggregate)
│   │   └── gateway.rs    # HTTP gateway server
│   ├── main.rs           # CLI entry point and dispatch (2,079 lines)
│   ├── lib.rs            # Library interface for reusability
│   ├── config.rs         # Configuration management with caching
│   ├── output.rs         # Output formatting (colors, tables, JSON)
│   ├── progress.rs       # Progress indicators (spinners, bars)
│   ├── shell.rs          # Interactive REPL shell
│   ├── tui.rs            # Terminal UI dashboard (ratatui)
│   ├── plugin.rs         # Plugin system for extensibility
│   └── utils.rs          # Utility functions (version, man pages)
└── tests/
    └── integration_tests.rs  # End-to-end CLI testing
        ↓
    ipfrs (core library)

Recent Refactoring (2026-01-09):

• Reduced main.rs from 4,825 to 2,079 lines (57% code reduction)
• Extracted all command implementations to modular commands/ files
• Total codebase: 8,652 lines across 15+ command modules
• Single source of truth for all command logic

Design Principles

• User-Friendly: Clear error messages, helpful hints
• Fast: Optimized for low startup time with config caching
• Compatible: Familiar to IPFS users
• Powerful: Expose advanced IPFRS features

Performance Optimizations

The CLI is optimized for fast startup and low latency:

• Config Caching: Configuration files are loaded once and cached globally using OnceLock to avoid repeated disk I/O
• Lazy Initialization: Heavy modules are only loaded when needed
• Minimal Dependencies: Core functionality uses lightweight dependencies
• Benchmarking: Comprehensive benchmark suite to track performance metrics

Run benchmarks with:

cargo bench -p ipfrs-cli

Key metrics:

• CLI startup time: < 100ms (measured via benchmarks)
• Config load (cached): < 1μs
• Config load (uncached): < 500μs
• Command parsing: < 10ms

Man Page Generation

Generate comprehensive man pages for all IPFRS commands:

# Generate man pages to target/man directory
cargo run --bin ipfrs-genman

# Generate to custom directory
cargo run --bin ipfrs-genman -- /path/to/output

# Install system-wide (Linux/macOS)
cargo run --bin ipfrs-genman
sudo cp target/man/*.1 /usr/share/man/man1/
sudo mandb

# View man pages
man ipfrs
man ipfrs-add
man ipfrs-daemon

The man page generator creates:

• Main man page: ipfrs.1
• Subcommand pages: ipfrs-<command>.1 for each command

Update Checking

Check for available updates using the hidden update command:

# Check for updates
ipfrs update --check

# The command will notify you if a newer version is available

Troubleshooting

The CLI provides helpful troubleshooting hints for common errors. Use the troubleshooting_hint() function in your code or check error messages for diagnostic steps covering:

• Daemon not running
• Repository not initialized
• Connection failures
• Content not found
• Permission issues
• Configuration errors
• Network timeouts

Shell Script Integration

The CLI is designed to be script-friendly with proper exit codes and quiet mode:

Exit Codes

Standard exit codes for reliable error handling in scripts:

• 0 - Success
• 1 - General error
• 2 - Invalid arguments or command-line usage
• 3 - File or content not found
• 4 - Permission denied or authentication failed
• 5 - Network or connection error
• 6 - I/O error (file system operations)
• 7 - Timeout error
• 8 - Configuration error

Example script:

#!/bin/bash
if ipfrs add myfile.txt; then
    echo "File added successfully"
else
    case $? in
        2) echo "Usage error - check your arguments" ;;
        3) echo "File not found" ;;
        6) echo "I/O error - check permissions" ;;
        *) echo "Error occurred" ;;
    esac
fi

Quiet Mode

Use --quiet or -q to suppress non-essential output for pipelines:

# Get just the CID without progress messages
CID=$(ipfrs add --quiet myfile.txt)

# Pipe content directly
ipfrs cat --quiet $CID | grep "pattern"

# Combine with JSON output for parsing
ipfrs ls --quiet --format json $CID | jq '.[] | .name'

Other Script-Friendly Features

• --no-color - Disable colored output (useful for logs)
• --format json - Machine-readable JSON output
• Consistent output to stdout (data) and stderr (diagnostics)

Migration from IPFS (Kubo)

IPFRS is designed to be compatible with IPFS workflows. If you're familiar with IPFS/Kubo, here's what you need to know:

Command Compatibility

Most IPFS commands work identically in IPFRS:

IPFS Command	IPFRS Equivalent	Notes
ipfs init	ipfrs init	✅ Same behavior
ipfs add <file>	ipfrs add <file>	✅ Compatible CIDs
ipfs cat <cid>	ipfrs cat <cid>	✅ Same output
ipfs get <cid>	ipfrs get <cid>	✅ Same functionality
ipfs daemon	ipfrs daemon	✅ Same API endpoints
ipfs swarm peers	ipfrs swarm peers	✅ Compatible
ipfs id	ipfrs id	✅ Same format
ipfs pin add	ipfrs pin add	✅ Compatible
ipfs dag get	ipfrs dag get	✅ IPLD compatible
ipfs block get	ipfrs block get	✅ Compatible

What's Different

Enhanced Features (IPFRS-specific):

# Tensor operations (new in IPFRS)
ipfrs tensor add model.safetensors
ipfrs tensor info <cid>

# Logic programming (new in IPFRS)
ipfrs logic infer --predicate "ancestor" --terms "Alice,Bob"
ipfrs logic prove --goal "path(A,B)"

# Semantic search (new in IPFRS)
ipfrs semantic search "query" -k 10
ipfrs semantic similar <cid>

# Model versioning (new in IPFRS)
ipfrs model add ./model_dir
ipfrs model checkpoint <cid> -m "v1.0"
ipfrs model diff <cid1> <cid2>

# Federated learning (new in IPFRS)
ipfrs gradient push ./gradients
ipfrs gradient aggregate --method mean

Configuration Differences:

• IPFRS config: ~/.ipfrs/config.toml (TOML format)
• IPFS config: ~/.ipfs/config (JSON format)
• Environment variable: IPFRS_PATH vs IPFS_PATH

API Compatibility:

• IPFRS exposes the same HTTP API on port 5001 (configurable)
• IPFRS gateway runs on port 8080 (configurable)
• Most IPFS HTTP API endpoints work without modification

Migration Steps

1. Install IPFRS:

cargo install --path crates/ipfrs-cli

2. Initialize Repository:

# Create new IPFRS repository
ipfrs init

# Or import existing IPFS data
ipfrs repo import ~/.ipfs

3. Test Compatibility:

# Add content with IPFRS
ipfrs add myfile.txt

# Verify same CID as IPFS would generate
# (IPFRS uses the same CID format)

4. Migrate Pins (if needed):

# Export pins from IPFS
ipfs pin ls > pins.txt

# Import to IPFRS
cat pins.txt | while read cid type; do
  ipfrs pin add $cid
done

5. Update Scripts:

# Simply replace 'ipfs' with 'ipfrs' in most cases
sed -i 's/ipfs /ipfrs /g' myscript.sh

Interoperability

IPFRS can communicate with IPFS nodes on the network:

# Connect to IPFS node
ipfrs swarm connect /ip4/x.x.x.x/tcp/4001/p2p/Qm...

# Retrieve content from IPFS network
ipfrs get <cid-from-ipfs>

# Provide content to IPFS network
ipfrs dht provide <cid>

Key Differences Summary

Similarities:

• ✅ Same CID format (content addressing)
• ✅ Same DAG structure (IPLD)
• ✅ Same network protocol (libp2p)
• ✅ Compatible HTTP API
• ✅ Same pinning mechanism

New in IPFRS:

• 🆕 Native tensor support (Safetensors, NumPy, PyTorch)
• 🆕 Built-in logic programming and inference
• 🆕 Semantic search with vector embeddings
• 🆕 Model versioning and diffing
• 🆕 Federated learning support
• 🆕 Enhanced performance for ML workloads

Troubleshooting Migration

Issue: "Repository not found"

# Solution: Initialize IPFRS repo
ipfrs init

Issue: "Cannot connect to daemon"

# Solution: Start IPFRS daemon
ipfrs daemon start
# Or run in foreground
ipfrs daemon

Issue: "Different CID for same content"

# Ensure same chunking parameters
ipfrs add --chunker rabin myfile.txt

Issue: "IPFS peers not visible"

# IPFRS is compatible - check bootstrap peers
ipfrs bootstrap list
ipfrs bootstrap add /dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN

For more help, see the troubleshooting guide or visit the IPFRS documentation.

Installation

# Build from source
cargo install --path crates/ipfrs-cli

# Or use pre-built binary
curl -sSL https://ipfrs.io/install.sh | sh

Usage Examples

Basic File Operations

# Add a file
$ ipfrs add document.pdf
added QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx document.pdf

# Retrieve the file
$ ipfrs cat QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx > output.pdf

# Add directory recursively
$ ipfrs add -r ./my_directory/

Tensor Operations

# Add model weights
$ ipfrs tensor add model.safetensors
added QmModel... model.safetensors (1.2 GB, shape: [1024, 768])

# Query semantic similarity
$ ipfrs semantic search "neural networks" -k 10
QmHash1... (similarity: 0.95)
QmHash2... (similarity: 0.89)
...

Network Operations

# Show connected peers
$ ipfrs swarm peers
/ip4/192.168.1.100/tcp/4001/p2p/QmPeer1...
/ip4/10.0.0.50/udp/4001/quic-v1/p2p/QmPeer2...

# Find content providers
$ ipfrs dht findprovs QmHash...
QmPeer3...
QmPeer4...

Shell Completions

Generate shell completion scripts for faster command-line interaction:

# Bash
ipfrs completions bash > /etc/bash_completion.d/ipfrs
# Or for user-only:
ipfrs completions bash > ~/.local/share/bash-completion/completions/ipfrs

# Zsh
ipfrs completions zsh > "${fpath[1]}/_ipfrs"

# Fish
ipfrs completions fish > ~/.config/fish/completions/ipfrs.fish

# PowerShell
ipfrs completions powershell > ipfrs.ps1

# Elvish
ipfrs completions elvish > ~/.config/elvish/lib/ipfrs.elv

After installing, restart your shell or source the completion file to enable tab completion for ipfrs commands and arguments.

Remote Daemon Management

IPFRS CLI supports connecting to remote daemons, allowing you to manage multiple IPFRS nodes from a single machine.

Configuration

Configure remote daemon in ~/.ipfrs/config.toml:

[api]
# Remote API URL (for connecting to remote daemon)
remote_url = "http://192.168.1.100:5001"
# API token (for authenticated connections)
api_token = "your-secret-token"
# Connection timeout in seconds
timeout = 60

Environment Variables

Override configuration using environment variables:

# Connect to remote daemon
export IPFRS_API_URL="http://remote-host:5001"
export IPFRS_API_TOKEN="your-token"

# Now all commands connect to the remote daemon
ipfrs swarm peers
ipfrs add myfile.txt
ipfrs id

Multiple Daemon Management

Manage multiple daemons using shell aliases:

# Add to ~/.bashrc or ~/.zshrc
alias ipfrs-local='IPFRS_API_URL=http://localhost:5001 ipfrs'
alias ipfrs-prod='IPFRS_API_URL=https://prod.example.com:5001 IPFRS_API_TOKEN=xxx ipfrs'
alias ipfrs-dev='IPFRS_API_URL=http://dev.example.com:5001 ipfrs'

# Usage
ipfrs-local id          # Check local daemon
ipfrs-prod swarm peers  # Check production daemon
ipfrs-dev add file.txt  # Add to development daemon

Secure Remote Connections

For production deployments, use HTTPS and authentication:

# Enable authentication on the daemon
ipfrs daemon start --auth-token "secure-random-token"

# Connect from client
export IPFRS_API_URL="https://daemon.example.com:5001"
export IPFRS_API_TOKEN="secure-random-token"
ipfrs id

Remote Command Examples

# Check remote daemon status
IPFRS_API_URL=http://remote:5001 ipfrs daemon status

# Add file to remote daemon
IPFRS_API_URL=http://remote:5001 ipfrs add largefile.bin

# Query remote daemon peers
IPFRS_API_URL=http://remote:5001 ipfrs swarm peers

# Pin content on remote daemon
IPFRS_API_URL=http://remote:5001 ipfrs pin add QmHash...

Configuration

Configuration file: ~/.ipfrs/config.toml

[general]
data_dir = ".ipfrs"
log_level = "info"

[storage]
blocks_path = "blocks"
cache_size = 104857600  # 100MB

[network]
listen_addrs = ["/ip4/0.0.0.0/tcp/4001"]
max_connections = 256

[api]
# Local daemon
listen_addr = "127.0.0.1:5001"
# Remote daemon (optional)
# remote_url = "http://remote-host:5001"
auth_enabled = false
# api_token = "your-token"
timeout = 60

[gateway]
listen_addr = "127.0.0.1:8080"

Environment Variables

Supported environment variables (override config):

• IPFRS_PATH - Data directory
• IPFRS_LOG_LEVEL - Log level (error, warn, info, debug, trace)
• IPFRS_API_URL - Remote API URL
• IPFRS_API_TOKEN - API authentication token

## Dependencies

- `clap` - Command-line argument parsing
- `tokio` - Async runtime
- `ipfrs` - Core library
- `colored` - Terminal colors

## References

- IPFRS v0.1.0 Whitepaper (CLI Design)
- IPFS CLI Documentation: https://docs.ipfs.tech/reference/kubo/cli/