Command-Line Interface

Khedra provides a simple, focused command-line interface (CLI) for managing the system. The CLI is designed around a core workflow of initialization, daemon management, and service control via REST API.

CLI Architecture

The CLI is built using the urfave/cli library, providing a lightweight and user-friendly interface focused on essential operations.

Design Principles

Simplicity: Minimal command set focused on core functionality
Clarity: Each command has a clear, single purpose
Automation-Friendly: Services are controlled via REST API for scriptability
Self-Documenting: Built-in help for all commands

Implementation Structure

func initCli(k *KhedraApp) *cli.App {
    app := &cli.App{
        Name:     "khedra",
        Usage:    "A tool to index, monitor, serve, and share blockchain data",
        Version:  version.Version,
        Commands: []*cli.Command{
            // Core commands only - no complex service management via CLI
        },
    }
    return app
}

Command Structure

Khedra's CLI is organized into logical command groups.

Root Command

The base khedra command serves as the entry point and provides global options:

khedra [global options] command [command options] [arguments...]

Global options include:

--config: Specify an alternate configuration file path
--format: Control output format (text, json, csv)
--verbose: Enable verbose output
--quiet: Suppress non-error output
--chain: Specify the target blockchain (defaults to "mainnet")

Service Management Commands

Commands for controlling Khedra's services:

Service Lifecycle Commands

khedra daemon: Start Khedra in daemon mode with all configured services

# Start with default configuration
khedra daemon

# Start with specific log level
TB_KHEDRA_LOGGING_LEVEL=debug khedra daemon

# Start with custom configuration file
khedra daemon --config=/path/to/config.yaml

khedra start [service...]: Start specific services (if supported)

# Start all services
khedra start

# Start specific services
khedra start scraper api

# Start in foreground mode
khedra start --foreground

khedra stop [service...]: Stop specific services (if supported)

# Stop all services
khedra stop

# Stop specific services  
khedra stop scraper monitor

# Force stop (ungraceful shutdown)
khedra stop --force

khedra restart [service...]: Restart specific services (if supported)

# Restart all services
khedra restart

# Restart specific services
khedra restart api ipfs

# Restart with configuration reload
khedra restart --reload-config

Service Status Commands

khedra status: Show status of all services

# Basic status
khedra status

# Detailed status with metrics
khedra status --verbose

# Status for specific services
khedra status scraper monitor

# JSON output for scripting
khedra status --format=json

Service Control via API

All service management operations are also available via REST API:

# Check service status
curl http://localhost:8080/api/v1/services

# Start a service
curl -X POST http://localhost:8080/api/v1/services/scraper/start

# Stop a service  
curl -X POST http://localhost:8080/api/v1/services/monitor/stop

# Get detailed service metrics
curl http://localhost:8080/api/v1/services/api?verbose=true

Index Management Commands

Commands for managing the Unchained Index:

Index Status and Information

khedra index status [chain]: Show index status for specified chain

# Status for default chain
khedra index status

# Status for specific chain
khedra index status --chain=mainnet

# Show gaps in the index
khedra index status --show-gaps

# Show detailed analytics
khedra index status --analytics

# Export status to file
khedra index status --output=/path/to/status.json

Index Maintenance Commands

khedra index rebuild [options]: Rebuild portions of the index

# Rebuild specific block range
khedra index rebuild --start=18000000 --end=18001000

# Rebuild from specific block to latest
khedra index rebuild --from=18000000

# Rebuild with specific batch size
khedra index rebuild --batch-size=1000 --start=18000000 --end=18001000

# Rebuild for specific chain
khedra index rebuild --chain=sepolia --start=4000000 --end=4001000

khedra index verify [options]: Verify index integrity

# Verify entire index
khedra index verify

# Verify specific block range
khedra index verify --start=18000000 --end=18001000

# Verify and attempt to repair issues
khedra index verify --repair

# Verify for specific chain
khedra index verify --chain=mainnet

khedra index optimize: Optimize index storage and performance

# Optimize entire index
khedra index optimize

# Optimize specific chunks
khedra index optimize --chunks=1800,1801,1802

# Optimize and compress
khedra index optimize --compress

Monitor Commands

Commands for managing address monitors:

Monitor Management

khedra monitor add ADDRESS [ADDRESS...]: Add addresses to monitor

# Add single address
khedra monitor add 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

# Add multiple addresses
khedra monitor add 0x742d35Cc... 0x1234567... 0xabcdef...

# Add with custom name
khedra monitor add 0x742d35Cc... --name="Vitalik Buterin"

# Add with notification settings
khedra monitor add 0x742d35Cc... --notifications=webhook,email

# Add from file
khedra monitor add --file=/path/to/addresses.txt

khedra monitor remove ADDRESS [ADDRESS...]: Remove monitored addresses

# Remove specific addresses
khedra monitor remove 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

# Remove without confirmation prompt
khedra monitor remove 0x742d35Cc... --force

# Remove all monitors (with confirmation)
khedra monitor remove --all

# Remove monitors matching pattern
khedra monitor remove --pattern="test_*"

Monitor Information

khedra monitor list: List all monitored addresses

# List all monitors
khedra monitor list

# List with detailed information
khedra monitor list --details

# List only active monitors
khedra monitor list --active-only

# Export to CSV
khedra monitor list --format=csv --output=monitors.csv

# Filter by pattern
khedra monitor list --pattern="*buterin*"

khedra monitor activity ADDRESS: Show activity for monitored address

# Show recent activity
khedra monitor activity 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

# Show activity in block range
khedra monitor activity 0x742d35Cc... --from=18000000 --to=18001000

# Limit number of results
khedra monitor activity 0x742d35Cc... --limit=100

# Show activity in specific time range
khedra monitor activity 0x742d35Cc... --since="2023-01-01" --until="2023-12-31"

# Export activity to file
khedra monitor activity 0x742d35Cc... --output=/path/to/activity.json

Monitor Configuration

khedra monitor config ADDRESS: Configure monitor settings

# Update monitor name
khedra monitor config 0x742d35Cc... --name="Updated Name"

# Configure notifications
khedra monitor config 0x742d35Cc... --notifications=webhook --webhook-url=https://...

# Set monitoring thresholds
khedra monitor config 0x742d35Cc... --min-value=1.0 --currency=ETH

# Disable/enable monitor
khedra monitor config 0x742d35Cc... --enabled=false

Chain Management Commands

Commands for managing blockchain connections:

Chain Configuration

khedra chains list: List configured blockchain networks

# List all configured chains
khedra chains list

# List only enabled chains
khedra chains list --enabled-only

# Show detailed chain information
khedra chains list --details

# Export chain configuration
khedra chains list --format=json --output=chains.json

khedra chains add NAME URL: Add new blockchain network

# Add new chain with single RPC
khedra chains add polygon https://polygon-rpc.com

# Add chain and enable immediately
khedra chains add arbitrum https://arb1.arbitrum.io/rpc --enable

# Add chain with multiple RPC endpoints
khedra chains add optimism https://mainnet.optimism.io,https://opt-mainnet.g.alchemy.com/v2/KEY

# Add chain with custom configuration
khedra chains add base https://mainnet.base.org --chain-id=8453 --symbol=ETH

khedra chains remove NAME: Remove blockchain network

# Remove specific chain
khedra chains remove polygon

# Remove without confirmation
khedra chains remove arbitrum --force

# Remove and clean up data
khedra chains remove optimism --cleanup-data

Chain Testing and Validation

khedra chains test NAME: Test connection to blockchain network

# Test specific chain connectivity
khedra chains test mainnet

# Test with verbose output
khedra chains test polygon --verbose

# Test all RPC endpoints for a chain
khedra chains test mainnet --test-all-rpcs

# Test and benchmark performance
khedra chains test mainnet --benchmark

khedra chains validate: Validate all chain configurations

# Validate all chains
khedra chains validate

# Validate specific chain
khedra chains validate --chain=mainnet

# Validate and show detailed results
khedra chains validate --verbose

# Validate and attempt to fix issues
khedra chains validate --auto-fix

Configuration Commands

Commands for managing Khedra's configuration:

Configuration Display and Editing

khedra config show: Display current configuration

# Show complete configuration
khedra config show

# Show specific section
khedra config show --section=services
khedra config show --section=chains
khedra config show --section=logging

# Hide sensitive information
khedra config show --redact

# Export configuration
khedra config show --format=yaml --output=config.yaml
khedra config show --format=json --output=config.json

khedra config edit: Open configuration in editor

# Edit with default editor
khedra config edit

# Edit with specific editor
khedra config edit --editor=vim
khedra config edit --editor=code

# Edit specific section
khedra config edit --section=services

# Edit and validate before saving
khedra config edit --validate

Configuration Management

khedra config wizard: Run interactive configuration wizard

# Run full configuration wizard
khedra config wizard

# Run simplified wizard
khedra config wizard --simple

# Run wizard for specific section
khedra config wizard --section=services
khedra config wizard --section=chains

# Run wizard and save to custom location
khedra config wizard --output=/path/to/config.yaml

khedra config validate: Validate configuration

# Validate current configuration
khedra config validate

# Validate specific file
khedra config validate --file=/path/to/config.yaml

# Validate and show detailed errors
khedra config validate --verbose

# Validate against specific schema version
khedra config validate --schema-version=v1.0

khedra config reset: Reset configuration to defaults

# Reset entire configuration (with confirmation)
khedra config reset

# Reset specific section
khedra config reset --section=services

# Reset without confirmation prompt
khedra config reset --force

# Reset and backup current config
khedra config reset --backup=/path/to/backup.yaml

Utility Commands

Commands for various utility operations:

Version and Information

khedra version: Display version information

# Show version
khedra version

# Show detailed build information
khedra version --build-info

# Show version in JSON format
khedra version --json

# Check for updates
khedra version --check-updates

Initialization and Setup

khedra init: Initialize Khedra configuration and data directories

# Initialize with wizard
khedra init

# Initialize with minimal setup
khedra init --minimal

# Initialize in specific directory
khedra init --data-dir=/custom/path

# Initialize with custom configuration
khedra init --config=/path/to/config.yaml

# Reinitialize existing setup
khedra init --force

Health and Diagnostics

khedra health: Check overall system health

# Basic health check
khedra health

# Detailed health report
khedra health --detailed

# Health check with remediation suggestions
khedra health --suggest-fixes

# Export health report
khedra health --output=/path/to/health-report.json

khedra doctor: Run comprehensive system diagnostics

# Run all diagnostic checks
khedra doctor

# Run specific diagnostic categories
khedra doctor --checks=network,storage,performance

# Run diagnostics and attempt auto-fixes
khedra doctor --auto-fix

# Run diagnostics for specific chain
khedra doctor --chain=mainnet

Log and Debug Commands

khedra logs: Display and manage log files

# Show recent logs
khedra logs

# Follow logs in real-time
khedra logs --follow

# Show logs for specific service
khedra logs --service=scraper
khedra logs --service=monitor

# Filter logs by level
khedra logs --level=error
khedra logs --level=debug

# Show logs in specific time range
khedra logs --since="2023-01-01" --until="2023-12-31"

# Export logs to file
khedra logs --output=/path/to/logs.txt

Data Management

khedra cleanup: Clean up temporary files and optimize storage

# Clean temporary files
khedra cleanup

# Clean and optimize index
khedra cleanup --optimize-index

# Clean old log files
khedra cleanup --logs --older-than=30d

# Dry run to see what would be cleaned
khedra cleanup --dry-run

# Clean specific data types
khedra cleanup --cache --temp --logs

The Khedra Book