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