335 lines
8.2 KiB
Markdown
335 lines
8.2 KiB
Markdown
---
|
|
name: cli-patterns
|
|
description: Lightweight Go CLI patterns using urfave/cli. Use when building CLI tools, creating commands with flags, implementing subcommands, adding before/after hooks, organizing command categories, or when user mentions Go CLI, urfave/cli, cobra alternatives, CLI flags, CLI categories.
|
|
allowed-tools: Bash, Read, Write, Edit
|
|
---
|
|
|
|
# CLI Patterns Skill
|
|
|
|
Lightweight Go CLI patterns using urfave/cli for fast, simple command-line applications.
|
|
|
|
## Overview
|
|
|
|
Provides battle-tested patterns for building production-ready CLI tools in Go using urfave/cli v2. Focus on simplicity, speed, and maintainability over complex frameworks like Cobra.
|
|
|
|
## Why urfave/cli?
|
|
|
|
- **Lightweight**: Minimal dependencies, small binary size
|
|
- **Fast**: Quick compilation, fast execution
|
|
- **Simple API**: Easy to learn, less boilerplate than Cobra
|
|
- **Production-ready**: Used by Docker, Nomad, and many other tools
|
|
- **Native Go**: Feels like standard library code
|
|
|
|
## Core Patterns
|
|
|
|
### 1. Basic CLI Structure
|
|
|
|
Use `templates/basic-cli.go` for simple single-command CLIs:
|
|
- Main command with flags
|
|
- Help text generation
|
|
- Error handling
|
|
- Exit codes
|
|
|
|
### 2. Subcommands
|
|
|
|
Use `templates/subcommands-cli.go` for multi-command CLIs:
|
|
- Command hierarchy (app → command → subcommand)
|
|
- Shared flags across commands
|
|
- Command aliases
|
|
- Command categories
|
|
|
|
### 3. Flags and Options
|
|
|
|
Use `templates/flags-demo.go` for comprehensive flag examples:
|
|
- String, int, bool, duration flags
|
|
- Required vs optional flags
|
|
- Default values
|
|
- Environment variable fallbacks
|
|
- Flag aliases (short and long forms)
|
|
- Custom flag types
|
|
|
|
### 4. Command Categories
|
|
|
|
Use `templates/categories-cli.go` for organized command groups:
|
|
- Group related commands
|
|
- Better help text organization
|
|
- Professional CLI UX
|
|
- Examples: database commands, deploy commands, etc.
|
|
|
|
### 5. Before/After Hooks
|
|
|
|
Use `templates/hooks-cli.go` for lifecycle management:
|
|
- Global setup (before all commands)
|
|
- Global cleanup (after all commands)
|
|
- Per-command setup/teardown
|
|
- Initialization and validation
|
|
- Resource management
|
|
|
|
### 6. Context and State
|
|
|
|
Use `templates/context-cli.go` for shared state:
|
|
- Pass configuration between commands
|
|
- Share database connections
|
|
- Manage API clients
|
|
- Context values
|
|
|
|
## Scripts
|
|
|
|
### Generation Scripts
|
|
|
|
**`scripts/generate-basic.sh <app-name>`**
|
|
- Generates basic CLI structure
|
|
- Creates main.go with single command
|
|
- Adds common flags (verbose, config)
|
|
- Includes help text template
|
|
|
|
**`scripts/generate-subcommands.sh <app-name>`**
|
|
- Generates multi-command CLI
|
|
- Creates command structure
|
|
- Adds subcommand examples
|
|
- Includes command categories
|
|
|
|
**`scripts/generate-full.sh <app-name>`**
|
|
- Generates complete CLI with all patterns
|
|
- Includes before/after hooks
|
|
- Adds comprehensive flag examples
|
|
- Sets up command categories
|
|
- Includes context management
|
|
|
|
### Utility Scripts
|
|
|
|
**`scripts/add-command.sh <app-name> <command-name>`**
|
|
- Adds new command to existing CLI
|
|
- Updates command registration
|
|
- Creates command file
|
|
- Adds to appropriate category
|
|
|
|
**`scripts/add-flag.sh <file> <flag-name> <flag-type>`**
|
|
- Adds flag to command
|
|
- Supports all flag types
|
|
- Includes environment variable fallback
|
|
- Adds help text
|
|
|
|
**`scripts/validate-cli.sh <project-path>`**
|
|
- Validates CLI structure
|
|
- Checks for common mistakes
|
|
- Verifies flag definitions
|
|
- Ensures help text exists
|
|
|
|
## Templates
|
|
|
|
### Core Templates
|
|
|
|
**`templates/basic-cli.go`**
|
|
- Single-command CLI
|
|
- Standard flags (verbose, version)
|
|
- Error handling patterns
|
|
- Exit code management
|
|
|
|
**`templates/subcommands-cli.go`**
|
|
- Multi-command structure
|
|
- Command registration
|
|
- Shared flags
|
|
- Help text organization
|
|
|
|
**`templates/flags-demo.go`**
|
|
- All flag types demonstrated
|
|
- Environment variable fallbacks
|
|
- Required flag validation
|
|
- Custom flag types
|
|
|
|
**`templates/categories-cli.go`**
|
|
- Command categorization
|
|
- Professional help output
|
|
- Grouped commands
|
|
- Category-based organization
|
|
|
|
**`templates/hooks-cli.go`**
|
|
- Before/After hooks
|
|
- Global setup/teardown
|
|
- Per-command hooks
|
|
- Resource initialization
|
|
|
|
**`templates/context-cli.go`**
|
|
- Context management
|
|
- Shared state
|
|
- Configuration passing
|
|
- API client sharing
|
|
|
|
### TypeScript Equivalent (Node.js)
|
|
|
|
**`templates/commander-basic.ts`**
|
|
- commander.js equivalent patterns
|
|
- TypeScript type safety
|
|
- Similar API to urfave/cli
|
|
|
|
**`templates/oclif-basic.ts`**
|
|
- oclif framework patterns (Heroku/Salesforce style)
|
|
- Class-based commands
|
|
- Plugin system
|
|
|
|
### Python Equivalent
|
|
|
|
**`templates/click-basic.py`**
|
|
- click framework patterns
|
|
- Decorator-based commands
|
|
- Python CLI best practices
|
|
|
|
**`templates/typer-basic.py`**
|
|
- typer framework (FastAPI CLI)
|
|
- Type hints for validation
|
|
- Modern Python patterns
|
|
|
|
## Examples
|
|
|
|
### Example 1: Database CLI Tool
|
|
|
|
**`examples/db-cli/`**
|
|
- Complete database management CLI
|
|
- Commands: connect, migrate, seed, backup
|
|
- Categories: schema, data, admin
|
|
- Before hook: validate connection
|
|
- After hook: close connections
|
|
|
|
### Example 2: Deployment Tool
|
|
|
|
**`examples/deploy-cli/`**
|
|
- Deployment automation CLI
|
|
- Commands: build, test, deploy, rollback
|
|
- Categories: build, deploy, monitor
|
|
- Context: share deployment config
|
|
- Hooks: setup AWS credentials
|
|
|
|
### Example 3: API Client
|
|
|
|
**`examples/api-cli/`**
|
|
- REST API client CLI
|
|
- Commands: get, post, put, delete
|
|
- Global flags: auth token, base URL
|
|
- Before hook: authenticate
|
|
- Context: share HTTP client
|
|
|
|
### Example 4: File Processor
|
|
|
|
**`examples/file-cli/`**
|
|
- File processing tool
|
|
- Commands: convert, validate, optimize
|
|
- Categories: input, output, processing
|
|
- Flags: input format, output format
|
|
- Progress indicators
|
|
|
|
## Best Practices
|
|
|
|
### CLI Design
|
|
|
|
1. **Keep it simple**: Start with basic structure, add complexity as needed
|
|
2. **Consistent naming**: Use kebab-case for commands (deploy-app, not deployApp)
|
|
3. **Clear help text**: Every command and flag needs description
|
|
4. **Exit codes**: Use standard codes (0=success, 1=error, 2=usage error)
|
|
|
|
### Flag Patterns
|
|
|
|
1. **Environment variables**: Always provide env var fallback for important flags
|
|
2. **Sensible defaults**: Required flags should be rare
|
|
3. **Short and long forms**: -v/--verbose, -c/--config
|
|
4. **Validation**: Validate flags in Before hook, not in action
|
|
|
|
### Command Organization
|
|
|
|
1. **Categories**: Group related commands (>5 commands = use categories)
|
|
2. **Aliases**: Provide shortcuts for common commands
|
|
3. **Subcommands**: Use for hierarchical operations (db migrate up/down)
|
|
4. **Help text**: Keep concise, provide examples
|
|
|
|
### Performance
|
|
|
|
1. **Fast compilation**: urfave/cli compiles faster than Cobra
|
|
2. **Small binaries**: Minimal dependencies = smaller output
|
|
3. **Startup time**: Use Before hooks for expensive initialization
|
|
4. **Lazy loading**: Don't initialize resources unless command needs them
|
|
|
|
## Common Patterns
|
|
|
|
### Configuration File Loading
|
|
|
|
```go
|
|
app.Before = func(c *cli.Context) error {
|
|
configPath := c.String("config")
|
|
if configPath != "" {
|
|
return loadConfig(configPath)
|
|
}
|
|
return nil
|
|
}
|
|
```
|
|
|
|
### Environment Variable Fallbacks
|
|
|
|
```go
|
|
&cli.StringFlag{
|
|
Name: "token",
|
|
Aliases: []string{"t"},
|
|
Usage: "API token",
|
|
EnvVars: []string{"API_TOKEN"},
|
|
}
|
|
```
|
|
|
|
### Required Flags
|
|
|
|
```go
|
|
&cli.StringFlag{
|
|
Name: "host",
|
|
Required: true,
|
|
Usage: "Database host",
|
|
}
|
|
```
|
|
|
|
### Global State Management
|
|
|
|
```go
|
|
type AppContext struct {
|
|
Config *Config
|
|
DB *sql.DB
|
|
}
|
|
|
|
app.Before = func(c *cli.Context) error {
|
|
ctx := &AppContext{
|
|
Config: loadConfig(),
|
|
}
|
|
c.App.Metadata["ctx"] = ctx
|
|
return nil
|
|
}
|
|
```
|
|
|
|
## Validation
|
|
|
|
Run `scripts/validate-cli.sh` to check:
|
|
- All commands have descriptions
|
|
- All flags have usage text
|
|
- Before/After hooks are properly defined
|
|
- Help text is clear and concise
|
|
- No unused imports
|
|
- Proper error handling
|
|
|
|
## Migration Guides
|
|
|
|
### From Cobra to urfave/cli
|
|
|
|
See `examples/cobra-migration/` for:
|
|
- Command mapping (cobra.Command → cli.Command)
|
|
- Flag conversion (cobra flags → cli flags)
|
|
- Hook equivalents (PreRun → Before)
|
|
- Context differences
|
|
|
|
### From Click (Python) to urfave/cli
|
|
|
|
See `examples/click-migration/` for:
|
|
- Decorator to struct conversion
|
|
- Option to flag mapping
|
|
- Context passing patterns
|
|
|
|
## References
|
|
|
|
- [urfave/cli v2 Documentation](https://cli.urfave.org/v2/)
|
|
- [Docker CLI Source](https://github.com/docker/cli) - Real-world example
|
|
- [Go CLI Best Practices](https://github.com/cli-dev/guide)
|