adaptive-enforcement-lab/go-cli-architecture

Go CLI Architecture

When to Use This Skill

Go vs Shell Scripts

Start with shell scripts for prototyping. Graduate to Go when you need type safety, testability, or complex orchestration logic.

Use Go when you need:

• Direct Kubernetes API access with type-safe clients
• Complex orchestration logic across multiple resources
• Reusable tooling packaged as container images
• Performance-critical operations (milliseconds matter)
• Long-running controllers or operators

Use shell scripts when you need:

• Simple glue logic between existing tools
• Quick prototypes or one-off operations
• kubectl-based workflows without custom logic
• CI/CD steps that primarily call other CLIs

Implementation

See the full implementation guide in the source documentation.

Key Principles

| Principle | Description | | ----------- | ------------- | | Separation of concerns | Commands handle CLI logic; pkg/ handles business logic | | Testable by default | Interfaces for external dependencies enable fake clients | | Fail fast | Validate configuration and connectivity before operations | | Structured output | JSON output for machine consumption, human-friendly by default | | Graceful degradation | Clear error messages with actionable context |

Building CLIs that operators trust.

Examples

See examples.md for code examples.

References

• Source Documentation
• AEL Build