golang CLI Template

golang project template for building CLI

Setup

Setup by Command

1. git clone https://github.com/mpppk/cli-template your_awesome_tool
2. Replace all strings cli-template in this repository to your_awesome_tool

Setup on GitHub

Click "Use this template" button on GitHub project page.

Project structure

Application layers

• /cmd includes golang files which implements command and sub commands.
• /domain includes golang files which implements domain model. This package should not depend on other layers.
• /handler includes golang files which implements handlers of http request.
• /usecase includes golang files which implements application use cases. This package is only allowed to depend on domain layer.

Others

• /util includes golang files which implements utilities. All layers can depend on this package. This package should not depend on other packages.
• /scripts includes scripts
• /testdata includes data files for tests. (see https://golang.org/cmd/go/#hdr-Test_packages)

For more detail, see golang-standards/project-layout.

Add new sub command

If you want to create new sub command, Add new go file to /cmd.

For more details, see spf13/cobra.

Task runner

Use Makefile.

Error handling

Use golang.org/x/xerrors.

Documentation

Write godoc(example code) or Example test(example code).

Testing

Don't write test in same package, instead put to package-name_test package.
For example, test of domain/sum.go is in domain_test package, not domain package.
To use unexported variables or functions in test, expose these by export_test.go file.
(ex. /internal/option/root_export_test.go)

For more details, see this article(Japanese).

cmd test

Recommended way is to wrap cobra.Command instance by func (unlike the code generated by cobra add). For example, see cmd/sum_test.go.

with file system

This template depends spf13/afero.
afero.OsFs is used in packages and afero.MemMapFs is used in tests. For example, see cmd/sum_test.go#TestSumWithOutFile

Auto release via Circle CI powered by goreleaser

Create version tag (e.g. v0.0.1) and push to GitHub.
Then goreleaser will release the new version on Circle CI.
(Before push tag, you must provide GitHub token to Circle CI as environment variable)

For more details, see my article (Japanese).

Build & Run Docker image

$ docker build -t cli-template .
...
$ docker run cli-template sum 1 2
3

SaaS integration

Circle CI

This template includes .circleci/config.yml.

AppVeyor

This template includes appveyor.yml.

CodeCov

Makefile includes codecov task which send coverage to CodeCov.
Circle CI also send coverage to CodeCov by its job.

Renovate

This template includes renovate.json.

README template

cli-template

Installation

MacOS

Linux

Download from GitHub Releases

Windows

Download from GitHub Releases

Usage

Write usage of your awesome tool here