Agent skill

cli-skills

CLI best practices for LlamaFarm. Covers Cobra, Bubbletea, Lipgloss patterns for Go CLI development.

View SKILL.md on GitHub Repository
Stars 831
Forks 48

Install this agent skill to your Project

npx add-skill https://github.com/llama-farm/llamafarm/tree/main/.claude/skills/cli-skills

SKILL.md

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

go
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

go
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

go
// 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

go
// 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

  1. User Experience First: CLI should feel responsive and provide clear feedback
  2. Graceful Degradation: Handle missing services, network errors, and timeouts gracefully
  3. Consistent Output: Use the output API for all user-facing messages
  4. Cross-Platform: Test on macOS, Linux, and Windows
  5. Terminal Compatibility: Test with different terminal emulators and sizes

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

llama-farm/llamafarm

common-skills

Best practices for the Common utilities package in LlamaFarm. Covers HuggingFace Hub integration, GGUF model management, and shared utilities.

831 48
Explore
llama-farm/llamafarm

typescript-skills

Shared TypeScript best practices for Designer and Electron subsystems.

831 48
Explore
llama-farm/llamafarm

wt

Manage LlamaFarm worktrees for isolated parallel development. Create, start, stop, and clean up worktrees.

831 48
Explore
llama-farm/llamafarm

generate-subsystem-skills

Generate specialized skills for each subsystem in the monorepo. Creates shared language skills and subsystem-specific checklists for high-quality AI code generation.

831 48
Explore
llama-farm/llamafarm

temp-files

Guidelines for creating temporary files in system temp directory. Use when agents need to create reports, logs, or progress files without cluttering the repository.

831 48
Explore
llama-farm/llamafarm

code-review

Comprehensive code review for diffs. Analyzes changed code for security vulnerabilities, anti-patterns, and quality issues. Auto-detects domain (frontend/backend) from file paths.

831 48
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results