Picture this: you’re staring at your screen, coffee in hand, contemplating whether to use yet another CLI framework or build your own. Well, grab another cup because today we’re diving deep into the rabbit hole of creating an extensible CLI framework in Go that’ll make your future self thank you (and maybe even high-five you through the screen). Building CLI applications in Go is like assembling IKEA furniture – it seems straightforward until you realize you need a framework that doesn’t exist yet. Sure, there are excellent options like Cobra, but sometimes you need something that fits your exact requirements like a well-tailored suit. Let’s roll up our sleeves and build something magnificent.
Why Reinvent the Wheel (And Make It Better)
Before we jump into code, let’s address the elephant in the room. Why build your own CLI framework when tools like Cobra exist? The answer lies in the beauty of customization and learning. Sometimes, existing frameworks are like wearing someone else’s shoes – they work, but they don’t quite fit perfectly. Building your own framework gives you:
- Complete control over the architecture and behavior
- Lightweight solutions tailored to your specific needs
- Deep understanding of how CLI frameworks work under the hood
- Flexibility to implement unique features that standard frameworks don’t offer
Architecture: The Foundation of Excellence
Let’s start with the architectural overview. Our framework will follow a modular design where commands are self-contained units that can be easily plugged into the main application.
Step 1: Building the Core Command Structure
Let’s start with the foundation – our Command struct. This will be the DNA of our framework.
// framework/command.go
package framework
import (
"flag"
"fmt"
"os"
"strings"
)
// Command represents a CLI command with its flags and execution logic
type Command struct {
Name string
Usage string
Description string
flags *flag.FlagSet
subCommands map[string]*Command
parent *Command
Execute func(cmd *Command, args []string) error
}
// NewCommand creates a new command instance
func NewCommand(name, usage, description string) *Command {
return &Command{
Name: name,
Usage: usage,
Description: description,
flags: flag.NewFlagSet(name, flag.ContinueOnError),
subCommands: make(map[string]*Command),
}
}
// Init initializes the command with provided arguments
func (c *Command) Init(args []string) error {
return c.flags.Parse(args)
}
// Called returns true if the command has been parsed
func (c *Command) Called() bool {
return c.flags.Parsed()
}
// Run executes the command
func (c *Command) Run(args []string) error {
if c.Execute != nil {
return c.Execute(c, args)
}
return fmt.Errorf("no execution handler defined for command: %s", c.Name)
}
This base structure gives us everything we need to start building our CLI empire. Notice how we’re storing subcommands in a map – this makes lookup lightning fast and keeps our code clean.
Step 2: Adding Flag Management Superpowers
Flags are the spice of CLI applications. Let’s add some robust flag management capabilities:
// Flag types for type safety
type FlagType int
const (
StringFlag FlagType = iota
IntFlag
BoolFlag
Float64Flag
)
// FlagDefinition defines a flag with its properties
type FlagDefinition struct {
Name string
Type FlagType
Usage string
DefaultValue interface{}
Required bool
}
// AddFlag adds a flag definition to the command
func (c *Command) AddFlag(def FlagDefinition) {
switch def.Type {
case StringFlag:
defaultVal := ""
if def.DefaultValue != nil {
defaultVal = def.DefaultValue.(string)
}
c.flags.String(def.Name, defaultVal, def.Usage)
case IntFlag:
defaultVal := 0
if def.DefaultValue != nil {
defaultVal = def.DefaultValue.(int)
}
c.flags.Int(def.Name, defaultVal, def.Usage)
case BoolFlag:
defaultVal := false
if def.DefaultValue != nil {
defaultVal = def.DefaultValue.(bool)
}
c.flags.Bool(def.Name, defaultVal, def.Usage)
case Float64Flag:
defaultVal := 0.0
if def.DefaultValue != nil {
defaultVal = def.DefaultValue.(float64)
}
c.flags.Float64(def.Name, defaultVal, def.Usage)
}
}
// GetStringFlag retrieves a string flag value
func (c *Command) GetStringFlag(name string) string {
if flag := c.flags.Lookup(name); flag != nil {
return flag.Value.String()
}
return ""
}
// GetIntFlag retrieves an int flag value
func (c *Command) GetIntFlag(name string) int {
if flag := c.flags.Lookup(name); flag != nil {
if val, ok := flag.Value.(*flag.Value); ok {
// This is a simplified version - in production, you'd want proper type assertion
return 0 // placeholder
}
}
return 0
}
// GetBoolFlag retrieves a bool flag value
func (c *Command) GetBoolFlag(name string) bool {
if flag := c.flags.Lookup(name); flag != nil {
return flag.Value.String() == "true"
}
return false
}
Step 3: The Command Registry – Your CLI’s Phone Book
Now let’s create a registry system that manages all our commands like a well-organized phonebook:
// framework/registry.go
package framework
import (
"fmt"
"sort"
"strings"
)
// Registry manages all registered commands
type Registry struct {
commands map[string]*Command
rootCmd *Command
}
// NewRegistry creates a new command registry
func NewRegistry() *Registry {
return &Registry{
commands: make(map[string]*Command),
}
}
// SetRootCommand sets the root command for the CLI
func (r *Registry) SetRootCommand(cmd *Command) {
r.rootCmd = cmd
r.commands[""] = cmd // Empty string key for root
}
// RegisterCommand registers a new command
func (r *Registry) RegisterCommand(cmd *Command) error {
if cmd.Name == "" {
return fmt.Errorf("command name cannot be empty")
}
if _, exists := r.commands[cmd.Name]; exists {
return fmt.Errorf("command '%s' is already registered", cmd.Name)
}
r.commands[cmd.Name] = cmd
return nil
}
// GetCommand retrieves a command by name
func (r *Registry) GetCommand(name string) (*Command, bool) {
cmd, exists := r.commands[name]
return cmd, exists
}
// ListCommands returns all registered command names
func (r *Registry) ListCommands() []string {
var names []string
for name := range r.commands {
if name != "" { // Skip root command
names = append(names, name)
}
}
sort.Strings(names)
return names
}
// Execute executes the appropriate command based on arguments
func (r *Registry) Execute(args []string) error {
if len(args) == 0 {
if r.rootCmd != nil {
return r.rootCmd.Run([]string{})
}
return r.showHelp()
}
cmdName := args
cmd, exists := r.GetCommand(cmdName)
if !exists {
return fmt.Errorf("unknown command: %s", cmdName)
}
// Parse flags and execute
if err := cmd.Init(args[1:]); err != nil {
return fmt.Errorf("failed to parse flags for '%s': %w", cmdName, err)
}
return cmd.Run(cmd.flags.Args())
}
// showHelp displays help information
func (r *Registry) showHelp() error {
fmt.Println("Available commands:")
for _, name := range r.ListCommands() {
if cmd, exists := r.GetCommand(name); exists {
fmt.Printf(" %-15s %s\n", name, cmd.Description)
}
}
return nil
}
Step 4: Making It Extensible with Plugins
Here’s where the magic happens – let’s make our framework extensible through a plugin system:
// framework/plugin.go
package framework
import (
"fmt"
"reflect"
)
// Plugin represents a plugin that can extend the CLI
type Plugin interface {
Name() string
Version() string
Initialize(*Registry) error
Commands() []*Command
}
// PluginManager manages plugins
type PluginManager struct {
plugins []Plugin
registry *Registry
}
// NewPluginManager creates a new plugin manager
func NewPluginManager(registry *Registry) *PluginManager {
return &PluginManager{
plugins: []Plugin{},
registry: registry,
}
}
// RegisterPlugin registers a new plugin
func (pm *PluginManager) RegisterPlugin(plugin Plugin) error {
// Check for duplicate plugins
for _, p := range pm.plugins {
if p.Name() == plugin.Name() {
return fmt.Errorf("plugin '%s' is already registered", plugin.Name())
}
}
// Initialize the plugin
if err := plugin.Initialize(pm.registry); err != nil {
return fmt.Errorf("failed to initialize plugin '%s': %w", plugin.Name(), err)
}
// Register plugin commands
for _, cmd := range plugin.Commands() {
if err := pm.registry.RegisterCommand(cmd); err != nil {
return fmt.Errorf("failed to register command from plugin '%s': %w", plugin.Name(), err)
}
}
pm.plugins = append(pm.plugins, plugin)
return nil
}
// GetPlugins returns all registered plugins
func (pm *PluginManager) GetPlugins() []Plugin {
return pm.plugins
}
// BasePlugin provides a base implementation for plugins
type BasePlugin struct {
name string
version string
}
// NewBasePlugin creates a new base plugin
func NewBasePlugin(name, version string) *BasePlugin {
return &BasePlugin{
name: name,
version: version,
}
}
func (bp *BasePlugin) Name() string { return bp.name }
func (bp *BasePlugin) Version() string { return bp.version }
func (bp *BasePlugin) Initialize(*Registry) error { return nil }
func (bp *BasePlugin) Commands() []*Command { return []*Command{} }
Step 5: Advanced Features – Middleware and Hooks
Let’s add some middleware support for cross-cutting concerns like logging, authentication, and validation:
// framework/middleware.go
package framework
import (
"context"
"fmt"
"time"
)
// MiddlewareFunc represents a middleware function
type MiddlewareFunc func(ctx context.Context, cmd *Command, args []string, next func() error) error
// CommandWithMiddleware wraps a command with middleware support
type CommandWithMiddleware struct {
*Command
middlewares []MiddlewareFunc
}
// NewCommandWithMiddleware creates a new command with middleware support
func NewCommandWithMiddleware(name, usage, description string) *CommandWithMiddleware {
return &CommandWithMiddleware{
Command: NewCommand(name, usage, description),
middlewares: []MiddlewareFunc{},
}
}
// Use adds a middleware to the command
func (c *CommandWithMiddleware) Use(middleware MiddlewareFunc) {
c.middlewares = append(c.middlewares, middleware)
}
// RunWithMiddleware executes the command with all middleware applied
func (c *CommandWithMiddleware) RunWithMiddleware(ctx context.Context, args []string) error {
// Create the final handler
finalHandler := func() error {
return c.Command.Run(args)
}
// Build the middleware chain (reverse order)
handler := finalHandler
for i := len(c.middlewares) - 1; i >= 0; i-- {
middleware := c.middlewares[i]
currentHandler := handler
handler = func() error {
return middleware(ctx, c.Command, args, currentHandler)
}
}
return handler()
}
// Common middleware implementations
// LoggingMiddleware logs command execution
func LoggingMiddleware(ctx context.Context, cmd *Command, args []string, next func() error) error {
start := time.Now()
fmt.Printf("Executing command: %s\n", cmd.Name)
err := next()
duration := time.Since(start)
if err != nil {
fmt.Printf("Command '%s' failed after %v: %v\n", cmd.Name, duration, err)
} else {
fmt.Printf("Command '%s' completed successfully in %v\n", cmd.Name, duration)
}
return err
}
// ValidationMiddleware validates command arguments
func ValidationMiddleware(minArgs int) MiddlewareFunc {
return func(ctx context.Context, cmd *Command, args []string, next func() error) error {
if len(args) < minArgs {
return fmt.Errorf("command '%s' requires at least %d arguments, got %d", cmd.Name, minArgs, len(args))
}
return next()
}
}
Step 6: Putting It All Together – A Real-World Example
Now for the grand finale – let’s create a practical example that demonstrates our framework in action. We’ll build a file management CLI tool:
// main.go
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"your-module/framework"
)
// FilePlugin implements a file management plugin
type FilePlugin struct {
*framework.BasePlugin
}
// NewFilePlugin creates a new file plugin
func NewFilePlugin() *FilePlugin {
return &FilePlugin{
BasePlugin: framework.NewBasePlugin("file-manager", "1.0.0"),
}
}
// Commands returns the commands provided by this plugin
func (fp *FilePlugin) Commands() []*framework.Command {
// List files command
listCmd := framework.NewCommand("list", "list [directory]", "List files in a directory")
listCmd.AddFlag(framework.FlagDefinition{
Name: "all",
Type: framework.BoolFlag,
Usage: "Show hidden files",
DefaultValue: false,
})
listCmd.Execute = fp.listFiles
// Create file command
createCmd := framework.NewCommand("create", "create <filename>", "Create a new file")
createCmd.AddFlag(framework.FlagDefinition{
Name: "content",
Type: framework.StringFlag,
Usage: "Initial content for the file",
DefaultValue: "",
})
createCmd.Execute = fp.createFile
return []*framework.Command{listCmd, createCmd}
}
// listFiles implements the list command
func (fp *FilePlugin) listFiles(cmd *framework.Command, args []string) error {
dir := "."
if len(args) > 0 {
dir = args
}
showAll := cmd.GetBoolFlag("all")
entries, err := os.ReadDir(dir)
if err != nil {
return fmt.Errorf("failed to read directory: %w", err)
}
fmt.Printf("Contents of %s:\n", dir)
for _, entry := range entries {
if !showAll && entry.Name() == '.' {
continue
}
if entry.IsDir() {
fmt.Printf(" 📁 %s/\n", entry.Name())
} else {
fmt.Printf(" 📄 %s\n", entry.Name())
}
}
return nil
}
// createFile implements the create command
func (fp *FilePlugin) createFile(cmd *framework.Command, args []string) error {
if len(args) == 0 {
return fmt.Errorf("filename is required")
}
filename := args
content := cmd.GetStringFlag("content")
// Create directory if it doesn't exist
dir := filepath.Dir(filename)
if dir != "." {
if err := os.MkdirAll(dir, 0755); err != nil {
return fmt.Errorf("failed to create directory: %w", err)
}
}
file, err := os.Create(filename)
if err != nil {
return fmt.Errorf("failed to create file: %w", err)
}
defer file.Close()
if content != "" {
if _, err := file.WriteString(content); err != nil {
return fmt.Errorf("failed to write content: %w", err)
}
}
fmt.Printf("✅ File '%s' created successfully!\n", filename)
return nil
}
func main() {
// Create registry and plugin manager
registry := framework.NewRegistry()
pluginManager := framework.NewPluginManager(registry)
// Create root command
rootCmd := framework.NewCommand("filemanager", "filemanager <command>", "A file management CLI tool")
rootCmd.Execute = func(cmd *framework.Command, args []string) error {
fmt.Println("File Manager CLI v1.0.0")
fmt.Println("Use 'filemanager help' for available commands")
return nil
}
registry.SetRootCommand(rootCmd)
// Register help command
helpCmd := framework.NewCommand("help", "help", "Show help information")
helpCmd.Execute = func(cmd *framework.Command, args []string) error {
fmt.Println("Available commands:")
for _, name := range registry.ListCommands() {
if command, exists := registry.GetCommand(name); exists {
fmt.Printf(" %-10s %s\n", name, command.Description)
}
}
return nil
}
registry.RegisterCommand(helpCmd)
// Register file plugin
filePlugin := NewFilePlugin()
if err := pluginManager.RegisterPlugin(filePlugin); err != nil {
fmt.Printf("Failed to register file plugin: %v\n", err)
os.Exit(1)
}
// Execute
if err := registry.Execute(os.Args[1:]); err != nil {
fmt.Printf("Error: %v\n", err)
os.Exit(1)
}
}
Step 7: Testing and Validation
Let’s add some testing utilities to ensure our framework works flawlessly:
// framework/testing.go
package framework
import (
"bytes"
"fmt"
"io"
"os"
"testing"
)
// TestContext provides utilities for testing CLI commands
type TestContext struct {
stdout *bytes.Buffer
stderr *bytes.Buffer
stdin *bytes.Buffer
}
// NewTestContext creates a new test context
func NewTestContext() *TestContext {
return &TestContext{
stdout: &bytes.Buffer{},
stderr: &bytes.Buffer{},
stdin: &bytes.Buffer{},
}
}
// CaptureOutput captures stdout and stderr for testing
func (tc *TestContext) CaptureOutput(fn func()) (string, string) {
// Save original
oldStdout := os.Stdout
oldStderr := os.Stderr
// Create pipes
r, w, _ := os.Pipe()
os.Stdout = w
os.Stderr = w
// Run function
fn()
// Restore
w.Close()
os.Stdout = oldStdout
os.Stderr = oldStderr
// Read output
var buf bytes.Buffer
io.Copy(&buf, r)
return buf.String(), buf.String()
}
// TestCommand provides a helper for testing commands
func TestCommand(t *testing.T, cmd *Command, args []string, expectedOutput string) {
ctx := NewTestContext()
output, _ := ctx.CaptureOutput(func() {
if err := cmd.Init(args); err != nil {
t.Fatalf("Failed to initialize command: %v", err)
}
if err := cmd.Run(cmd.flags.Args()); err != nil {
t.Fatalf("Command execution failed: %v", err)
}
})
if output != expectedOutput {
t.Errorf("Expected output '%s', got '%s'", expectedOutput, output)
}
}
Advanced Architecture Patterns
Our framework supports several advanced patterns that make it truly extensible: Command Composition: Commands can be composed of smaller, reusable components. Event-Driven Architecture: Commands can emit and listen to events for loose coupling. Dependency Injection: Commands can declare dependencies that are automatically resolved. Configuration Management: Built-in support for configuration files and environment variables.
Performance Considerations
When building CLI frameworks, performance matters. Here are some optimizations our framework includes:
- Lazy Loading: Commands and plugins are loaded only when needed
- Efficient Parsing: Flag parsing is optimized for common use cases
- Memory Management: Careful memory allocation to minimize GC pressure
- Caching: Frequently accessed data is cached for better performance
Real-World Usage Patterns
Here are some patterns I’ve found effective when using this framework in production: Plugin Architecture: Organize features as plugins for better modularity. Configuration Layers: Support multiple configuration sources (files, environment, flags). Error Handling: Implement consistent error handling across all commands. Logging Integration: Built-in support for structured logging.
Conclusion: Your CLI Framework Journey
Building an extensible CLI framework in Go is like crafting a fine instrument – it requires patience, attention to detail, and a deep understanding of the problem you’re solving. Our framework provides a solid foundation that can grow with your needs while maintaining simplicity and performance. The beauty of this approach lies in its extensibility. Whether you’re building a simple utility or a complex multi-command application, this framework adapts to your requirements rather than forcing you into a rigid structure. Remember, the best framework is the one that gets out of your way and lets you focus on what matters – solving problems and delivering value to your users. With the foundation we’ve built today, you’re well-equipped to create CLI applications that are not just functional, but truly delightful to use. Now go forth and build amazing CLI tools! Your future self (and your users) will thank you for the thoughtful architecture and extensible design. And who knows? Maybe someone will write a blog post about how awesome your CLI framework is. That’s the dream, right? Happy coding! 🚀