go-isatty

go-isatty is a minimal, dependency-light Go package that answers one question reliably across platforms: is this file descriptor attached to an interactive terminal? It underpins color and TTY-detection logic in some of the Go ecosystem’s most widely used CLI tools, letting them decide when to emit ANSI colors, progress bars, or interactive prompts versus falling back to plain output for pipes, redirects, and CI logs.

The implementation is split by build tags into platform-specific files — BSD/Darwin using ioctl TIOCGETA via golang.org/x/sys/unix, Windows using GetConsoleMode plus an NtQueryObject-based Cygwin/MSYS2 pty name check, Plan9, Solaris, and a catch-all stub for sandboxed runtimes like js/wasm and App Engine. Each file compiles only for its target OS via Go build constraints, so the public IsTerminal and IsCygwinTerminal functions stay a small, stable two-function API regardless of platform.

What You Get

• A single IsTerminal(fd uintptr) bool function that works uniformly across Linux, BSD/Darwin, Windows, Plan9, Solaris, and sandboxed runtimes
• IsCygwinTerminal(fd uintptr) bool for detecting Cygwin and MSYS2 pseudo-terminals on Windows, where the native console API alone can’t tell
• Platform-specific implementations selected automatically at compile time via Go build tags, with no runtime detection overhead
• A dependency footprint limited to golang.org/x/sys, keeping it safe to vendor into CLI tools without dragging in a larger toolkit

Common Use Cases

• CLI tools deciding whether to emit ANSI color codes or plain text depending on whether stdout is a terminal or a redirected file/pipe
• Interactive prompts and spinners that should only render when attached to a real terminal, not when running in CI or as part of a script
• Logging libraries that switch between colorized human-readable output and structured plain output based on terminal detection
• Cross-platform Go tools that need consistent terminal detection on Windows including Cygwin/MSYS2 environments, not just native Windows consoles

Under The Hood

Architecture

go-isatty is a flat, single-package library with no internal layering — its entire public surface is two functions, IsTerminal and IsCygwinTerminal, declared once conceptually and implemented separately per platform via Go build constraints (isatty_bsd.go, isatty_windows.go, isatty_others.go, and platform equivalents for Linux, Plan9, and Solaris). Each file satisfies the same signature so the compiler selects exactly one implementation per build target, meaning there’s no runtime branching, interface indirection, or dependency injection — callers pass a raw uintptr file descriptor directly to a syscall wrapper. If the core two-function signature ever changed, every downstream consumer that gates terminal-aware behavior — colorized CLIs, prompt libraries, loggers — would need updating, which is why the API has stayed stable for over a decade.

Tech Stack

The stack is intentionally minimal: Go 1.20+ as declared in go.mod, with a single external dependency, golang.org/x/sys v0.28.0, used only on BSD/Darwin targets to call unix.IoctlGetTermios. The Windows implementation bypasses any external package and calls kernel32.dll (GetConsoleMode, GetFileInformationByHandleEx, GetFileType) and ntdll.dll (NtQueryObject) directly via syscall.NewLazyDLL, avoiding cgo entirely. There’s no build tooling beyond the standard go build/go test toolchain and a go.test.sh coverage script; the library has no deployment target of its own since it’s consumed as a vendored dependency inside other Go binaries.

Code Quality

Test coverage is present but shallow — the non-Windows and Windows test files run largely smoke-level checks (one test’s own comment notes it verifies non-panic behavior rather than a specific return value, since terminal state depends on how the test runner is invoked). Error handling favors returning a plain bool over propagating errors, which fits a boolean-predicate API. What compensates for the thin unit assertions is a genuinely rigorous CI setup: GitHub Actions runs the full suite with the race detector across Linux, macOS, and Windows runners on multiple Go versions each, uploading coverage to Codecov on every push and pull request. Naming is idiomatic Go throughout, and there’s no dedicated linter configuration, but the surface area is small enough that this is a low-risk gap.

What Makes It Unique

go-isatty doesn’t innovate technically — TTY detection via ioctl or GetConsoleMode is a well-understood, decades-old technique — but its practical contribution is being the de facto standard implementation the Go ecosystem converged on for exactly this problem, correctly handling an edge case most naive implementations miss: Cygwin and MSYS2 terminals on Windows report as pipes rather than consoles, so a plain GetConsoleMode check returns false even inside an interactive Cygwin shell. Its named-pipe pattern inspection to recover that information, plus a documented fallback to the undocumented NtQueryObject API for older Windows versions, reflects accumulated platform knowledge rather than a novel architecture.