CLI tools in Go: stdout is data, stderr is diagnostics, exit codes are the API

Three channels, three meanings

By the end of this section you will know exactly which Go function sends bytes to which stream — and why getting it wrong brings down pipelines at 2 a.m.

Every Unix process is born holding three file descriptors, and the contract over them is older than Go: stdout (fd 1) is the product — the bytes the next program consumes; stderr (fd 2) is commentary — progress, warnings, errors, anything aimed at a human; the exit code is the verdict — the only part a shell can branch on. A pipe connects only stdout to the next process; stderr bypasses the pipe and still reaches the terminal. That is the whole mechanism behind the Hook: anything you print to stdout becomes part of your data format, whether you meant it or not.

Go’s standard library is opinionated in your favor here, if you know where: the log package writes to stderr by default — log.Printf is pipeline-safe out of the box. fmt.Println writes to stdout — it is for results, not narration:

json.NewEncoder(os.Stdout).Encode(report)            // data: the next process eats this
fmt.Fprintf(os.Stderr, "resolved %d services\n", n)  // diagnostics: the operator reads this
log.Printf("retrying registry fetch")                // also stderr — log is safe by default

Exit codes are the second half of the API. The working convention: 0 success, 1 generic failure, 2 usage error — flag itself exits with 2 when parsing fails, so your tool already follows that last one. The BSD sysexits.h table (64–78: EX_USAGE, EX_NOINPUT, EX_TEMPFAIL…) deserves an honest framing: it is a convention from 1980s mail software, not a standard the OS enforces — almost nothing checks those values today. What matters is that you pick a small table, document it in --help, and never change it casually: scripts branch on these numbers. Stay within 0–255 (the shell sees only the low 8 bits), and avoid 126+ — shells use 126 for not-executable, 127 for not-found, and report signal deaths as 128 plus the signal number (ctrl-C kill shows as 130).

Machine mode and human mode

When you inherit an unfamiliar tool, the first question you should ask is: does it behave the same in a pipeline as it does in a demo? A serious tool has two audiences and one binary, so it needs an explicit machine format — --json — and a way to notice which audience is present. The mechanism is a TTY check on the output descriptor: term.IsTerminal(int(os.Stdout.Fd())) (from golang.org/x/term). Interactive terminal: render tables, color, progress spinners. Piped or redirected: drop all of it.

isTTY := term.IsTerminal(int(os.Stdout.Fd()))
useColor := isTTY && os.Getenv("NO_COLOR") == ""   // honor the NO_COLOR convention

The tradeoff worth being precise about: auto-switching decoration (color, spinners, cursor tricks) on TTY detection is universally safe — raw ANSI escapes like \x1b[32m in a CI log or a grep result are pure noise. Auto-switching format is not: a tool that silently emits JSON when piped and a table when not will behave differently in a script than in the demo that preceded the script, and that surprise costs a debugging session. The robust contract: decoration follows the TTY, format follows an explicit flag.

flag versus cobra, honestly

The stdlib flag package covers a one-verb tool completely: typed flags, -h generation, exit-2 on bad input, zero dependencies. Its edges: single-dash long flags only (-verbose, not --verbose — though it accepts two dashes on parse), no subcommands, no shell completions. You can hand-roll subcommands with flag.NewFlagSet per verb and a switch on os.Args[1] — fine for two or three verbs, miserable for twelve.

That is the actual decision line for cobra or urfave/cli: not ergonomics, surface area. A git-style tool — nested subcommands, generated completions for three shells, man pages — is precisely what cobra automates, and paying its dependency tree (cobra pulls pflag and friends — a real cost you now audit forever, in a binary that exists partly to avoid dependency sprawl) is the honest price. A tool with one verb and six flags that imports cobra bought a framework for a function call. Start with flag; migrate when the subcommand switch hurts.

stdin is an input: the filter contract

The tools you already trust — grep, sort, jq — obey the cat-pipe contract: file arguments if given, stdin otherwise. That single convention is what makes them composable, and it costs five lines:

var in io.Reader = os.Stdin
if flag.NArg() > 0 {
	f, err := os.Open(flag.Arg(0))
	if err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
	defer f.Close()
	in = f
}

One honest number for the scanner you will reach for next: bufio.Scanner caps tokens at 64 KiB by default and reports ErrTooLong past it — real-world log lines exceed that; call sc.Buffer with a bigger cap or use bufio.Reader. And when flags arrive from three places at once, the precedence ladder from the configuration lesson applies unchanged: flags beat environment beats config file — explicit and closest to the invocation wins.

Ctrl-C must clean up

A CLI that writes temp files, holds a lock, or half-finishes an upload owes the user a clean exit on interrupt. The modern wiring is signal.NotifyContext plus the defer chain — and one sharp edge: os.Exit does not run deferred calls. A signal handler that calls os.Exit directly skips every defer os.RemoveAll you carefully wrote.

func main() { os.Exit(run()) }   // exactly one os.Exit, at the very top

func run() int {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	tmp, err := os.MkdirTemp("", "release-*")
	if err != nil { fmt.Fprintln(os.Stderr, err); return 1 }
	defer os.RemoveAll(tmp)      // runs on normal return AND on signal-driven return

	if err := build(ctx, tmp); err != nil {
		if ctx.Err() != nil { return 130 }   // interrupted: 128 + SIGINT(2), by convention
		fmt.Fprintln(os.Stderr, err)
		return 1
	}
	return 0
}

The mechanism: the first ctrl-C cancels ctx; your work function notices ctx.Err() and returns; the stack unwinds through every defer; run hands a code to the single os.Exit at the top. Cleanup is just normal control flow — no cleanup registry, no handler spaghetti.

Shipping it

Distribution is where Go CLIs win outright: CGO_ENABLED=0 go build yields one static binary per platform, cross-compiled with nothing but GOOS=linux GOARCH=arm64. Expect 5–15 MB for a typical tool; -ldflags="-s -w" strips symbol tables for roughly a quarter of that back. The two delivery channels differ in audience: go install example.com/tool@v1.4.2 builds from source on the user’s machine — perfect for Go developers, useless for anyone without a toolchain and unpinnable in CI beyond the tag. Released archives (the goreleaser pattern: per-platform tarballs plus checksums on a releases page) serve everyone else and give you reproducible, signable artifacts. Mature tools do both.