MAIN ein-cli Project Documentation

Project Overview

ein-cli is a dual-interface Infernet CLI/TUI application that provides both command-line automation and interactive terminal interfaces for decentralized AI inference through the Infernet Network. The project enables users to discover AI nodes, make micropayments via X402, and consume AI services in a peer-to-peer infrastructure.

Core Concept: Infernet Network

Infrastructure + Inference + Network - A decentralized network where anyone can provide inference capacity and consume AI services with X402 micropayments.

Technology Stack

Core Dependencies

Go 1.21+ - Primary programming language
Cobra - CLI framework for commands and flags
Bubbletea - TUI framework (Model-View-Update pattern)
Bubbles - Pre-built TUI components (lists, inputs, spinners)
Lipgloss - Styling and layout for TUI
Viper - Configuration management

Infernet Integration

Wallet API v2 - Blockchain wallet integration
X402 Payment Protocol - Micropayments for AI inference
Base Network - Smart contract interactions for node registry
USDC - Payment token for inference services

Project Structure

ein-cli/
├── main.go                    # Entry point - determines CLI vs TUI mode
├── go.mod                     # Go module with Charm stack dependencies
├── go.sum                     # Dependency checksums
├── ein-cli                    # Compiled binary (executable)
│
├── cmd/                       # CLI commands (Cobra)
│   ├── root.go               # Root command with global flags
│   ├── api.go                # API-related CLI commands
│   └── version.go            # Version information command
│
├── internal/                  # Private application packages
│   ├── infernet/             # Infernet protocol client
│   │   ├── client.go         # Main Infernet client
│   │   └── node.go           # Node discovery and management
│   ├── wallet/               # Wallet integration
│   │   └── client.go         # Wallet API v2 client
│   ├── messages/             # Bubbletea custom messages
│   │   └── navigation.go     # Navigation message types
│   └── models/               # Data structures and configuration
│       ├── config.go         # Application configuration
│       └── api.go            # API request/response models
│
├── tui/                      # Terminal User Interface
│   ├── app.go                # Main TUI application coordinator
│   ├── router.go             # Screen navigation system
│   ├── keys.go               # Global key bindings
│   ├── styles/               # Styling and themes
│   │   ├── theme.go          # Purple theme color palette
│   │   └── components.go     # Component-specific styles
│   └── screens/              # Individual TUI screens
│       ├── main_menu.go      # Main navigation menu
│       ├── api_form.go       # Legacy API request form
│       ├── settings.go       # Configuration management
│       ├── help.go           # Help and documentation
│       ├── node_browser.go   # Infernet node discovery
│       └── wallet_manager.go # Wallet connection interface
│
├── pkg/                      # Public utility packages
│   └── utils/                # Helper functions
│
└── Documentation Files:
    ├── plan.md               # Original development roadmap (Phase 1)
    ├── step2inplan.md        # Infernet-specific implementation plan
    ├── PROJECT_STRUCTURE.md  # Detailed structure documentation
    └── CRUSH.md              # Development guidelines and commands

Architecture Design

Entry Point Logic

The application uses a dual-mode approach:

No arguments: Launches interactive TUI mode
With arguments: Executes CLI commands directly

func main() {
    if len(os.Args) > 1 {
        cmd.Execute() // CLI mode
    } else {
        tui.NewApp().Run() // TUI mode
    }
}

Configuration System

Comprehensive configuration supporting both legacy API features and Infernet-specific settings:

type Config struct {
    Server   ServerConfig   // Legacy API configuration
    Theme    ThemeConfig    // UI theme preferences
    History  HistoryConfig  // Request history settings
    Auth     AuthConfig     // Authentication settings
    Infernet InfernetConfig // Infernet-specific configuration
}

Infernet Integration Architecture

Node Discovery: Smart contract integration for finding inference providers
Payment System: X402 micropayments with USDC on Base network
Wallet Management: Wallet API v2 for blockchain interactions
Model Support: llama-3.3, mistral-7b, stable-diffusion integration

Development Timeline (from .md file timestamps)

Based on file timestamps, the project evolved as follows:

plan.md (Dec 10, 2024) - Original generic API client concept
PROJECT_STRUCTURE.md (Dec 10, 2024) - Detailed architecture documentation
CRUSH.md (Dec 10, 2024) - Development commands and guidelines
step2inplan.md (Dec 11, 2024) - Pivot to Infernet-specific implementation

Key Features

Current Implementation

✅ Dual CLI/TUI interface architecture
✅ Bubbletea-based interactive TUI with purple theme
✅ Cobra-based CLI commands with global flags
✅ Configuration management with Viper
✅ Screen navigation system with breadcrumbs
✅ Infernet client integration points
✅ Wallet client architecture

Infernet-Specific Features (In Development)

🔄 Node discovery from Base smart contract registry
🔄 X402 payment integration for micropayments
🔄 Multi-model AI inference (llama-3.3, mistral, stable-diffusion)
🔄 Real-time pricing comparison across nodes
🔄 Transaction history and cost analytics
🔄 Pre-written request templates
🔄 Reputation-based node selection

TUI Screens

Main Menu: Navigation hub for all features
Node Browser: Discover and compare inference nodes
Wallet Manager: Connect wallet and manage payments
API Form: Legacy API request interface
Settings: Configuration management
Help: Documentation and keyboard shortcuts

How to Recreate Project from Zero

1. Initialize Go Module

mkdir ein-cli && cd ein-cli
go mod init ein-cli

2. Install Dependencies

go get github.com/charmbracelet/bubbles@v0.18.0
go get github.com/charmbracelet/bubbletea@v0.25.0
go get github.com/charmbracelet/lipgloss@v0.9.1
go get github.com/spf13/cobra@v1.8.0
go get github.com/spf13/viper@v1.18.2

3. Create Project Structure

mkdir -p cmd internal/{infernet,wallet,messages,models} tui/{screens,styles} pkg/utils

4. Implement Core Files

Follow this implementation order:

main.go - Entry point with dual-mode logic
internal/models/config.go - Configuration structures
internal/models/api.go - API data models
cmd/root.go - Cobra CLI setup with Viper
tui/keys.go - Key bindings
tui/styles/theme.go - Purple theme palette
tui/router.go - Screen navigation system
tui/screens/main_menu.go - Main menu implementation
tui/app.go - Main TUI application coordinator

5. Build and Test

go build -o ein-cli main.go
./ein-cli              # Launch TUI
./ein-cli --help        # Test CLI
./ein-cli version       # Test subcommands

6. Add Infernet Integration

Implement wallet client in internal/wallet/
Create Infernet client in internal/infernet/
Add node browser screen in tui/screens/node_browser.go
Implement payment system integration

Development Commands

Building and Running

go build -o ein-cli main.go     # Build binary
go run main.go                  # Run without building
./ein-cli                       # Launch TUI mode
./ein-cli --help                # CLI help

Development Tools

go test ./...                   # Run tests
go fmt ./...                    # Format code
go vet ./...                    # Static analysis
go mod tidy                     # Clean dependencies

Configuration

Default Configuration Location

File: ~/.ein-cli.yaml
Environment Variables: Prefixed with EIN_
CLI Flags: Override config file settings

Key Configuration Sections

Server: Legacy API settings
Theme: Purple theme customization
History: Request history preferences
Infernet.Wallet: Blockchain network settings
Infernet.Payment: Micropayment limits and preferences
Infernet.Nodes: Node selection criteria
Infernet.Models: AI model preferences

Success Metrics

Technical Goals

Sub-5-second AI inference with micropayment
Multi-node price comparison interface
Complete transaction transparency
Intuitive keyboard-driven navigation

User Experience Goals

Seamless wallet connection via Wallet API v2
Real-time payment status tracking
Clear error messages and feedback
Context-sensitive help system

Future Enhancements

Planned Features

GraphQL support for node metadata
WebSocket connections for real-time updates
Plugin system for custom authentication
Team collaboration features
Mock server functionality for development

Performance Optimizations

Request caching for node metadata
Concurrent inference requests
Response streaming for large payloads
Background node availability checking

AI Agent Instructions for Extension

To Add New TUI Screen:

Create screen file in tui/screens/new_screen.go
Implement Bubbletea Model interface (Init, Update, View)
Add screen constant to tui/router.go
Register in tui/app.go initializeScreens()
Add navigation from relevant screens

To Add CLI Command:

Create command file in cmd/new_command.go
Use Cobra command structure with persistent flags
Add to root command in cmd/root.go init()
Implement shared business logic in internal/

To Extend Configuration:

Add fields to relevant config struct in internal/models/config.go
Update NewDefaultConfig() with sensible defaults
Add validation if needed
Update settings screen to show new options

This project provides a solid foundation for building decentralized AI interaction tools with both automation (CLI) and exploration (TUI) capabilities, specifically designed for the Infernet Network ecosystem.

Ver tambien: CLI PRS, project-architecture, Implementation Plan

Home

Explorer

main-ein-cli-project-documentation