Home

plan

6 min read

ein-cli Development Plan

Project Overview

ein-cli is a dual-interface tool that provides both CLI commands for automation/scripting and an interactive TUI for exploratory usage. The tool focuses on making REST API requests with a user-friendly interface.

Core Concept

  • CLI Mode: Direct command execution with flags (when arguments provided)
  • TUI Mode: Interactive menu-driven interface (default when no flags provided)
  • Shared Core: Both interfaces use the same business logic and API client

Technology Stack

Charm Stack Components

  • 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
  • Huh: Advanced forms and inputs

Additional Libraries

  • Resty or net/http: REST API client
  • Viper: Configuration management
  • Logrus/Zerolog: Logging

Project Structure

ein-cli/
├── go.mod
├── go.sum
├── main.go                    # Entry point - determines CLI vs TUI
├── README.md
├── .gitignore
│
├── cmd/                       # CLI commands (Cobra)
│   ├── root.go               # Root command setup
│   ├── config.go             # Config commands
│   ├── api.go                # API-related commands
│   └── version.go            # Version command
│
├── internal/
│   ├── config/
│   │   ├── config.go         # Configuration structure
│   │   └── loader.go         # Config loading/saving
│   │
│   ├── client/
│   │   ├── client.go         # HTTP client wrapper
│   │   ├── auth.go           # Authentication handling
│   │   ├── endpoints.go      # API endpoint definitions
│   │   └── requests.go       # Request/response handling
│   │
│   ├── core/
│   │   ├── service.go        # Business logic service
│   │   └── validator.go      # Input validation
│   │
│   └── models/
│       ├── api.go            # API request/response models
│       ├── config.go         # Configuration models
│       └── errors.go         # Error types
│
├── tui/
│   ├── app.go                # Main TUI application
│   ├── router.go             # Screen navigation router
│   ├── keys.go               # Global key bindings
│   │
│   ├── components/
│   │   ├── menu.go           # Menu component
│   │   ├── form.go           # Form component
│   │   ├── loader.go         # Loading spinner
│   │   ├── confirm.go        # Confirmation dialog
│   │   └── result.go         # Result display
│   │
│   ├── screens/
│   │   ├── main_menu.go      # Main menu screen
│   │   ├── settings.go       # Settings screen
│   │   ├── api_form.go       # API request form
│   │   ├── results.go        # Results viewer
│   │   └── help.go           # Help screen
│   │
│   └── styles/
│       ├── theme.go          # Color themes
│       ├── layout.go         # Layout styles
│       └── components.go     # Component styles
│
└── pkg/
    └── utils/
        ├── format.go         # Data formatting
        └── helpers.go        # Utility functions

Architecture Design

Entry Point Logic

package main
 
import (
    "os"
    "ein-cli/cmd"
    "ein-cli/tui"
)
 
func main() {
    // If arguments provided, use CLI mode
    if len(os.Args) > 1 {
        cmd.Execute()
        return
    }
    
    // Otherwise, launch TUI
    app := tui.NewApp()
    if err := app.Run(); err != nil {
        os.Exit(1)
    }
}

CLI Layer (Cobra Commands)

// cmd/root.go
var rootCmd = &cobra.Command{
    Use:   "ein",
    Short: "Ein CLI tool",
    Long:  "A CLI tool with TUI interface for API interactions",
}
 
var apiCmd = &cobra.Command{
    Use:   "api [endpoint]",
    Short: "Make API requests",
    Run: func(cmd *cobra.Command, args []string) {
        // Use shared service layer
        service := core.NewService(client.New())
        result, err := service.MakeRequest(endpoint, data)
        // Handle result
    },
}

TUI Layer (Bubbletea)

// tui/app.go
type App struct {
    program   *tea.Program
    router    *Router
    service   *core.Service
    config    *config.Config
}
 
func (a *App) Run() error {
    model := NewMainModel(a.service, a.config)
    a.program = tea.NewProgram(model, tea.WithAltScreen())
    _, err := a.program.Run()
    return err
}
// tui/router.go
type Screen int
 
const (
    MainMenu Screen = iota
    APIForm
    Settings
    Results
    Help
)
 
type Router struct {
    current    Screen
    previous   []Screen
    components map[Screen]tea.Model
}
 
func (r *Router) Navigate(screen Screen) tea.Cmd {
    r.previous = append(r.previous, r.current)
    r.current = screen
    return r.components[screen].Init()
}

TUI Screen Flow Design

┌─────────────────┐
│   Main Menu     │
├─────────────────┤
│ > API Requests  │ ──┐
│   Settings      │   │
│   Help          │   │
│   Exit          │   │
└─────────────────┘   │
                      │
                      ▼
               ┌─────────────────┐
               │  API Form       │
               ├─────────────────┤
               │ Endpoint: _____ │
               │ Method: [GET▼]  │
               │ Headers:        │
               │ ┌─────────────┐ │
               │ │ Key: Value  │ │
               │ └─────────────┘ │
               │ Body:           │
               │ ┌─────────────┐ │
               │ │ JSON data   │ │
               │ └─────────────┘ │
               │ [Submit] [Back] │
               └─────────────────┘
                      │
                      ▼
               ┌─────────────────┐
               │ Loading...      │
               │     ⠋          │
               └─────────────────┘
                      │
                      ▼
               ┌─────────────────┐
               │  Results        │
               ├─────────────────┤
               │ Status: 200 OK  │
               │ Time: 245ms     │
               │                 │
               │ Response:       │
               │ ┌─────────────┐ │
               │ │ {           │ │
               │ │   "data":.. │ │
               │ │ }           │ │
               │ └─────────────┘ │
               │ [Back] [Save]   │
               └─────────────────┘

Key Features to Implement

Core Features

  1. Dynamic Forms: Use Huh for complex form inputs
  2. Request History: Store and replay previous requests
  3. Configuration Management: Save server configs, auth tokens
  4. Response Formatting: JSON pretty-printing, syntax highlighting
  5. Error Handling: Graceful error display in TUI

User Experience Features

  1. Keyboard Navigation: Vim-like shortcuts
  2. Themes: Light/dark mode support
  3. Help System: Context-sensitive help screens
  4. Request Templates: Pre-configured request templates
  5. Export/Import: Save and load request collections

Advanced Features

  1. Authentication: Support for various auth methods (Bearer, Basic, API Key)
  2. Environment Variables: Support for variable substitution
  3. Response Validation: Schema validation for responses
  4. Request Chaining: Use response data in subsequent requests

Development Phases

Phase 1: Foundation (Week 1-2)

Goal: Basic structure and navigation

  • Set up project structure
  • Initialize go.mod with dependencies
  • Implement basic CLI commands with Cobra
  • Create simple TUI navigation with Bubbletea
  • Basic screen routing system

Phase 2: Core Functionality (Week 3-4)

Goal: HTTP client and basic API requests

  • HTTP client implementation with authentication
  • Basic API request forms using Huh
  • Response display with JSON formatting
  • Error handling for network requests
  • Configuration file support

Phase 3: Enhanced UX (Week 5-6)

Goal: Improved user experience

  • Request history and persistence
  • Advanced form validation
  • Response syntax highlighting
  • Loading states and spinners
  • Keyboard shortcuts and help system

Phase 4: Advanced Features (Week 7-8)

Goal: Power user features

  • Request templates and collections
  • Environment variable support
  • Export/import functionality
  • Response chaining capabilities
  • Advanced authentication methods

Phase 5: Polish (Week 9-10)

Goal: Production readiness

  • Styling and themes (light/dark mode)
  • Comprehensive help system
  • Error handling refinement
  • Performance optimization
  • Documentation and examples

Technical Considerations

State Management

  • Use Bubbletea’s Model-View-Update pattern
  • Centralized state in the main app model
  • Screen-specific state in individual screen models

Data Persistence

  • Configuration files in JSON/YAML format
  • Request history stored locally
  • Support for multiple configuration profiles

Error Handling

  • Graceful degradation for network issues
  • User-friendly error messages in TUI
  • Proper error propagation in CLI mode

Performance

  • Lazy loading of screens and components
  • Efficient rendering with minimal redraws
  • Background processing for long-running requests

Testing Strategy

  • Unit tests for business logic
  • Integration tests for API client
  • TUI component testing where possible
  • CLI command testing

Success Metrics

Usability

  • Intuitive navigation flow
  • Fast response times (<100ms for UI interactions)
  • Clear error messages and feedback

Functionality

  • Support for all major HTTP methods
  • Proper handling of various content types
  • Reliable configuration management

Developer Experience

  • Clean, maintainable code structure
  • Comprehensive documentation
  • Easy to extend with new features

Future Enhancements

Potential Features

  • GraphQL support
  • WebSocket connections
  • Plugin system for custom authentication
  • Team collaboration features
  • API documentation integration
  • Mock server functionality

Performance Optimizations

  • Request caching
  • Concurrent request execution
  • Response streaming for large payloads

This plan provides a comprehensive roadmap for developing ein-cli with both CLI and TUI interfaces, ensuring a robust and user-friendly tool for API interactions.

Graph View

Backlinks