📝 docs: add comprehensive version management and CLI documentation
This commit is contained in:
198
adr/0015-cli-subcommands-cobra.md
Normal file
198
adr/0015-cli-subcommands-cobra.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# 15. CLI Subcommands and Flag Management with Cobra
|
||||
|
||||
**Date:** 2026-04-05
|
||||
**Status:** 🟡 Proposed
|
||||
**Authors:** DanceLessonsCoach Team
|
||||
**Decision Date:** TBD
|
||||
**Implementation Status:** Not Started
|
||||
|
||||
## Context
|
||||
|
||||
As DanceLessonsCoach 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 (Next Sprint)
|
||||
```go
|
||||
var rootCmd = &cobra.Command{
|
||||
Use: "dance-lessons-coach",
|
||||
Short: "DanceLessonsCoach - API server and CLI tools",
|
||||
Long: `DanceLessonsCoach provides greeting services and API management.
|
||||
|
||||
To begin working with DanceLessonsCoach, 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 DanceLessonsCoach 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")
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
func init() {
|
||||
rootCmd.AddCommand(versionCmd)
|
||||
rootCmd.AddCommand(serverCmd)
|
||||
|
||||
// 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")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 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
|
||||
- ❌ **Migration**: Move existing flags to cobra
|
||||
- ❌ **Documentation**: Update docs with new CLI
|
||||
- ❌ **Testing**: Ensure all functionality works
|
||||
|
||||
### 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:** DanceLessonsCoach Team
|
||||
**Approvers Needed:** @gabrielradureau
|
||||
Reference in New Issue
Block a user