scaffold-cli

Context

Project {{project_name}} is a CLI application using {{stack}}. You will create a new command "{{input.name}}".

Read AGENTS.md for conventions. Read existing commands to understand patterns.

Instructions

1. Analyze existing command patterns

   • Read existing command files
   • Identify: argument parsing library (cobra, clap, click, commander, argparse, etc.)
   • Identify: command registration pattern (subcommands, router, etc.)
   • Identify: output formatting (table, JSON, plain text, colored)
   • Note error handling patterns (exit codes, stderr vs stdout)

2. Create command file

   • Path: according to project convention
     • Go (cobra): cmd/{{input.name}}.go or internal/cmd/{{input.name}}.go
     • Rust (clap): src/commands/{{input.name}}.rs
     • Python (click): src/commands/{{input.name}}.py
     • Node (commander): src/commands/{{input.name}}.ts
   • Implement:
     • Command definition with name, description, aliases
     • Argument/flag parsing with validation
     • Help text with usage examples
     • Handler function with business logic

3. Create argument/flag definitions

   • Define all required and optional flags
   • Set proper types (string, bool, int, etc.)
   • Add short aliases where appropriate (-o for --output)
   • Set sensible defaults
   • Add validation for required args

4. Register command

   • Add to root command / command registry
   • Ensure it shows up in --help output
   • Set up proper parent-child relationship for subcommands

5. Implement handler logic

   • Separate business logic from CLI plumbing
   • Use project's existing service/logic layer
   • Handle errors gracefully with helpful messages
   • Respect --quiet/--verbose flags if they exist
   • Use proper exit codes (0 = success, 1 = error, 2 = usage error)

6. Create tests

   • Path: according to convention
   • Test cases:
     • Command executes successfully with valid args
     • Help text is correct
     • Required args validation works
     • Flag parsing works correctly
     • Error cases return proper exit codes
     • Output format is correct