Skip to content

CLI Architecture & Go Development

The edge-cli tool is the primary entry point for managing the Edge Computing LLM platform. It is built in Go using the Cobra framework for command routing and Viper for configuration management.

Architecture Overview

graph TD
    A[edge-cli Entrypoint] --> B(Cobra Root Command)
    B --> C{Subcommands}
    C -->|apply| D[Applier Package]
    C -->|verify| E[Verifier Package]
    C -->|logs| F[Logger Package]
    C -->|doctor| G[Doctor Package]

    D --> H[pkg/kubernetes]
    D --> I[pkg/helm]

    E --> H
    E --> J[pkg/nvidia]

    H --> K[pkg/edgebase]
    I --> K
    J --> K

Core Packages

The CLI is modularized into several internal and reusable packages:

1. cmd/

Contains the Cobra command definitions. Each subcommand (e.g., cmd/apply.go, cmd/verify.go) registers itself with the root command and delegates actual logic to the internal packages.

2. internal/

Contains business logic specific to edge-cli.

  • internal/kubernetes: Wrappers for kubectl operations, client-go integration, and namespace management.
  • internal/helm: Helm chart installation, upgrade, and values overlay management.
  • internal/nvidia: Interaction with NVIDIA container toolkit, GPU operator checks, and DCGM metrics.
  • internal/config: Viper configuration loading, profile resolution (lite, standard, heavy).
  • internal/platform: High-level platform orchestration logic.
  • internal/doctor: System health checks, prerequisite validation.
  • internal/app: Application lifecycle management (Ollama, Open WebUI).
  • internal/logging: Structured logging using slog or logrus.
  • internal/execx: Robust command execution wrappers with timeout and context support.

3. pkg/edgebase

This is a shared library, originally from k3s-nvidia-edge, that provides common utilities for Go CLIs in the ecosystem: - File system helpers - Common types and constants - Standardized error handling - Output formatters (table, JSON, YAML)

Command Design Principles

  1. Idempotency: Commands like edge-cli apply should be safe to run multiple times. They should converge the cluster to the desired state.
  2. Context-Awareness: All long-running operations must accept a context.Context to support cancellation and timeouts.
  3. Structured Output: Support --output json or --output yaml for programmatic consumption, while defaulting to human-readable text.
  4. Fail Fast: The doctor command or pre-flight checks should catch missing dependencies (e.g., missing Helm, disconnected GPU) before attempting complex operations.

Tutorial: Adding a New Command

Let's add a theoretical edge-cli models list command.

Step 1: Create the Command File Create cmd/models_list.go:

package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
    "github.com/your-org/edge-cli/internal/app"
)

var modelsListCmd = &cobra.Command{
    Use:   "list",
    Short: "List available LLM models",
    RunE: func(cmd *cobra.Command, args []string) error {
        models, err := app.ListModels(cmd.Context())
        if err != nil {
            return err
        }

        for _, m := range models {
            fmt.Printf("- %s (Size: %s)\n", m.Name, m.Size)
        }
        return nil
    },
}

func init() {
    modelsCmd.AddCommand(modelsListCmd)
}

Step 2: Implement the Logic In internal/app/models.go:

package app

import (
    "context"
    // ... imports
)

type Model struct {
    Name string
    Size string
}

func ListModels(ctx context.Context) ([]Model, error) {
    // Logic to query Ollama API at http://ollama.llm-observability.svc.cluster.local:11434
    // ...
    return []Model{{"llama3", "4.7GB"}}, nil
}

Step 3: Update Makefile & Build Run make build and test your new command: 

./bin/edge-cli models list

Logging and Debugging

Use the --debug flag to enable verbose logging. Ensure all internal packages use the provided logger instance rather than standard log or fmt.Println for debug information.