Go CLI Tools

What it is

A collection of Go-specific command-line tools and patterns for building, testing, managing, and deploying Go applications.

Installation

Go Toolchain

The Go programming language itself is the primary dependency.

• Linux/macOS: Follow the official instructions: https://go.dev/doc/install Typically involves downloading a tarball, extracting it, and adding $GOROOT/bin to your $PATH.

• Windows: Download the MSI installer from: https://go.dev/doc/install

Common Go CLI Tools (often installed via go install)

Many useful Go tools are installed using go install. Ensure your $GOPATH/bin (or $GOBIN) is in your $PATH.

go install github.com/go-delve/delve/cmd/dlv@latest
go install golang.org/x/tools/cmd/goimports@latest
go install github.com/onsi/ginkgo/v2/ginkgo@latest
go install github.com/josharian/impl@latest

Core Concepts

• Modules: The standard way to manage dependencies in Go. Defined by a go.mod file.
• GOPATH: The traditional workspace directory. Modules largely supersede explicit GOPATH management for dependencies, but the $GOPATH/bin directory is still important for go install’d binaries.
• Build Tags: Conditional compilation directives used to include or exclude source files based on build constraints (e.g., //go:build darwin).
• Go Workspace: A directory structure that can contain multiple Go modules. Configured via go.work file.

Commands / Usage

Building and Running

• go build: Compile packages and dependencies.

  # Build the current directory's package into an executable named 'myprogram'
  go build -o myprogram .
  
  # Build all packages in the current directory (useful for libraries)
  go build
  
  # Build for a different OS and architecture
  GOOS=linux GOARCH=amd64 go build -o myprogram-linux-amd64 .
  
  # Build with verbose output
  go build -v .
  
  # Build with race detector enabled
  go build -race .
  

• go run: Compile and run Go programs.

  # Run the main package in the current directory
  go run main.go
  
  # Run a specific file, useful for quick scripts
  go run script.go
  
  # Run with arguments
  go run main.go --config production
  
  # Run a program from a module path without needing to build it first
  go run example.com/my/project/cmd/myapp@latest --version
  

• go install: Compile and install packages and dependencies. Primarily used for installing command-line tools.

  # Install the 'dlv' debugger
  go install github.com/go-delve/delve/cmd/dlv@latest
  
  # Install 'goimports' for formatting
  go install golang.org/x/tools/cmd/goimports@latest
  
  # Install a local package (installs the binary to $GOPATH/bin or $GOBIN)
  go install ./cmd/mycli
  

Dependency Management

• go mod init: Initialize a new module.

  # Initialize a module with the given module path
  go mod init example.com/my/project
  

• go get: Add dependencies to a module.

  # Add the latest version of a package
  go get github.com/gin-gonic/gin
  
  # Add a specific version
  go get github.com/gin-gonic/gin@v1.7.7
  
  # Tidy up dependencies (remove unused, minimal updates)
  go get -u .
  

• go mod tidy: Ensure the go.mod file matches the source code.

  # Remove unused dependencies and add missing ones
  go mod tidy
  

• go list -m: List module information.

  # List the main module path
  go list -m
  
  # List all dependencies and their versions
  go list -m all
  
  # List the version of a specific dependency
  go list -m github.com/gin-gonic/gin
  

• go mod vendor: Create a vendor directory for dependencies.

  # Create or update the vendor directory
  go mod vendor
  

Testing

• go test: Run tests.

  # Run tests in the current directory
  go test
  
  # Run tests and show verbose output
  go test -v
  
  # Run tests and show coverage
  go test -cover
  
  # Run tests that match a specific pattern
  go test -run TestUserLogin
  
  # Run tests with benchmarks enabled
  go test -bench .
  
  # Run tests with race detector
  go test -race
  
  # Run tests for a specific package
  go test ./...
  
  # Run tests and generate a coverage profile
  go test -coverprofile=coverage.out
  

• go test -bench: Run benchmarks.

  # Run all benchmarks in the current package
  go test -bench .
  
  # Run benchmarks matching a pattern
  go test -bench BenchmarkUserLookup
  
  # Run benchmarks with memory allocations enabled
  go test -benchmem .
  

Formatting and Linting

• go fmt: Format Go source files.

  # Format all Go files in the current directory and subdirectories
  go fmt ./...
  

• goimports: Formats Go code and manages imports (adds missing, removes unused).

  # Format and fix imports for all Go files
  goimports -w .
  

• golint: Lints Go source code (deprecated, consider staticcheck or golangci-lint).

  # Lint all Go files
  golint ./...
  

• staticcheck: A powerful static analysis tool.

  # Run staticcheck on the current module
  staticcheck ./...
  

• golangci-lint: A fast Go linters aggregator.

  # Run golangci-lint on the current module
  golangci-lint run
  

Debugging

• dlv (Delve): The debugger for Go.

  # Start Delve debugger for the current program
  dlv debug
  
  # Attach Delve to a running process
  dlv attach <pid>
  
  # Debug a specific binary
  dlv exec ./myprogram
  
  # Set a breakpoint at a function
  (dlv) break main.main
  
  # Set a breakpoint at a file and line number
  (dlv) break main.go:25
  
  # Continue execution
  (dlv) continue
  
  # Step over a line
  (dlv) next
  
  # Step into a function
  (dlv) step
  
  # Print a variable's value
  (dlv) print myVariable
  
  # List source code
  (dlv) list
  

Workspace Management

• go work init: Initialize a workspace.

  # Initialize a workspace in the current directory
  go work init
  

• go work use: Add modules to the workspace.

  # Add a module to the workspace
  go work use ../my-other-module
  
  # Add multiple modules
  go work use ../module1 ../module2
  

• go work sync: Update go.mod files in the workspace to match the workspace definition.

  # Sync workspace dependencies
  go work sync
  

• go work edit: Edit the go.work file.

  # Edit the go.work file using your default editor
  go work edit
  

Other Useful Commands

• go clean: Remove object files and executables.

  # Remove cached files
  go clean -cache
  
  # Remove compiled binaries from the current directory
  go clean -i .
  

• go doc: Show documentation for Go packages.

  # Show documentation for the 'fmt' package
  go doc fmt
  
  # Show documentation for a specific function in a package
  go doc fmt Printf
  
  # Show documentation for a type
  go doc http Response
  

• go generate: Run generator programs.

  # Run all generate directives in the current package
  go generate
  

• go vet: Report suspicious constructs in Go programs.

  # Vet the current package
  go vet .
  
  # Vet all packages in the current module
  go vet ./...
  

Common Patterns

• Build and run a single file script:

  go run my_script.go
  

• Build a cross-compiled binary:

  GOOS=darwin GOARCH=amd64 go build -o myapp-macos .
  GOOS=linux GOARCH=arm64 go build -o myapp-linux-arm64 .
  

• Run tests with coverage for CI:

  go test -race -coverprofile=coverage.txt -covermode=atomic ./...
  

• Format and lint all code in a project:

  goimports -w . && golangci-lint run
  

• Install a tool globally:

  go install github.com/spf13/cobra-cli@latest
  

• Use Delve to debug a running process:

  dlv attach <PID_of_go_process>
  

• Develop multiple local modules together using a workspace:

  # In the root of your workspace
  go work init
  go work use ./module-a
  go work use ../path/to/module-b
  # Now 'go build' etc. will consider both modules
  

• Generate code before building:

  go generate ./... && go build .
  

Gotchas

• go install binary location: Binaries installed via go install go into $GOPATH/bin (or $GOBIN if set). Ensure this directory is in your $PATH to run them directly.
• Module path vs. directory: go run can accept module paths like go run example.com/my/project/cmd/myapp@latest, which downloads and runs the latest version without needing a local checkout.
• go get behavior: go get can sometimes modify go.mod and go.sum in ways you might not expect if not used carefully. go mod tidy is often preferred for maintaining consistency.
• Build tags: Remember that files with build tags are only compiled if the tag matches the build environment (e.g., //go:build ignore will never be compiled).
• go vet limitations: go vet is a basic linter. More advanced checks require tools like staticcheck or golangci-lint.
• go test -cover: The coverage percentage can sometimes be misleading if tests don’t cover critical paths adequately. Always review the generated coverage reports.
• go build vs go run: go build creates an executable file, while go run compiles and runs the code directly without necessarily creating a persistent executable. go run is convenient for scripts but less so for deployment artifacts.