Linux CLI Best Practices

Shared portable guidance for Go engineers operating services on Linux hosts, in CI, and inside containers.

Apply these rules in runbooks, onboarding checklists, and code review when shell workflows touch production paths.

How to Use This List

• Tick items as your team standardizes laptops, CI images, and runbooks.
• Treat Tier A rules as mandatory before production SSH or kubectl access.
• Encode test and log capture habits in CI scripts, not tribal knowledge.
• Revisit when you adopt distroless images, new Go toolchain pins, or GitOps-only deploys.

A - Navigation and environment

• Start commands from the module root with go.mod visible. Wrong working directories produce confusing go test and relative config errors.
• Keep GOPATH/bin and GOROOT/bin on PATH in login and non-login shells. CI and cron jobs miss go install tools otherwise.
• Set GOTOOLCHAIN policy explicitly (auto vs local). Reproducible releases should not surprise-download mid-pipeline.
• Scope GOPRIVATE with direnv, not global .bashrc. Prevents leaking org module settings into personal repos.
• Document architecture when cross-compiling (GOOS, GOARCH, CGO_ENABLED). Ship the ELF binary your server actually runs.

B - Process and signals

• Prefer SIGTERM and graceful shutdown before kill -9. Validates Go Shutdown paths you rely on in systemd and Kubernetes.
• Identify processes with pgrep/ss before restarting services. Avoid killing the wrong binary on shared hosts.
• Set LimitNOFILE (or ulimits) for high-connection Go servers. Default 1024 exhausts under moderate HTTP concurrency.
• Align systemd TimeoutStopSec with in-process shutdown timeouts. Prevents SIGKILL mid-request drain.
• Run long-running commands under tmux on SSH hosts. Dropped connections should not abort go test ./... evidence gathering.

C - Logs and search

• Log to stdout/stderr in containers and supervised services. Platforms ship journal/kubelet logs, not files inside ephemeral disks.
• Use JSON field names stable enough for jq filters. trace_id, level, and msg should not rename per release without notice.
• Search code with ripgrep defaults, not unscoped grep -R. Respect .gitignore to skip vendor/ and build artifacts.
• Capture command output with tee during incidents. Pipes alone lose evidence when scrollback truncates.
• Correlate app logs with journalctl --since windows. Kernel OOM and unit restart lines explain silent Go process exits.

D - Build, test, and profile

• Run go test ./... -count=1 before pushing when CI does the same. Cache hides flakes locally.
• Enable -race in CI for pure Go packages unless documented otherwise. Data races are cheaper to fix pre-prod.
• Store profiles and test logs in artifacts/ with timestamps. Supports postmortems and perf comparisons (pprof -base).
• Bind debug pprof to loopback or port-forward only. Open :6060 on 0.0.0.0 is a known exposure.
• Profile under representative load, not idle servers. Empty CPU profiles waste incident time.

E - systemd and VMs

• Run services as dedicated non-root users. Go does not require root except special bind cases - use proxies or capabilities.
• Keep secrets out of world-readable unit files. Use restricted EnvironmentFile or secret agents.
• Use Restart=on-failure with RestartSec backoff. Crash loops should not hammer databases on startup.
• Version binaries under /opt/<app>/bin with atomic symlink swaps. Supports rollback without editing unit files.
• Test ExecStart manually as the service user before enable. Catches permission and path errors early.

F - Containers and Kubernetes

• Use multi-stage Dockerfiles: compile with Go image, run minimal runtime. Distroless or static images shrink attack surface.
• Add .dockerignore excluding .git, tests, and local artifacts. Image size and cache churn stay predictable.
• Check kubectl describe Events for probe and exit codes. Logs alone miss CrashLoopBackOff root causes.
• Use kubectl logs --previous after crashes. Current container logs may be empty on instant failure.
• Close kubectl port-forward after debugging. Tunnels bypass policy you assume protects admin ports.

G - Productivity and safety

• Allow direnv only after reviewing .envrc diffs. Prevents malicious env injection on shared clones.
• Avoid pasting production credentials into shell history. Prefer scripts reading from vault files or env injected at runtime.
• Pin tool versions in runbooks (kubectl, docker, jq). CLI flag differences break copy-paste during incidents.
• Prefer reproducible scripts over one-off hero commands. Postmortems should replay exact steps.
• Redact PII before sharing log excerpts in tickets. jq extracts are not automatic anonymization.

FAQs

Related

• Linux CLI Skills for Go Engineers - section overview
• Linux CLI Basics - hands-on starting examples
• Build, Test & Profile from the Shell - test and pprof workflows
• systemd & Service Unit Files for Go Binaries - production units
• Containers from the CLI: docker & kubectl - cluster debugging
• Shell Productivity: tmux, fzf & direnv - terminal workflow

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).