dance-lessons-coach/adr/0015-cli-subcommands-cobra.md

15. CLI Subcommands and Flag Management with Cobra

Date: 2026-04-05 Status: Implemented Authors: Arcodange Team Decision Date: 2026-04-05 Implementation Status: Phase 1 Complete

Context

As dance-lessons-coach grows, we need a more robust and maintainable CLI structure. Currently, we use simple flag parsing (--version), but this approach has limitations:

1. Limited scalability: Adding more commands/flags becomes messy
2. Poor user experience: No built-in help, completion, or validation
3. Hard to maintain: Manual flag parsing is error-prone
4. No subcommands: Can't easily add commands like server start, server stop, etc.

Decision Drivers

• Scalability: Support growing CLI needs as project expands
• User Experience: Provide professional CLI with help, completion, validation
• Maintainability: Easy to add/remove commands and flags
• Standards: Follow industry best practices for CLI tools
• Extensibility: Support future commands (migrate, seed, etc.)
• Integration: Work well with existing config system

Decision

We will adopt Cobra as our CLI framework. Cobra is a mature, widely-used library for building modern CLI applications in Go.

Selected Solution: Cobra CLI Framework

Repository: https://github.com/spf13/cobra Version: v1.8.0 (or latest stable)

Key Features

1. Subcommands: server start, server stop, migrate, etc.
2. Flags: --config, --env, --verbose, etc.
3. Help System: Automatic --help generation
4. Shell Completion: Built-in support
5. Validation: Type-safe flag parsing
6. Middleware: Pre/post command hooks

Implementation Plan

Phase 1: Basic Integration (✅ COMPLETED)

Implemented in: cmd/cli/main.go

var rootCmd = &cobra.Command{
    Use:   "dance-lessons-coach",
    Short: "dance-lessons-coach - API server and CLI tools",
    Long: `dance-lessons-coach provides greeting services and API management.

To begin working with dance-lessons-coach, run:
  dance-lessons-coach server --help`,
    SilenceUsage: true,
}

var versionCmd = &cobra.Command{
    Use:   "version",
    Short: "Print version information",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println(version.Full())
    },
}

var serverCmd = &cobra.Command{
    Use:   "server",
    Short: "Start the dance-lessons-coach server",
    Run: func(cmd *cobra.Command, args []string) {
        // Load config and start server
        cfg, err := config.LoadConfig()
        if err != nil {
            log.Fatal().Err(err).Msg("Failed to load configuration")
        }
        server := server.NewServer(cfg, context.Background())
        if err := server.Run(); err != nil {
            log.Fatal().Err(err).Msg("Server failed")
        }
    },
}

var greetCmd = &cobra.Command{
    Use:   "greet [name]",
    Short: "Greet someone by name",
    Args:  cobra.MaximumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        name := ""
        if len(args) > 0 {
            name = args[0]
        }
        fmt.Printf("Hello %s!\n", name)
    },
}

func init() {
    rootCmd.AddCommand(versionCmd)
    rootCmd.AddCommand(serverCmd)
    rootCmd.AddCommand(greetCmd)

    // Add flags to server command
    serverCmd.Flags().String("config", "", "Config file path")
    serverCmd.Flags().String("env", "", "Environment (dev, staging, prod)")
    serverCmd.Flags().Bool("debug", false, "Enable debug logging")
}

func main() {
    if err := rootCmd.Execute(); err != nil {
        log.Fatal().Err(err).Msg("CLI execution failed")
    }
}

Current Commands:

• version: Print version information
• server: Start the dance-lessons-coach server
• greet [name]: Greet someone by name
• help: Built-in help system
• completion: Shell completion scripts (automatic)

Current Flags:

• --config: Config file path (server command)
• --env: Environment (dev, staging, prod) (server command)
• --debug: Enable debug logging (server command)
• --help: Help for any command (built-in)

Phase 2: Advanced Features (Future)

• Subcommand groups: server, db, migrate, tools
• Persistent flags: Global flags like --config, --env
• Command aliases: Shorter command names
• Custom help templates: Branded help output
• Shell completion scripts: Generate completion for bash/zsh/fish

Phase 3: Migration (Ongoing)

• Migrate existing flags to Cobra
• Deprecate old flag parsing
• Update documentation
• Add new commands as needed

Migration Strategy

1. Incremental adoption: Start with version command, then server command
2. Backward compatibility: Support old flags during transition
3. Documentation: Update README with new CLI usage
4. Testing: Ensure all existing functionality works

Command Structure Proposal

# Main commands
dance-lessons-coach server    # Start the server
dance-lessons-coach version   # Show version
dance-lessons-coach migrate   # Database migrations
dance-lessons-coach config    # Config management

# Server subcommands
dance-lessons-coach server start    # Start server
dance-lessons-coach server stop     # Stop server
dance-lessons-coach server restart # Restart server
dance-lessons-coach server status   # Server status

# Global flags
dance-lessons-coach --help      # Show help
dance-lessons-coach --version   # Show version (shortcut)
dance-lessons-coach --config /path/to/config.yaml

# Example usage
dance-lessons-coach server start --env production --debug
dance-lessons-coach migrate up
dance-lessons-coach config validate

Pros and Cons of Cobra

✅ Advantages

1. Industry Standard: Used by Kubernetes, Hugo, etcd, and many others
2. Mature Ecosystem: Well-documented, widely adopted
3. Feature Rich: Help, completion, validation built-in
4. Extensible: Easy to add new commands
5. Go Idiomatic: Fits well with Go patterns
6. Good Documentation: Excellent docs and examples

❌ Disadvantages

1. Learning Curve: New patterns to learn
2. Migration Effort: Need to refactor existing code
3. Slight Overhead: More complex than simple flag parsing
4. Dependency: Adds cobra to project

Validation

Does this meet our requirements?

• ✅ Scalability: Easy to add new commands
• ✅ User Experience: Professional CLI with help/completion
• ✅ Maintainability: Clean, structured code
• ✅ Standards: Follows industry best practices
• ✅ Extensibility: Supports future growth
• ✅ Integration: Works with existing config system

What's still needed?

• ✅ Implementation: Actual cobra integration (Phase 1 complete)
• ❌ Migration: Move existing flags to cobra (Phase 2)
• ❌ Documentation: Update docs with new CLI (Phase 2)
• ❌ Testing: Ensure all functionality works (Phase 2)

Future Enhancements

1. Add more commands: migrate, config, db, etc.
2. Improve help: Custom templates, examples
3. Add completion: Shell completion scripts
4. Enhance validation: Better error messages
5. Add aliases: Shorter command names

References

• Cobra GitHub
• Cobra Documentation
• CLI Guidelines
• Go CLI Best Practices

---

Status: Proposed Next Review: 2026-04-12
Implementation Owner: Arcodange Team
Approvers Needed: @gabrielradureau