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`

```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

```bash
# 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](https://github.com/spf13/cobra)
- [Cobra Documentation](https://cobra.dev/)
- [CLI Guidelines](https://clig.dev/)
- [Go CLI Best Practices](https://github.com/clig-dev/clig)

---

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