Cross-Platform CLI Notes

Updated

September 8, 2026

Cross-Platform CLI Notes

Overview

Go builds everywhere; OS details still leak into CLIs. Isolate differences.

Paths

filepath.Join(a, b)     // not strings + "/"
filepath.Separator
os.UserConfigDir()      // not hardcode ~/.config

Line endings

// accept both when reading tools
// write "\n" unless you must speak CRLF to Windows tools

Signals

Windows: os.Interrupt works for Ctrl-C; SIGTERM semantics differ. Use signal.NotifyContext with available signals; build-tag extra Unix signals.

Shells

  • Avoid cmd /c with user strings
  • PowerShell quoting ≠ bash
  • Document examples for both

Color

// enable only if TTY && NO_COLOR unset && TERM != dumb

Windows: optional virtual terminal processing for ANSI.

Build tags

//go:build windows
// flock_windows.go stub → error "unsupported"

File locking

flock Unix-only; Windows has different APIs—feature-detect or document Unix-only commands.

Rules

Do Don’t
filepath + os helpers Assume /tmp exists as on Linux
CI matrix linux/mac/windows Test only on your laptop OS
Clear “unix only” in help Silent fail on Windows

Try next

  1. GOOS=windows go build your CLI.
  2. Replace hardcoded /tmp with os.TempDir().
  3. Stub flock commands on Windows with message.