Golang CLI Boilerplate 🛠️

This is a versatile and easy-to-use template for building a robust Golang CLI with Cobra and Viper. It comes with built-in AWS adapters via Golang SDK v2 and handy utilities.

Getting Started 🚦

Use this repository as a GitHub Template to create your own CLI:

Clone this repository and start adding your command and flag definitions. Utilize pre-installed AWS adapters and included utilities to kickstart your CLI development.
This template's CLI is called golang-cli-boilerplate. You can rename it by changing the name using your favourite tool, or just using our IDE with a simple Ctrl+Shift+R and replace all the occurrences of golang-cli-boilerplate with your new name (or including the org/golang-cli-boilerplate) if applicable.
Configure PreCommit hooks by running task pre-commit-init. This will install the pre-commit hooks in your local repository.
Update the LICENSE.md file with your own license.
Verify that everything is working as expected:

# If you want to use the MakeFile included.
make lint

# Or, if you're using Taskfile
task go-lint

After this step, you should be able to run your CLI:

# TaskFile wraps the binary in a task, so you can run it like this:
task cli-run -- help

# Or directly, just ensure you're building the binary first
go build -o <my-cli> main.go

# Or, with TaskFile
task cli-build

NOTE: This template includes a MakeFile and a TaskFile with the necessary (best practices) configuration to build and lint your CLI. Both tools include the same capability, so you can choose the one you prefer.

🔧 Release your CLI

The release of your CLI is done using GoReleaser. For MacOs, you can use Homebrew. This template already includes a .goreleaser.yml file with the necessary (best practices) configuration to release your CLI. In addition, a GitHub Action is included to automate the release process.

  goreleaser:
    if: needs.release-please.outputs.releases_created == 'true'
    permissions:
      contents: write
    needs:
      - release-please
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v3
        with:
          fetch-depth: 0
      - name: Set up Go
        uses: actions/setup-go@4d34df0c2316fe8122ab82dc22947d607c0c91f9 # v4
        with:
          go-version: '1.20'
      - name: Download Syft
        uses: anchore/sbom-action/download-syft@422cb34a0f8b599678c41b21163ea6088edb2624 # v0.14.1
      - name: Run GoReleaser
        uses: goreleaser/goreleaser-action@f82d6c1c344bcacabba2c841718984797f664a6b # v4
        with:
          distribution: goreleaser
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{secrets.GH_HOMEBREW_TOKEN}}

NOTE: In order to use the GitHub Action, you need to create a GH_HOMEBREW_TOKEN secret in your repository with enough permissions to read and write into the tap repository.

📚 Documentation

Documenting your CLI is relevant. This repository includes a docs folder with a template for the documentation of your CLI. You can use it as a starting point for your own documentation. It includes:

📃 README.md with a standard structure for a CLI repository.
📃 INSTALLATION.md file with the installation instructions for your CLI.
📃 CONTRIBUTING.md file with the instructions for contributing to your CLI.
📃 CODE_OF_CONDUCT.md file with the code of conduct for your CLI.
📃 LICENSE.md file with the license for your CLI.

tree -L 3  docs/
docs/
├── about_docs.md
└── templates
    ├── CODE_OF_CONDUCT.md
    ├── CONTRIBUTING.md
    ├── INSTALLATION.md
    ├── LICENSE
    └── README.md

NOTE: It's recommended to move these files accordingly, nevertheless it's strongly encouraged to keep a concise documentation structure, keeping the README.md simple, concise, and store the more detailed documentation in the docs folder. For more details about the document templates, see this.

Features 🧩

Out-of-the-box environment variable management 🌳
Auto-scan host environment variables for AWS and Terraform credentials 📄
Import env vars from dotfiles (.env) 📄
Leverages built-in AWS adapters (Golang SDK v2)
Ready-to-use utilities for common tasks 🧰. See the pkg folder for more details.
Built-in Docker support 🐳
Out-of-the-box GitHub Actions workflows for CI/CD 🚀
Built-in PreCommit hooks for linting and formatting 🧹
Out-of-the-box support for output data in yaml, json or tables🤖

Safely share the `cliClient` to `subCommands` 🤝

On each subcommand (at the parent level, which means, those that are in the top of your pkg), ensure you're implementing the GetClient function:

func GetClient(cmd *cobra.Command) *cli.Client {
	ctx := cmd.Context().Value(cliutils.GetCtxKey())
	if ctx == nil {
		log.Fatal("Unable to get the client context.")
	}
	client, ok := ctx.(*cli.Client)
	if !ok {
		log.Fatal("Unable to assert client.")
	}
	return client
}

Adapters 🧩

Adapters are known also as clients. They can plug into the cliClient and provide additional functionality. This template includes a subcommand called aws-ecs in the cmd/example package. It's a subcommand that use the aws adapter to read the ECS clusters in your account. It's a good example of how to use the cliClient and the aws adapter. See here

Tooling 🧑‍🔧

This template is equipped with an array of tools to maintain a high standard of code quality and accelerate the development process:

Precommit framework for managing and maintaining multi-language pre-commit hooks
Taskfile is a simpler way to automate tasks
Makefile for managing build workflow
GolangCI-linter for consolidated linting to improve code quality
GoReleaser for easy binary release management
Docker for containerization
ShellCheck for shell script linting
Release please for automated releases

NOTE: For pre-commit, ensure you're running task pre-commmit-init to add the pre-configured hooks into your git hooks. This will ensure that the code is linted and formatted before committing it. Also, there are other linters included (yaml, docker, shell, md, etc.).

Roadmap 🗓️

Add a built-in GitHub adapter.
Add a CLI for quickly bootstrapping a new CLI
Add an OpenAI adapter for generating CLI documentation and/or other purposes.

Contributing

Please read our contributing guide. All issues, pull requests and GitHub stars are welcome! Happy coding! 💻

Community

Find me in:

📧 Email
🧳 Linkedin

gchiesa/go-cli-example