Go CLI Builder

Overview

This skill provides templates, scripts, and patterns for building production-ready Go command-line tools. It follows established patterns from projects like feedspool-go, feed-to-mastodon, and linkding-to-opml.

The skill generates projects with:

• Cobra for CLI framework
• Viper for configuration management (YAML files with CLI overrides)
• SQLite with a naive migration system
• Logrus for structured logging
• Makefile for common tasks (lint, format, test, build)
• GitHub Actions workflows for CI, tagged releases, and rolling releases
• Strict code formatting with gofumpt and linting with golangci-lint

When to Use This Skill

Use this skill when:

• Creating a new Go CLI tool from scratch
• Adding commands to an existing Go CLI project that follows these patterns
• Needing reference material about Cobra/Viper integration
• Setting up GitHub Actions workflows for multi-platform Go releases

Example user requests:

• "Create a new Go CLI tool called feed-analyzer"
• "Scaffold a Go project for processing log files"
• "Add a new 'export' command to my Go CLI project"
• "Help me set up GitHub Actions for releasing my Go tool"

Quick Start

Creating a New Project

To scaffold a complete new project:

# With database support (default)
python scripts/scaffold_project.py my-cli-tool

# Without database support
python scripts/scaffold_project.py my-cli-tool --no-database

# With template support for generating output
python scripts/scaffold_project.py my-cli-tool --templates

# Combining options
python scripts/scaffold_project.py my-cli-tool --no-database --templates

Project Options:

• Database Support (default: included)

  • Includes SQLite with migrations system
  • Use

    --no-database

    to exclude if you don't need persistent storage
  • Examples: CLI tools that only fetch/transform data, API clients

• Template Support (default: excluded)

  • Includes embedded template system with init command
  • Use

    --templates

    to include for tools that generate formatted output
  • Examples: Markdown generators, OPML exporters, report generators

What gets created:

Base structure (always):

• Entry point (

  main.go

  )
• Root command with Cobra/Viper integration (

  cmd/root.go

  )
• Version command (

  cmd/version.go

  )
• Configuration system (

  internal/config/

  )
• Makefile with standard targets
• GitHub Actions workflows (CI, release, rolling-release)

Optional additions:

• Database layer with migrations (

  internal/database/

  ) - if database enabled
• Template system (

  internal/templates/

  ,

  cmd/init.go

  ) - if templates enabled

Next steps after scaffolding:

1. Update

   go.mod

   with the actual module name
2. Customize the example config file
3. If using database: Define initial schema in

   internal/database/schema.sql

4. Run

   make setup

   to install development tools
5. Run

   go mod tidy

   to download dependencies

Adding Commands to Existing Projects

To add a new command to an existing project:

python scripts/add_command.py fetch

This creates

cmd/fetch.go

with:

• Command boilerplate
• Access to logger and config
• Flag binding examples
• TODO comments for implementation

Project Structure

Generated projects follow this structure:

my-cli-tool/
├── main.go                          # Entry point
├── go.mod                           # Dependencies
├── Makefile                         # Build automation
├── my-cli-tool.yaml.example         # Example configuration
├── cmd/                             # Command definitions
│   ├── root.go                      # Root command + Cobra/Viper setup
│   ├── version.go                   # Version command
│   ├── constants.go                 # Application constants
│   └── [command].go                 # Individual commands
├── internal/
│   ├── config/
│   │   └── config.go                # Configuration struct
│   ├── database/
│   │   ├── database.go              # Connection + initialization
│   │   ├── migrations.go            # Migration system
│   │   └── schema.sql               # Initial schema (embedded)
│   └── templates/                   # Optional: For tools that generate output
│       ├── templates.go             # Embedded template loader
│       └── default.md               # Default template (embedded)
└── .github/workflows/
    ├── ci.yml                       # PR linting and testing
    ├── release.yml                  # Tagged releases
    └── rolling-release.yml          # Main branch rolling releases

Configuration System

Projects use a three-tier configuration hierarchy:

1. Config file (

   my-tool.yaml

   ): Base configuration in YAML
2. Environment variables: Automatic via Viper
3. CLI flags: Override everything

See

references/cobra-viper-integration.md

for detailed patterns on:

• Binding flags to Viper keys
• Adding new configuration options
• Command-specific vs. global configuration
• Environment variable mapping

Database Layer

The generated database layer includes:

1. Initial schema (

   internal/database/schema.sql

   ): Embedded SQL for first-time setup
2. Migration tracking:

   schema_migrations

   table tracks applied versions
3. Migration execution: Automatic on database initialization
4. Idempotent operations: Safe to run multiple times

To add a new migration:

1. Edit

   internal/database/migrations.go

2. Add to the

   getMigrations()

   map with the next version number:

   func getMigrations() map[int]string {
       return map[int]string{
           2: `CREATE TABLE IF NOT EXISTS settings (
               key TEXT PRIMARY KEY,
               value TEXT NOT NULL
           );`,
       }
   }
   

3. Migrations run automatically on next database initialization

Init Command Pattern

For tools that generate output files (markdown, OPML, etc.), the

init

command pattern provides a great user experience by generating both configuration and customizable templates.

When to Use Init Command

Use the init command when your CLI tool:

• Generates formatted output (markdown, HTML, XML, etc.)
• Benefits from user-customizable templates
• Has configuration that users need to set up before first use

Init Command Components

Available templates:

• init.go.template

  - Complete init command implementation

• templates.go.template

  - Template loader with embedded default

• default.md.template

  - Example embedded markdown template

The init command:

1. Creates a YAML configuration file with all options documented
2. Creates a customizable template file (using embedded default)
3. Supports

   --force

   flag to overwrite existing files
4. Supports

   --template-file

   flag to specify custom template filename
5. Provides helpful next steps after initialization

Embedded Templates

Go's

//go:embed

directive allows embedding template files directly in the binary:

package templates

import (
    _ "embed"
)

//go:embed default.md
var defaultTemplate string

func GetDefaultTemplate() (string, error) {
    return defaultTemplate, nil
}

Benefits:

• Single binary distribution (no external template files needed)
• Users can still customize by running

  init

  to get a copy
• Template always available as fallback

Integration with Other Commands

Commands that generate output should support both:

1. Built-in template (default) - uses embedded template
2. Custom template (via

   --template

   flag or config) - loads from file

Example pattern:

templatePath := viper.GetString("command.template")
var generator *Generator
if templatePath != "" {
    generator, err = NewGeneratorFromFile(templatePath)
} else {
    generator, err = NewGenerator() // uses embedded default
}

Example Projects Using This Pattern

• linkding-to-markdown

  - Fetches bookmarks and generates markdown

• mastodon-to-markdown

  - Exports Mastodon posts to markdown

Makefile Targets

All generated projects include these targets:

• make setup

  : Install development tools (gofumpt, golangci-lint)

• make build

  : Build the binary with version information

• make run

  : Build and run the application

• make lint

  : Run golangci-lint

• make format

  : Format code with go fmt and gofumpt

• make test

  : Run tests with race detection

• make clean

  : Remove build artifacts

GitHub Actions Workflows

Three workflows are included:

1. CI (

ci.yml

)

• Triggers: Pull requests to main, manual workflow calls
• Actions: Lint with golangci-lint, test with race detection
• Skip: Commits starting with

  [noci]

2. Release (

release.yml

)

• Triggers: Tags matching

  v*

  (e.g.,

  v1.0.0

  )
• Platforms: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64)
• Outputs: Compressed binaries, checksums, GitHub release
• Docker: Optional (commented out by default)

3. Rolling Release (

rolling-release.yml

)

• Triggers: Pushes to main branch
• Actions: Same as Release but creates a "latest" prerelease
• Purpose: Testing builds from the latest commit

To customize:

• Update Docker Hub username in workflows if using Docker
• Adjust Go version if needed (default: 1.21)
• Modify build matrix to add/remove platforms

Typical Workflow

Starting a New Project

1. Use this skill to scaffold the project
2. Customize the initial schema in

   internal/database/schema.sql

3. Update configuration struct in

   internal/config/config.go

4. Add domain-specific packages in

   internal/

   (see

   references/internal-organization.md

   )
5. Add commands using the add_command script
6. Implement command logic, calling into

   internal/

   packages

Adding a Feature

1. Determine if it needs a new command or extends existing one
2. If new command: use

   add_command.py

   script
3. Add any required configuration to config struct and root flags
4. Implement logic in

   internal/

   packages
5. Update command to call the internal logic
6. Add tests
7. Run

   make format && make lint && make test

Reference Documentation

For detailed patterns and guidelines, refer to:

• references/cobra-viper-integration.md

  : Complete guide to configuration system
  • Flag binding patterns
  • Adding new configuration options
  • Environment variable mapping
  • Best practices

• references/internal-organization.md

  : Internal package structure
  • Package organization principles
  • Dependency rules
  • Common patterns (Option pattern, error wrapping)
  • When to create new packages

• references/template-patterns.md

  : Template-based output generation
  • When and how to use embedded templates
  • Init command implementation
  • Generator/renderer patterns
  • Template functions and testing
  • User workflow and best practices

Templates Available

All templates are in

assets/templates/

:

Core Files:

• main.go

  : Minimal entry point

• go.mod.template

  : Pre-configured dependencies

• Makefile.template

  : Standard build targets

• gitignore.template

  : Go-specific ignores

• config.yaml.example

  : Example configuration

Commands:

• root.go.template

  : Cobra/Viper integration

• version.go.template

  : Version command

• constants.go.template

  : Application constants

• command.go.template

  : New command template

• init.go.template

  : Init command for config/template generation

Internal Packages:

• config.go.template

  : Configuration struct

• database.go.template

  : Database layer

• migrations.go.template

  : Migration system

• schema.sql.template

  : Initial schema

• templates.go.template

  : Embedded template loader

• default.md.template

  : Example embedded template

CI/CD:

• ci.yml.template

  : CI workflow

• release.yml.template

  : Release workflow

• rolling-release.yml.template

  : Rolling release workflow

Best Practices

1. Keep commands thin: Business logic belongs in

   internal/

   packages
2. Use the config struct: Access configuration through

   GetConfig()

   rather than calling Viper directly
3. Wrap errors: Always add context with

   fmt.Errorf("context: %w", err)

4. Format before committing: Run

   make format && make lint

5. Test with race detection:

   go test -race ./...

6. Version your releases: Use semantic versioning tags (v1.0.0, v1.1.0, etc.)
7. Document in .yaml.example: Keep example config updated
8. Handle errors explicitly: Use

   _ = 

   for intentionally ignored errors (e.g.,

   _ = viper.BindPFlag(...)

   )
9. Defer cleanup safely: Use

   defer func() { _ = tx.Rollback() }()

   instead of

   defer tx.Rollback()

   to avoid linter warnings

Common Customizations

After scaffolding, projects typically need:

1. Module name update: Change

   github.com/yourusername/project

   in

   go.mod

   to actual path
2. Additional dependencies: Add with

   go get

   and run

   go mod tidy

3. Custom schema: Define tables in

   internal/database/schema.sql

4. Domain packages: Create packages in

   internal/

   for business logic
5. Command implementations: Fill in the TODOs in command files
6. Docker configuration: Uncomment Docker sections in workflows if needed

Recent Improvements

Linter Compliance (2025-11-11)

• Fixed viper.BindPFlag warnings: All

  viper.BindPFlag()

  calls now use

  _ = 

  prefix to explicitly ignore errors, satisfying the

  errcheck

  linter
• Fixed defer Rollback warnings: Database transaction cleanup now uses

  defer func() { _ = tx.Rollback() }()

  pattern
• Removed static linking: Removed

  -linkmode external -extldflags "-static"

  flags from Makefile to eliminate getaddrinfo warnings when using CGO with SQLite
• Updated templates: All templates now generate linter-clean code out of the box

These changes ensure that projects scaffolded with this skill pass

golangci-lint

without warnings.

Troubleshooting

"gofumpt not found" or "golangci-lint not found"

• Run

  make setup

  to install development tools

"Failed to initialize schema"

• Check database file path and permissions
• Ensure directory exists or is creatable

"Missing migration for version N"

• Migrations must be sequential; add any missing versions

"getaddrinfo warning during build"

• This warning has been resolved in recent versions by removing static linking flags
• If you see this in an older project, remove the static linking lines from your Makefile (see Recent Improvements section)

GitHub Actions failing on cross-compilation

• Ensure CGO is enabled for SQLite
• Linux ARM64 builds require cross-compilation tools (handled in workflow)