CLI Framework
Enterprise-grade CLI framework for building command-line tools with Forge. Features commands, subcommands, flags, middleware, prompts, tables, plugins, and seamless Forge App integration.
Forge CLI Framework is an enterprise-grade CLI framework for building powerful command-line tools in Go. It provides a comprehensive foundation for creating interactive, user-friendly CLI applications with modern UX patterns, extensive customization options, and seamless integration with Forge applications.
The CLI framework is production-ready and actively maintained. It's designed to work both standalone and integrated with Forge applications for accessing services via dependency injection.
Key Features
🎯 Commands & Subcommands
Hierarchical command structure with support for nested subcommands, aliases, and middleware
🚩 Comprehensive Flags
String, int, bool, slice, duration flags with validation, default values, and short aliases
💬 Interactive Prompts
Input, confirm, select, multi-select with arrow key navigation and modern UX patterns
📊 Progress & Tables
Progress bars, spinners, and formatted tables with multiple styles and color support
🔌 Plugin System
Modular, composable plugin architecture for extending CLI functionality
🔗 Forge Integration
Seamless integration with Forge apps for accessing services via dependency injection
Architecture Overview
The CLI framework follows a modular architecture with clear separation of concerns:
Core Components:
- CLI: Main application with command management and execution
- Commands: Hierarchical command structure with subcommands and aliases
- Flags: Type-safe flag parsing with validation and default values
- Context: Command execution context with access to flags, args, and services
- Parser: Argument and flag parsing with error handling
- Logger: CLI-optimized logging with color-coded output
- Help: Auto-generated help text and usage information
Interactive Components:
- Prompts: Input, confirm, select, multi-select with arrow key navigation
- Progress: Progress bars and spinners for long-running operations
- Tables: Formatted tables with multiple styles and color support
- Colors: ANSI color support with automatic terminal detection
- Completion: Shell completion for Bash, Zsh, and Fish
Integration Features:
- Plugins: Modular plugin system for extending functionality
- Middleware: Before/after command hooks for cross-cutting concerns
- Forge Integration: Access to Forge app services via dependency injection
- Error Handling: Structured error handling with exit codes
- Testing: Comprehensive testing utilities for CLI applications
Key Features
✅ Commands & Subcommands - Hierarchical command structure
✅ Comprehensive Flags - String, int, bool, slice, duration with validation
✅ Interactive Prompts - Input, confirm, select, multi-select with arrow key navigation ⬆️⬇️
✅ Space Bar Selection - Toggle multi-select with spacebar (modern UX) ⎵
✅ Progress Indicators - Progress bars and spinners
✅ Table Output - Formatted, colored tables with multiple styles
✅ Middleware - Before/after command hooks
✅ Plugin System - Modular, composable commands
✅ CLI-Optimized Logger - Color-coded, simple output
✅ Auto-Generated Help - Automatic help text generation
✅ Shell Completion - Bash, Zsh, Fish completion
✅ Forge Integration - Access to DI container and services
Quick Start
Get started with the CLI framework in minutes:
Make sure you have Go 1.21+ installed. The CLI framework works both standalone and integrated with Forge applications.
# Create a new Go module
mkdir my-cli-tool && cd my-cli-tool
go mod init my-cli-tool
# Add CLI framework dependency
go get github.com/xraph/forge/clipackage main
import (
"fmt"
"os"
"github.com/xraph/forge/cli"
)
func main() {
// Create CLI application
app := cli.New(cli.Config{
Name: "mytool",
Version: "1.0.0",
Description: "My awesome CLI tool",
})
// Add a hello command with flags
helloCmd := cli.NewCommand(
"hello",
"Say hello to someone",
func(ctx cli.CommandContext) error {
name := ctx.String("name")
if name == "" {
name = "World"
}
ctx.Success(fmt.Sprintf("Hello, %s!", name))
return nil
},
cli.WithFlag(cli.NewStringFlag("name", "n", "Name to greet", "")),
)
app.AddCommand(helloCmd)
// Run the CLI
if err := app.Run(os.Args); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(cli.GetExitCode(err))
}
}package main
import (
"os"
"github.com/xraph/forge"
"github.com/xraph/forge/cli"
)
func main() {
// Create Forge app
app := forge.NewApp(forge.AppConfig{
Name: "myapp",
Version: "1.0.0",
Environment: "development",
})
// Register services
forge.RegisterSingleton(app.Container(), "userService",
func(c forge.Container) (*UserService, error) {
return NewUserService(), nil
})
// Create CLI with Forge integration
cliApp := cli.NewForgeIntegratedCLI(app, cli.Config{
Name: "myapp-cli",
Version: "1.0.0",
Description: "CLI with Forge integration",
})
// Add command that uses Forge services
userCmd := cli.NewCommand(
"user",
"Manage users",
func(ctx cli.CommandContext) error {
// Access Forge service via DI
userService, err := cli.GetService[*UserService](ctx, "userService")
if err != nil {
return err
}
users := userService.ListUsers()
// Display in table format
table := ctx.Table()
table.SetHeader([]string{"ID", "Name", "Email"})
for _, user := range users {
table.AppendRow([]string{user.ID, user.Name, user.Email})
}
table.Render()
return nil
},
)
cliApp.AddCommand(userCmd)
// Run the CLI
if err := cliApp.Run(os.Args); err != nil {
os.Exit(cli.GetExitCode(err))
}
}Interactive Example
The CLI framework excels at creating interactive command-line experiences:
setupCmd := cli.NewCommand(
"setup",
"Interactive setup wizard",
func(ctx cli.CommandContext) error {
ctx.Info("Welcome to the setup wizard!")
// Simple prompt
name, err := ctx.Prompt("What's your name?")
if err != nil {
return err
}
// Confirm prompt
confirmed, err := ctx.Confirm(fmt.Sprintf("Is '%s' correct?", name))
if err != nil {
return err
}
if !confirmed {
ctx.Warning("Setup cancelled")
return nil
}
// Select with arrow keys
env, err := ctx.Select("Choose environment:", []string{
"development",
"staging",
"production",
})
if err != nil {
return err
}
// Multi-select with spacebar
features, err := ctx.MultiSelect("Select features:", []string{
"database",
"cache",
"events",
"streaming",
})
if err != nil {
return err
}
// Progress bar for setup
progress := ctx.ProgressBar(100)
for i := 0; i <= 100; i += 10 {
progress.Set(i)
time.Sleep(100 * time.Millisecond)
}
progress.Finish("Setup complete!")
ctx.Success("Configuration saved!")
return nil
},
)Next Steps
🎯 Commands
Learn how to create commands, subcommands, and organize your CLI structure
🚩 Flags
Master flag types, validation, and advanced flag configuration
💬 Prompts
Create interactive experiences with prompts, selections, and user input
📊 Output
Format output with tables, progress bars, colors, and styling
Community & Support
- GitHub: xraph/forge - Source code and issues
- Examples: Check the
/cli/examplesdirectory for real-world examples - Documentation: Comprehensive guides and API reference
- Contributing: We welcome contributions and feedback
Ready to build powerful CLI tools? Let's start with commands!
How is this guide?
Last updated on