Color Output & User-Friendly Errors

Operators judge CLIs by error clarity: what failed, what to fix next, and whether automation can detect failure class.

Go tools separate stdout (data contract) from stderr (logs, warnings, colored hints).

Libraries like fatih/color and lipgloss add ANSI colors when output is a terminal, and degrade gracefully in CI logs.

Summary

User-friendly errors start with wrapped error values, end with concise stderr messages, and finish with documented os.Exit codes.

Color highlights severity (red error, yellow warning, green success) without polluting JSON or TSV on stdout.

Disable styling when NO_COLOR is set or when stdout/stderr is not a TTY.

Recipe

Quick-reference recipe card - copy-paste ready.

func fail(err error) {
    color.New(color.FgRed).Fprintln(os.Stderr, "error:", err)
    os.Exit(1)
}
 
func main() {
    if err := run(); err != nil {
        fail(err)
    }
}

When to reach for this:

• Operator-facing tools where mistakes need actionable hints.
• Scripts that parse exit codes but show humans colored stderr.
• CLIs that emit JSON on stdout and prose errors on stderr.

Working Example

package main
 
import (
    "errors"
    "fmt"
    "io"
    "os"
 
    "github.com/fatih/color"
)
 
var (
    errConfig = errors.New("config file not found")
    errAuth   = errors.New("authentication failed")
)
 
const (
    exitGeneral = 1
    exitConfig  = 2
    exitAuth    = 3
)
 
func usage(w io.Writer) {
    fmt.Fprintln(w, "usage: mytool --config path.yaml")
}
 
func run(args []string) error {
    if len(args) == 0 {
        usage(os.Stderr)
        return errConfig
    }
    return nil
}
 
func main() {
    color.NoColor = os.Getenv("NO_COLOR") != ""
 
    err := run(os.Args[1:])
    if err == nil {
        color.New(color.FgGreen).Fprintln(os.Stderr, "ok")
        return
    }
 
    switch {
    case errors.Is(err, errConfig):
        color.New(color.FgYellow).Fprintln(os.Stderr, "hint: copy config.example.yaml to config.yaml")
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(exitConfig)
    case errors.Is(err, errAuth):
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(exitAuth)
    default:
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(exitGeneral)
    }
}

What this demonstrates:

• Sentinels (errConfig, errAuth) map to distinct exit codes.
• Yellow hint precedes the red error line for config problems.
• NO_COLOR disables ANSI for accessibility and CI.
• Success still prints to stderr so stdout stays empty for pipes.

Deep Dive

How It Works

• fmt.Errorf("load %s: %w", path, err) wraps errors for errors.Is and errors.As.
• main translates errors to exit codes once; libraries return error without os.Exit.
• Color packages check TTY capability; lipgloss can style whole blocks consistently.
• Structured logs (slog) can mirror stderr messages for long-running CLIs.

Stream Conventions

Exit Code Guidelines

Go Notes

// slog for verbose mode on stderr
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelInfo}))

• Libraries must not call color directly on behalf of callers; return errors upward.
• For cobra, use SilenceErrors: true and print styled errors in main after Execute.
• Test messages with bytes.Buffer and color.NoColor = true for stable assertions.

Gotchas

• Color on stdout - Breaks tool | jq when ANSI leaks into JSON. Fix: color stderr only.
• Printing usage on stdout - Pipes capture help text as data. Fix: flag.Usage and cobra help target stderr.
• Generic "something went wrong" - Operators cannot fix issues. Fix: include which flag, file, or host failed.
• os.Exit in libraries - Skips defers and prevents wrapping. Fix: exit only in main.
• Ignoring NO_COLOR - Accessibility and CI policies expect respect for the env var. Fix: check NO_COLOR and TTY before styling.

Alternatives

FAQs

Related

• CLI Tools Basics - stderr usage and exit codes
• flag Package & POSIX-Style Flags - usage on stderr
• bubbletea Terminal UI & Progress Bars - lipgloss styling
• cobra & urfave/cli Command Trees - SilenceErrors pattern
• CLI Tools Best Practices - testing and UX checklist

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).