go-template

A modern Go template for building CLI and TUI applications with best practices and powerful tools.

Features

• 🎯 Cobra Command Framework - Build powerful CLI applications with ease
• ⚙️ Viper Configuration - Flexible configuration management with TOML, environment variables, and flags
• 📝 Structured Logging - Beautiful logging with Charmbracelet's log package
• 🎨 Charmbracelet Tools - Modern terminal UI capabilities
• 🔧 Environment Support - .env file support for local development
• 📦 Modular Structure - Clean, organized project layout
• 🚀 Automated Releases - GoReleaser integration for multi-platform builds

Installation

From Release

Download the latest release from the releases page.

From Source

git clone https://github.com/theantichris/go-template.git
cd go-template
go build -o go-template

Using Go Install

go install github.com/theantichris/go-template@latest

Quick Start

1. Clone and rename the template:

   git clone https://github.com/theantichris/go-template.git my-app
   cd my-app
   rm -rf .git
   git init

2. Update module name:

   go mod edit -module github.com/yourusername/my-app
   go mod tidy

3. Customize the application:

   • Edit cmd/root.go to change the command name and description
   • Add new commands in the cmd/ directory
   • Update configuration options as needed

Usage

Basic Commands

# Run the application
go run main.go

# Build the application
go build

# Run with debug logging
./go-template --debug

# Use custom config file
./go-template --config /path/to/config.toml

# Display help
./go-template --help

Configuration

The application supports multiple configuration sources with the following precedence:

1. Command-line flags
2. Environment variables
3. Configuration file
4. Default values

Configuration File

Create a .config.toml file in your home directory or current directory:

debug = true
envVar = "some-value"

Environment Variables

Create a .env file for local development:

DEBUG=true
ENV_VAR=some-value

Or set environment variables directly:

export DEBUG=true
export ENV_VAR=some-value

Project Structure

go-template/
├── cmd/
│   └── root.go         # Root command and configuration
├── main.go             # Application entry point
├── go.mod              # Go module dependencies
├── go.sum              # Dependency checksums
├── README.md           # Project documentation
├── CLAUDE.md           # Claude AI assistant guide
├── SPEC.md             # Project specification template
└── LICENSE             # License file

Development

Prerequisites

• Go 1.23.1 or higher
• Git

Building

# Build for current platform
go build

# Build for specific platforms
GOOS=linux GOARCH=amd64 go build -o go-template-linux
GOOS=darwin GOARCH=amd64 go build -o go-template-darwin
GOOS=windows GOARCH=amd64 go build -o go-template.exe

Releasing

This project uses GoReleaser for automated releases.

# Create a new tag
git tag v0.1.0
git push origin v0.1.0

# For local testing (requires GoReleaser installed)
goreleaser release --snapshot --clean

Releases are automatically built and published when a new tag is pushed to GitHub.

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

Code Quality

Pre-commit Hooks

This project uses pre-commit to ensure code quality and consistency. The hooks automatically run before each commit.

Installing Pre-commit and Required Tools

macOS (Homebrew)

# Install all tools via Homebrew
brew install pre-commit golangci-lint markdownlint-cli codespell

Linux (Ubuntu/Debian)

# Install available packages via apt
sudo apt update
sudo apt install pre-commit golang-golangci-lint

# Install Node.js and markdownlint-cli
sudo apt install nodejs npm
sudo npm install -g markdownlint-cli

# Install codespell via pip
sudo apt install python3-pip
pip3 install codespell

Windows

# Using winget for golangci-lint
winget install GolangCI.golangci-lint

# Using pip for Python tools (requires Python installed)
pip install pre-commit codespell

# Using npm for markdownlint-cli (requires Node.js installed)
npm install -g markdownlint-cli

Alternative: Using pip and npm directly (all platforms)

# Install Go linter
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Install Python tools
pip install pre-commit codespell

# Install Node.js tools
npm install -g markdownlint-cli

Setting up pre-commit in your repository

# Install the git hooks
pre-commit install

# Run hooks manually on all files
pre-commit run --all-files

# Run hooks on staged files only
pre-commit run

The following hooks are configured:

• Go: go fmt, go mod tidy, unit tests, and golangci-lint
• Markdown: markdownlint with auto-fix
• Spelling: codespell for checking spelling errors
• General: trailing whitespace, end-of-file fixer, YAML validation, large file detection, merge conflict detection

Manual Linting

# Install Go linter
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run Go linter
golangci-lint run

# Install Markdown linter
brew install markdownlint-cli2

# Run Markdown linter
markdownlint-cli2 "**/*.md"

Dependencies

• Cobra - CLI framework
• Viper - Configuration management
• Charmbracelet Log - Structured logging
• Charmbracelet Fang - Enhanced command execution
• Godotenv - .env file support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Go team for the amazing language and tools
• The Cobra and Viper teams for excellent CLI libraries
• The Charmbracelet team for beautiful terminal tools

Support

For issues, questions, or suggestions, please open an issue.

---

Built with ❤️ using Go