CLI Skills for LlamaFarm

Framework-specific patterns for the LlamaFarm CLI. These guidelines extend the shared Go skills with Cobra, Bubbletea, and Lipgloss best practices.

Tech Stack

• Go 1.24+

• Cobra (CLI framework)

• Bubbletea (TUI framework)

• Lipgloss (terminal styling)

• Bubbles (TUI components)

Directory Structure

cli/ cmd/ # Cobra command implementations config/ # Configuration types and loading orchestrator/ # Service management and process control utils/ # Shared utilities (HTTP, output, logging) version/ # Version and upgrade handling internal/ # Internal packages (not exported) tui/ # Reusable TUI components buildinfo/ # Build-time information

Quick Reference

Cobra Commands

• Use RunE over Run for error handling

• Register flags in init() functions

• Use persistent flags for shared options

• Validate arguments with Args field

Bubbletea TUI

• Implement Init() , Update() , View() interface

• Use message types for state changes

• Return tea.Cmd for async operations

• Keep state immutable in Update()

Lipgloss Styling

• Define styles as package-level constants

• Use lipgloss.NewStyle() for styling

• Handle terminal width dynamically

• Support color themes via style variables

Shared Go Skills

This skill extends the base Go skills. See:

Link Description

go-skills/SKILL.md Overview and quick reference

go-skills/patterns.md Idiomatic Go patterns

go-skills/concurrency.md Goroutines, channels, sync

go-skills/error-handling.md Error wrapping, sentinels

go-skills/testing.md Table-driven tests, mocks

go-skills/security.md Input validation, secure coding

CLI-Specific Checklists

File Description

cobra.md Cobra command patterns, flags, validation

bubbletea.md Bubbletea Model/Update/View patterns

performance.md CLI-specific optimizations

Key Patterns in This Codebase

Command Registration Pattern

var myCmd = &cobra.Command{ Use: "mycommand [args]", Short: "Brief description", Long: Extended description with examples., Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { // Implementation with error returns return nil }, }

func init() { rootCmd.AddCommand(myCmd) myCmd.Flags().StringVar(&flagVar, "flag", "default", "Flag description") }

TUI Model Pattern

type myModel struct { viewport viewport.Model textarea textarea.Model width int height int err error }

func (m myModel) Init() tea.Cmd { return tea.Batch(m.textarea.Focus(), doAsyncWork()) }

func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { var cmds []tea.Cmd switch msg := msg.(type) { case tea.WindowSizeMsg: m.width = msg.Width m.height = msg.Height case tea.KeyMsg: switch msg.String() { case "ctrl+c": return m, tea.Quit } } return m, tea.Batch(cmds...) }

func (m myModel) View() string { return lipgloss.JoinVertical(lipgloss.Left, m.viewport.View(), m.textarea.View(), ) }

Output API Pattern

// Use the output API for consistent messaging utils.OutputInfo("Starting service %s...", serviceName) utils.OutputSuccess("Service started successfully") utils.OutputError("Failed to start service: %v", err) utils.OutputProgress("Downloading model...") utils.OutputWarning("Service already running")

Service Orchestration Pattern

// Ensure services are running before operations factory := GetServiceConfigFactory() config := factory.ServerOnly(serverURL) orchestrator.EnsureServicesOrExitWithConfig(config, "server")

// Or with multiple services config := factory.RAGCommand(serverURL) orchestrator.EnsureServicesOrExitWithConfig(config, "server", "rag", "universal-runtime")

Guidelines

• User Experience First: CLI should feel responsive and provide clear feedback

• Graceful Degradation: Handle missing services, network errors, and timeouts gracefully

• Consistent Output: Use the output API for all user-facing messages

• Cross-Platform: Test on macOS, Linux, and Windows

• Terminal Compatibility: Test with different terminal emulators and sizes