go-cli

1. Project Structure:

Use the following folder structure:

cmd/ (entry points for the CLI)
pkg/ (reusable packages)
internal/ (private packages for the project)
configs/ (configuration files)
docs/ (documentation and examples)
scripts/ (helper scripts for build, lint, test)
test/ (testing utilities and data)

Each command should have its own folder under cmd/, containing a main.go file.

2. Dependencies:

- Use go.mod to manage dependencies.
- Keep dependencies minimal and only include well-maintained, production-ready libraries.

3. CLI Framework:

- Use cobra or urfave/cli for building CLI commands.
- Structure commands hierarchically for clarity and scalability.

4. Configuration:

- Support configuration via:
  - Environment variables.
  - YAML/JSON/TOML configuration files.
  - Command-line flags (with clear precedence rules).
- Use spf13/viper for configuration management.

5. Error Handling:

- Use idiomatic Go error handling with errors.Is and errors.As when appropriate.
- Provide user-friendly error messages for CLI users.
- Log detailed errors for debugging while keeping the CLI output clean.

6. Logging:

- Use log or zerolog for structured logging.
- Log levels should include info, debug, warn, and error.

7. Testing:

- Use testing for unit tests.
- Include end-to-end tests for CLI commands.
- Aim for high test coverage, especially for critical command functionality.

8. Documentation:

- Generate usage documentation automatically (e.g., cobra provides built-in support for this).
- Provide examples for common command usage in the docs/ folder.

9. Performance:

- Optimize for minimal memory usage and fast execution times.
- Avoid unnecessary allocations and keep dependencies lightweight.

10. Code Quality:

- Enforce code quality with the following tools:
- golangci-lint for linting.
- go fmt and goimports for formatting.
- staticcheck for static analysis.
- Follow idiomatic Go naming conventions and avoid abbreviations.

11. Versioning:

- Include a --version flag to display the tool's version.
- Embed build information (e.g., Git commit hash and build date) using ldflags during compilation.

12. Security:

- Validate all user inputs and sanitize outputs.
- Avoid loading untrusted data into memory without validation.
- Keep dependencies up-to-date and audit them regularly.

13. CLI Design:

- Commands should follow this format:
  - <command> <subcommand> [flags]
- Provide clear and concise help text for every command and flag.
- Use meaningful defaults where possible.

14. Cross-Platform:

    - Ensure the tool works seamlessly across Linux, macOS, and Windows.
    - Use os and filepath packages for platform-independent file handling.

15. Build and Distribution:
    - Provide a Makefile with common targets:
      - build: Compile the binary.
      - test: Run tests.
      - lint: Run linters.
      - clean: Clean build artifacts.

- Use goreleaser for packaging and releasing binaries.