termenv

termenv lets Go programs safely use advanced terminal styling without hand-rolling ANSI escape sequences. It inspects the environment the program is running in — checking for a TTY, reading NO_COLOR/CLICOLOR/CLICOLOR_FORCE, and querying the terminal directly — to determine the best available color profile: TrueColor (24-bit RGB), ANSI256, ANSI (16-color), or Ascii (no color).

Once a profile is known, termenv exposes a chainable Style API for composing bold, italic, underline, faint, blink, reverse, and crossed-out text, plus foreground/background coloring from hex values, ANSI codes, or image/color.Color values. Colors outside the detected profile are automatically degraded to the nearest supported color rather than failing or rendering garbage output.

Beyond styling, termenv wraps a broad set of terminal control sequences: cursor positioning and movement, screen/altscreen switching, scrolling regions, window title and cursor-color changes, mouse tracking modes, bracketed paste, OS clipboard access via OSC 52, and desktop notifications. It also detects whether the terminal has a light or dark background by querying the terminal’s actual color and computing luminance.

The library underpins the Charm ecosystem’s terminal UI tools (Bubble Tea, Lip Gloss, Glow) and is widely used anywhere a Go CLI needs to render color safely across arbitrary terminals, CI environments, and SSH sessions.

What You Get

• Automatic color-profile detection (TrueColor, ANSI256, ANSI, Ascii) based on TTY status, NO_COLOR/CLICOLOR env vars, and direct terminal queries
• Automatic color degradation — RGB colors fall back to the nearest 256-color or 16-color match when the terminal doesn’t support truecolor
• A chainable Style API for bold, faint, italic, underline, overline, blink, reverse, and crossed-out text with foreground/background colors
• Foreground/background and dark-vs-light background detection by querying the terminal directly
• Cursor, screen, and scrolling-region control sequences (move, save/restore position, altscreen, clear lines, scrolling regions)
• Session-level terminal control: window title, cursor color, clipboard copy via OSC 52, and desktop notifications
• Go text/template helper functions (Bold, Color, Foreground, Background, etc.) for styling template output directly
• Mouse tracking mode toggles (X10, Hilite, Cell Motion, All Motion) and bracketed-paste mode support

Common Use Cases

• Safe CLI color output - a Go CLI colors its output without crashing or emitting garbled escape codes on terminals, CI logs, or piped output that don’t support color
• Terminal UI theming - a TUI framework (like Bubble Tea) detects the user’s terminal background to choose a light or dark theme automatically
• Cross-platform styling - a tool ships one styling codebase that behaves correctly on Linux, macOS, and Windows terminals with differing ANSI support
• Templated CLI reports - a command generates styled report output by using termenv’s template helper functions inside text/template definitions
• Respecting user color preferences - an application honors NO_COLOR/CLICOLOR_FORCE conventions so users can globally disable or force color output

Under The Hood

Architecture

The package is organized around a small set of focused types: Output (in output.go) is the central object wrapping a writer, an Environ abstraction for environment-variable access, and cached foreground/background color state; Profile (profile.go) represents a detected color capability level and knows how to convert any Color down to what it supports; Color is an interface implemented by ANSIColor, ANSI256Color, and RGBColor, each producing its own ANSI sequence; and Style (style.go) is an immutable, chainable value type that accumulates SGR codes before rendering. Platform-specific terminal querying (termenv_unix.go, termenv_windows.go, termenv_solaris.go, termenv_other.go) is isolated behind Go build tags, so the same public API works across operating systems while OS-specific ioctl/console-mode code stays out of the shared logic. A package-level default Output lets most callers use free functions (termenv.String(), termenv.ColorProfile()) without constructing anything, while NewOutput with functional options (WithProfile, WithTTY, WithUnsafe, WithColorCache) supports explicit control and testing.

Tech Stack

Written in Go (module targets Go 1.17), with a small, purpose-built dependency set: go-colorful for color-space math and nearest-color matching, go-isatty for TTY detection, go-osc52 for clipboard escape sequences, uniseg for Unicode-aware string width calculation, and golang.org/x/sys for low-level terminal syscalls. There’s no web framework, ORM, or database — it’s a low-level terminal I/O library consumed by other CLI/TUI projects. CI runs via GitHub Actions across a matrix of Go versions and operating systems (Ubuntu, macOS, Windows), with a separate coverage workflow reporting to Coveralls.

Code Quality

The package has dedicated test files for its major pieces (color, screen, style, template helpers, and core termenv behavior), run with go test -race and tracked for coverage in CI. Error handling is explicit and typed, using sentinel errors (ErrInvalidColor, ErrStatusReport) rather than swallowing failures. Two golangci-lint configurations (strict and soft) enforce style and catch common Go pitfalls, and exported identifiers carry doc comments throughout, following idiomatic Go naming conventions.

What Makes It Unique

Most terminal-color libraries simply wrap ANSI codes; termenv’s distinguishing behavior is querying the terminal itself — via escape-sequence round-trips — to determine actual foreground/background colors and infer light-vs-dark theme, and to automatically step a requested color down through TrueColor → ANSI256 → ANSI → Ascii until it finds one the terminal actually supports, rather than requiring the caller to detect capabilities themselves. Combined with cursor/screen control, clipboard, and notification sequences in the same package, it functions as a broader terminal I/O toolkit rather than just a color-printing helper, which is why it became the styling engine underneath the Charm ecosystem’s TUI tools.