ckeletin-go

A professional Golang CLI scaffold for building beautiful, robust, and modular command-line applications.

---

Table of Contents

• ckeletin-go
  • Table of Contents
  • Introduction
  • Key Highlights
  • Quick Start
  • Features
  • Getting Started
    • Prerequisites
    • Installation
    • Using the Scaffold
    • Customizing the Module Path
      • Steps to Update the Module Path
  • Configuration
    • Configuration File
    • Environment Variables
    • Command-Line Flags
  • Commands
    • ping Command
      • Usage
      • Flags
      • Examples
  • Development Workflow
    • Taskfile Tasks
    • Pre-Commit Hooks with Lefthook
    • Continuous Integration
  • Customization
    • Changing the Program Name
    • Adding New Commands
    • Modifying Configurations
    • Customizing the UI
  • Tooling Best Practices
  • Contributing
  • License
  • Additional Notes
  • Note

---

Introduction

ckeletin-go is a Golang scaffold project designed to help developers create professional, robust, and beautiful CLI applications. Inspired by the idea of a "skeleton," ckeletin provides a strong foundation on which you can build your own tooling, utilities, and interactive experiences.

This scaffold integrates essential libraries and tools that follow best practices:

• Cobra for building flexible, modular CLI commands.
• Viper for configuration management via files, environment variables, and flags.
• Zerolog for structured, leveled logging.
• Bubble Tea for beautiful, interactive terminal UIs.
• Task automation with Task and pre-commit hooks with Lefthook.
• High test coverage, code quality checks, and CI/CD pipelines using GitHub Actions and CodeQL.

Each command manages its own configuration and defaults, promoting modularity and ease of maintenance.

---

Key Highlights

• Single-Source Binary Name: Update BINARY_NAME in Taskfile.yml, and ldflags handles the rest. No more hunting down references.
• Detailed Coverage Reports: Use task test:coverage-text to see exactly what code paths need testing.
• Seamless Customization: Easily add new commands, reconfigure settings, or integrate Bubble Tea UIs.

---

Quick Start

1. Clone the repository:

   git clone https://github.com/peiman/ckeletin-go.git
   cd ckeletin-go
   

2. Set up development tools:

   task setup
   

   Installs necessary tools and pre-commit hooks.

3. Build and run the sample command:

   task build
   ./ckeletin-go ping
   

   You’ll see “Pong” printed—congratulations, you’re running the scaffold!

---

Features

• Modular Command Structure: Add, remove, or update commands without breaking the rest of the application.
• Structured Logging: Use Zerolog to create efficient, leveled logs. Perfect for debugging, auditing, and production use.
• Bubble Tea UI: Optional, interactive UI for advanced terminal applications.
• Single-Source Configuration: Set defaults in config files, override with env vars, and fine-tune with flags.
• Task Automation: One Taskfile to define all build, test, and lint tasks.
• High Test Coverage & Quality Checks: Ensure a robust codebase that meets production standards.

---

Getting Started

Prerequisites

• Go: 1.20+ recommended.
• Task: Install from taskfile.dev.
• Git: For version control.

Installation

git clone https://github.com/yourusername/ckeletin-go.git
cd ckeletin-go
task setup

Using the Scaffold

1. Update module path in go.mod.

2. Change BINARY_NAME in Taskfile.yml to rename your CLI (e.g., myapp).

3. Build and run to confirm setup:

   task build
   ./myapp ping
   

Customizing the Module Path

When you clone this repository, it's important to update the MODULE_PATH in the go.mod file to reflect your own repository path. This ensures that your module is uniquely identifiable and avoids conflicts with other projects.

Steps to Update the Module Path

1. Open go.mod: Locate the go.mod file in the root of the project.

2. Edit the Module Path: Change the module path to reflect your own repository. For example, if you're using GitHub, it might look like this:

   module github.com/yourusername/your-repo-name
   

   If you're using another version control system, adjust the path accordingly. For example:

   module gitlab.com/yourusername/your-repo-name
   

3. Update References: If the MODULE_PATH is used elsewhere in the project (e.g., in Taskfile.yml for build flags), update those references to match your new module path.

4. Run go mod tidy: After making changes, run go mod tidy to clean up any unnecessary dependencies and ensure the go.mod and go.sum files are up to date.

By following these steps, you can ensure that your version of the project is correctly configured and ready for further development or deployment.

---

Configuration

ckeletin-go uses Viper for flexible configuration:

Configuration File

Default config file: $HOME/.ckeletin-go.yaml (or myapp.yaml if renamed).

Example:

app:
  log_level: "info"
  ping:
    output_message: "Pong"
    output_color: "green"
    ui: false

Environment Variables

Override any config via environment variables:

export APP_LOG_LEVEL="debug"
export APP_PING_OUTPUT_MESSAGE="Hello, World!"
export APP_PING_UI=true

Command-Line Flags

Override at runtime:

./myapp ping --message "Hi there!" --color yellow --ui

---

Commands

ping Command

A sample command showing how to use Cobra, Viper, Zerolog, and Bubble Tea together.

Usage

./myapp ping [flags]

Flags

• --message: Override output message.
• --color: Override output color.
• --ui: Enable Bubble Tea UI.

Examples

./myapp ping
./myapp ping --message "Hello!" --color cyan
./myapp ping --ui

---

Development Workflow

Taskfile Tasks

• task setup: Install tools.
• task format: Format code.
• task lint: Run linters.
• task vuln: Check for vulnerabilities.
• task test: Run tests with coverage.
• task test:coverage-text: Detailed coverage report.
• task check: All checks.
• task build: Build the binary.
• task run: Run the binary.
• task clean: Clean artifacts.

Pre-Commit Hooks with Lefthook

task setup installs hooks that run format, lint, test on commit, ensuring code quality before changes land in the repository.

Continuous Integration

GitHub Actions runs task check on each commit or pull request, maintaining code standards and reliability.

---

Customization

In Short:

• Change BINARY_NAME in Taskfile.yml to rename your CLI.
• Add commands using cobra-cli: cobra-cli add hello.
• Adjust configs in Viper.
• Enhance UI in internal/ui/.

Changing the Program Name

In Taskfile.yml:

vars:
  BINARY_NAME: myapp

Then:

task build
./myapp ping

Adding New Commands

Install Cobra CLI tool:

go install github.com/spf13/cobra-cli@latest

Add a new command:

cobra-cli add hello

This follows Cobra’s best practice: each command in its own file, cleanly separated and easily testable.

Modifying Configurations

Set new defaults in initConfig or in command files. Use viper.BindPFlag() to bind flags. Adjust config files or env vars to match your desired behavior.

Customizing the UI

Explore the internal/ui/ package to modify the Bubble Tea model, colors, and interactivity. Use configs to allow runtime customization of UI elements.

---

Tooling Best Practices

Cobra (repo, docs):

• Keep commands small and focused.
• Each command in its own file promotes clarity and testability.
• Use RunE to return errors gracefully rather than exiting immediately.

Viper (repo, docs):

• Set defaults first, then allow overrides via config files, env vars, and flags.
• Keep configuration keys consistent and descriptive.
• Exploit environment variable binding and automatic environment detection for easy deployment in different environments.

Zerolog (repo, docs):

• Use structured logs for better machine readability.
• Set a global log level and pass context around rather than using global variables directly.
• Keep logs concise and meaningful; leverage fields to add context without cluttering messages.

Bubble Tea (repo, docs):

• Keep the TUI logic isolated in its package or command.
• Make colors, messages, and interactions configurable to adapt to user preferences.

By following these best practices, you ensure that your CLI remains maintainable, testable, and flexible enough to grow with your project's needs.

---

Contributing

1. Fork & create a new branch.
2. Make changes, run task check.
3. Commit with descriptive messages.
4. Open a pull request against main.

---

License

MIT License. See LICENSE.

---

Additional Notes

• task test:coverage-text identifies uncovered code paths for targeted testing improvements.
• Press q or Ctrl-C to exit UI mode.
• Use quotes for special chars in arguments.
• Run go mod tidy to keep dependencies clean.
• Regularly run tests, lint, and format tasks to maintain code quality and style.

---

Note

Keep your environment and tools updated. Embrace the structured approach offered by this scaffold, and enjoy building a professional-grade CLI with ckeletin-go!