Go Scripting

Opinionated guide for small Go CLIs and scripts. Prescribes a narrow, modern stack so you don't re-litigate the same choices on every new tool.

When to use

• Writing a new Go CLI tool, even a one-file script.
• Adding a subcommand to an existing kong-based CLI.
• Deciding which logger, CLI framework, or collection helper to use.
• Adding tables, spinners, or progress output.

When NOT to use

• Go library code — this guide is for CLIs and scripts.
• Go web services — framework-specific guides fit better.
• Shell territory (one grep, one curl): write a shell script.
• Agent-facing command contracts for CLIs inside skills — use skill-cli-authoring first, then return here for Go implementation details.

Stack (at a glance)

See references for the full rationale.

Decision: Go vs shell

Go when you need any of:

• Structured config, JSON parsing, or typed values.
• Multiple subcommands.
• Cross-platform (no bash assumptions).
• Real error handling.
• Tests.

Shell when the whole thing is a sequence of ~5 commands a POSIX sh can run in 30 lines.

Scale tiers

Skip kong below Tier 2 — stdlib flag is enough for a 2-flag script. Skip go-pretty/spinner unless you have row-oriented data or long-running operations.

Non-negotiables

• Use slog. Don't introduce a third-party logger. If you think you need zerolog, read references/logging.md.
• Use kong for new tools. cobra is acceptable only when the codebase is already on it. Mixing routers across one project is worse than either.
• Ship --verbose, --no-color, and respect NO_COLOR. Users expect these flags.
• Exit codes: 0 success, 1 runtime error, 2 usage error.
• Never log.Fatal or os.Exit from library code. Exit from main only.
• Stdlib collections first. slices.Contains before lo.Contains. iter.Seq before lo.Map chains. samber/lo is a last resort.
• Gate all visual output (colors, spinners, tables) on term.IsTerminal && NO_COLOR == "". Piped or CI output must be plain.

Common mistakes

• Reaching for kong on a 50-line script. Use stdlib flag.
• Using fmt.Println as your logger. Use slog.
• panic as error handling. Return errors; exit from main.
• Importing samber/lo for a single Filter. Use stdlib slices or a loop.
• Materializing a slice when iter.Seq suffices. Return the iterator.
• Spinners in CI logs. Detect the terminal and suppress.
• Emitting a table when --json was passed. Respect the flag.
• Keeping timestamps in CLI output. Strip them — the shell prefix is enough.
• Designing the command surface only after coding structs. For skill-local CLIs, settle examples, JSON shape, safety class, and smoke checks with skill-cli-authoring first.

References