Posted inProgramming

From Script to Ship: Building Cross-Platform CLI Tools with Go and Cobra

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

The Distribution Headache in Internal Tooling

We’ve all hit that wall where a script works perfectly on our machine but crashes the moment a teammate tries to run it. I once managed a 12-person team relying on a sprawl of Bash scripts to manage cloud deployments. The second we hired engineers using M1 Macs instead of Intel-based Linux, everything fell apart. Path issues, incompatible sed versions, and missing jq dependencies turned a simple deployment into a two-hour debugging session.

The problem stems from relying on the host environment’s runtime. While Python or Node.js are more stable than Bash, they still demand pre-installed runtimes and messy package managers like virtualenv or node_modules. This overhead kills the adoption of small, internal utilities. If a tool isn’t easy to install, people won’t use it. Mastering the art of the “zero-dependency” binary is crucial for scaling internal operations.

Choosing the Right CLI Stack

Selecting your toolchain isn’t just about syntax; it’s about how your code reaches the end user. Most CLI development falls into three camps, each with its own baggage.

  • Shell Scripts (Bash/Zsh): These are fine for a 10-line quick fix. However, they lack structured error handling and become a maintenance nightmare once they cross the 100-line mark.
  • Scripting Languages (Python/Node.js): You get fantastic libraries, but distribution is a pain. You end up forcing colleagues to manage version managers (like pyenv or nvm) or shipping bloated, 50MB executables that often fail to unpack correctly.
  • Compiled Languages (Go/Rust): These produce a single, static binary. No runtimes. No dependencies. You hand someone a file, they run it, and it works. Go has become the go-to choice for tools like Docker and Kubernetes because it balances developer speed with near-instant execution.

The Go and Cobra Ecosystem: A Reality Check

Using Go and Cobra provides a rock-solid base, but you should weigh the trade-offs before diving in.

The Wins

  • Static Linking: Go bundles everything into one file. It effectively kills the “it works on my machine” excuse.
  • The Cobra Framework: It handles the heavy lifting—nested commands (like git commit -m), flag parsing, and shell autocompletion—straight out of the box.
  • Blazing Performance: Go binaries start in milliseconds. This speed is vital for developers who run CLI commands hundreds of times a day.
  • Easy Cross-Compilation: You can build a Windows .exe and a macOS binary from your Linux terminal with a single command.

The Hurdles

  • Binary Size: A “Hello World” app in Go is roughly 5MB because the runtime is embedded. For context, a feature-heavy tool like Terraform can exceed 80MB.
  • Strict Typing: Unlike Python, Go won’t let you play fast and loose with data. You’ll write more boilerplate up front, which can feel slow during the first hour of prototyping.

Your Professional Toolchain

To build tools that meet production standards, I recommend this specific stack. It mirrors the workflows used by major open-source projects.

  1. Go (1.21+): The compiler.
  2. Cobra-CLI: For scaffolding your command structure.
  3. GoReleaser: The industry standard for automating builds and GitHub releases.
  4. GitHub Actions: To ensure your binaries are built in a clean, consistent CI environment.
# Grab the scaffold tool
go install github.com/spf13/cobra-cli@latest

# Install GoReleaser (Homebrew makes this easy)
brew install goreleaser/tap/goreleaser

Step-by-Step: Building an Automated CLI

Let’s build it-tool, a utility for managing internal configs. We will design the structure, add logic, and automate the ship-to-user pipeline.

1. Scaffolding the Project

Start by initializing your Go module. Use your GitHub repository path so Go can resolve dependencies correctly.

mkdir it-tool && cd it-tool
go mod init github.com/youruser/it-tool
cobra-cli init

This generates main.go and cmd/root.go. Think of root.go as your application’s lobby—it’s where you define global flags like --verbose or --config.

2. Adding Sub-commands

Clean CLI design relies on verbs. Instead of a messy command with 20 flags, use sub-commands. Let’s add a health check.

cobra-cli add health

Inside cmd/health.go, you’ll find an init() function. Use this to define flags that only matter for this specific action.

// cmd/health.go snippet
var healthCmd = &cobra.Command{
    Use:   "health",
    Short: "Check infrastructure status",
    Run: func(cmd *cobra.Command, args []string) {
        isFull, _ := cmd.Flags().GetBool("full")
        if isFull {
            fmt.Println("🔍 Running 60-second deep diagnostic...")
        } else {
            fmt.Println("✅ System is healthy!")
        }
    },
}

func init() {
    rootCmd.AddCommand(healthCmd)
    healthCmd.Flags().BoolP("full", "f", false, "Run a comprehensive check")
}

3. Handling Logic and Errors

Don’t bury your business logic inside the cmd/ folder. Keep your Run functions thin and put the actual work in an internal/ package. This makes your code testable. When things fail, skip the generic panics. Use os.Stderr and clean exit codes so other scripts can catch your errors.

// The professional way to exit
fmt.Fprintf(os.Stderr, "Error: Failed to connect to DB\n")
os.Exit(1)

4. Automating with GoReleaser

Shipping is the hardest part. Manually running GOOS=windows go build for every update is a recipe for disaster. GoReleaser handles the heavy lifting for you.

Initialize your config:

goreleaser init

Edit the .goreleaser.yaml to target common architectures like arm64 (for Apple Silicon) and amd64 (for most servers):

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - windows
      - darwin
    goarch:
      - amd64
      - arm64

5. The CI/CD Finish Line

Create .github/workflows/release.yml. This workflow triggers every time you push a git tag. It compiles the code for all platforms and attaches the binaries to a new GitHub Release in about 30 seconds.

name: release
on:
  push:
    tags: ['v*']
jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-go@v4
        with: { go-version: '1.21' }
      - uses: goreleaser/goreleaser-action@v5
        with:
          distribution: goreleaser
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Ready to ship? Just tag and push:

git tag -a v1.0.0 -m "Initial stable release"
git push origin v1.0.0

Within a minute, your team will have access to a polished release page with binaries for every OS. You’ve just turned a local script into a professional tool that actually scales.

Share:
Tags: