termenv
lets you safely use advanced styling options on the terminal. It
gathers information about the terminal environment in terms of its ANSI & color
support and offers you convenient methods to colorize and style your output,
without you having to deal with all kinds of weird ANSI escape sequences and
color conversions.
- RGB/TrueColor support
- Detects the supported color range of your terminal
- Automatically converts colors to the best matching, available colors
- Terminal theme (light/dark) detection
- Chainable syntax
- Nested styles
go get github.com/muesli/termenv
output := termenv.NewOutput(os.Stdout)
termenv
queries the terminal's capabilities it is running in, so you can
safely use advanced features, like RGB colors or ANSI styles. output.Profile
returns the supported profile:
termenv.Ascii
- no ANSI support detected, ASCII onlytermenv.ANSI
- 16 color ANSI supporttermenv.ANSI256
- Extended 256 color ANSI supporttermenv.TrueColor
- RGB/TrueColor support
Alternatively, you can use termenv.EnvColorProfile
which evaluates the
terminal like ColorProfile
, but also respects the NO_COLOR
and
CLICOLOR_FORCE
environment variables.
You can also query the terminal for its color scheme, so you know whether your app is running in a light- or dark-themed environment:
// Returns terminal's foreground color
color := output.ForegroundColor()
// Returns terminal's background color
color := output.BackgroundColor()
// Returns whether terminal uses a dark-ish background
darkTheme := output.HasDarkBackground()
If you don't want to rely on the automatic detection, you can manually select the profile you want to use:
output := termenv.NewOutput(os.Stdout, termenv.WithProfile(termenv.TrueColor))
termenv
supports multiple color profiles: Ascii (black & white only),
ANSI (16 colors), ANSI Extended (256 colors), and TrueColor (24-bit RGB). Colors
will automatically be degraded to the best matching available color in the
desired profile:
TrueColor
=> ANSI 256 Colors
=> ANSI 16 Colors
=> Ascii
s := output.String("Hello World")
// Supports hex values
// Will automatically degrade colors on terminals not supporting RGB
s.Foreground(output.Color("#abcdef"))
// but also supports ANSI colors (0-255)
s.Background(output.Color("69"))
// ...or the color.Color interface
s.Foreground(output.FromColor(color.RGBA{255, 128, 0, 255}))
// Combine fore- & background colors
s.Foreground(output.Color("#ffffff")).Background(output.Color("#0000ff"))
// Supports the fmt.Stringer interface
fmt.Println(s)
You can use a chainable syntax to compose your own styles:
s := output.String("foobar")
// Text styles
s.Bold()
s.Faint()
s.Italic()
s.CrossOut()
s.Underline()
s.Overline()
// Reverse swaps current fore- & background colors
s.Reverse()
// Blinking text
s.Blink()
// Combine multiple options
s.Bold().Underline()
termenv
provides a set of helper functions to style your Go templates:
// load template helpers
f := output.TemplateFuncs()
tpl := template.New("tpl").Funcs(f)
// apply bold style in a template
bold := `{{ Bold "Hello World" }}`
// examples for colorized templates
col := `{{ Color "#ff0000" "#0000ff" "Red on Blue" }}`
fg := `{{ Foreground "#ff0000" "Red Foreground" }}`
bg := `{{ Background "#0000ff" "Blue Background" }}`
// wrap styles
wrap := `{{ Bold (Underline "Hello World") }}`
// parse and render
tpl, err = tpl.Parse(bold)
var buf bytes.Buffer
tpl.Execute(&buf, nil)
fmt.Println(&buf)
Other available helper functions are: Faint
, Italic
, CrossOut
,
Underline
, Overline
, Reverse
, and Blink
.
// Move the cursor to a given position
output.MoveCursor(row, column)
// Save the cursor position
output.SaveCursorPosition()
// Restore a saved cursor position
output.RestoreCursorPosition()
// Move the cursor up a given number of lines
output.CursorUp(n)
// Move the cursor down a given number of lines
output.CursorDown(n)
// Move the cursor up a given number of lines
output.CursorForward(n)
// Move the cursor backwards a given number of cells
output.CursorBack(n)
// Move the cursor down a given number of lines and place it at the beginning
// of the line
output.CursorNextLine(n)
// Move the cursor up a given number of lines and place it at the beginning of
// the line
output.CursorPrevLine(n)
// Reset the terminal to its default style, removing any active styles
output.Reset()
// RestoreScreen restores a previously saved screen state
output.RestoreScreen()
// SaveScreen saves the screen state
output.SaveScreen()
// Switch to the altscreen. The former view can be restored with ExitAltScreen()
output.AltScreen()
// Exit the altscreen and return to the former terminal view
output.ExitAltScreen()
// Clear the visible portion of the terminal
output.ClearScreen()
// Clear the current line
output.ClearLine()
// Clear a given number of lines
output.ClearLines(n)
// Set the scrolling region of the terminal
output.ChangeScrollingRegion(top, bottom)
// Insert the given number of lines at the top of the scrollable region, pushing
// lines below down
output.InsertLines(n)
// Delete the given number of lines, pulling any lines in the scrollable region
// below up
output.DeleteLines(n)
// SetWindowTitle sets the terminal window title
output.SetWindowTitle(title)
// SetForegroundColor sets the default foreground color
output.SetForegroundColor(color)
// SetBackgroundColor sets the default background color
output.SetBackgroundColor(color)
// SetCursorColor sets the cursor color
output.SetCursorColor(color)
// Hide the cursor
output.HideCursor()
// Show the cursor
output.ShowCursor()
// Copy to clipboard
output.Copy(message)
// Copy to primary clipboard (X11)
output.CopyPrimary(message)
// Trigger notification
output.Notify(title, body)
// Enable X10 mouse mode, only button press events are sent
output.EnableMousePress()
// Disable X10 mouse mode
output.DisableMousePress()
// Enable Mouse Tracking mode
output.EnableMouse()
// Disable Mouse Tracking mode
output.DisableMouse()
// Enable Hilite Mouse Tracking mode
output.EnableMouseHilite()
// Disable Hilite Mouse Tracking mode
output.DisableMouseHilite()
// Enable Cell Motion Mouse Tracking mode
output.EnableMouseCellMotion()
// Disable Cell Motion Mouse Tracking mode
output.DisableMouseCellMotion()
// Enable All Motion Mouse mode
output.EnableMouseAllMotion()
// Disable All Motion Mouse mode
output.DisableMouseAllMotion()
// Enables bracketed paste mode
termenv.EnableBracketedPaste()
// Disables bracketed paste mode
termenv.DisableBracketedPaste()
- 24-bit (RGB): alacritty, foot, iTerm, kitty, Konsole, st, tmux, vte-based, wezterm, Ghostty, Windows Terminal
- 8-bit (256): rxvt, screen, xterm, Apple Terminal
- 4-bit (16): Linux Console
Click to show feature matrix
Terminal | Query Color Scheme | Query Cursor Position | Set Window Title | Change Cursor Color | Change Default Foreground Setting | Change Default Background Setting | Bracketed Paste | Extended Mouse (SGR) | Pixels Mouse (SGR-Pixels) |
---|---|---|---|---|---|---|---|---|---|
alacritty | โ | โ | โ | โ | โ | โ | โ | โ | โ |
foot | โ | โ | โ | โ | โ | โ | โ | โ | โ |
kitty | โ | โ | โ | โ | โ | โ | โ | โ | โ |
Konsole | โ | โ | โ | โ | โ | โ | โ | โ | โ |
rxvt | โ | โ | โ | โ | โ | โ | โ | โ | โ |
urxvt | โ | โ | โ | โ | โ | โ | โ | โ | โ |
screen | โ1 | โ | โ | โ | โ | โ | โ | โ | โ |
st | โ | โ | โ | โ | โ | โ | โ | โ | โ |
tmux | โ1 | โ | โ | โ | โ | โ | โ | โ | โ |
vte-based2 | โ | โ | โ | โ | โ | โ | โ | โ | โ |
wezterm | โ | โ | โ | โ | โ | โ | โ | โ | โ |
xterm | โ | โ | โ | โ | โ | โ | โ | โ | โ |
Linux Console | โ | โ | โ | โ | โ | โ | โ | โ | โ |
Apple Terminal | โ | โ | โ | โ | โ | โ | โ | โ | โ |
iTerm | โ | โ | โ | โ | โ | โ | โ | โ | โ |
Windows cmd | โ | โ | โ | โ | โ | โ | โ | โ | โ |
Windows Terminal | โ | โ | โ | โ | โ | โ | โ | โ | โ |
You can help improve this list! Check out how to and open an issue or pull request.
Click to show feature matrix
Terminal | Copy to Clipboard (OSC52) | Hyperlinks (OSC8) | Notifications (OSC777) |
---|---|---|---|
alacritty | โ | โ 3 | โ |
foot | โ | โ | โ |
kitty | โ | โ | โ |
Konsole | โ4 | โ | โ |
rxvt | โ | โ | โ |
urxvt | โ 5 | โ | โ |
screen | โ | โ6 | โ |
st | โ | โ | โ |
tmux | โ | โ7 | โ |
vte-based2 | โ2 | โ | โ |
wezterm | โ | โ | โ |
xterm | โ | โ | โ |
Linux Console | โ | โ | โ |
Apple Terminal | โ 8 | โ | โ |
iTerm | โ | โ | โ |
Windows cmd | โ | โ | โ |
Windows Terminal | โ | โ | โ |
termenv
works on Unix systems (like Linux, macOS, or BSD) and Windows. While
terminal applications on Unix support ANSI styling out-of-the-box, on Windows
you need to enable ANSI processing in your application first:
restoreConsole, err := termenv.EnableVirtualTerminalProcessing(termenv.DefaultOutput())
if err != nil {
panic(err)
}
defer restoreConsole()
The above code is safe to include on non-Windows systems or when os.Stdout does not refer to a terminal (e.g. in tests).
You can find the source code used to create this chart in termenv
's examples.
- reflow - ANSI-aware text operations
- Lip Gloss - style definitions for nice terminal layouts ๐
- ansi - ANSI sequence helpers
Need some inspiration or just want to see how others are using termenv
? Check
out these projects:
- Bubble Tea - a powerful little TUI framework ๐
- Glamour - stylesheet-based markdown rendering for your CLI apps ๐๐ปโโ๏ธ
- Glow - a markdown renderer for the command-line ๐ ๐ป
- duf - Disk Usage/Free Utility - a better 'df' alternative
- gitty - contextual information about your git projects
- slides - terminal-based presentation tool
Got some feedback or suggestions? Please open an issue or drop me a note!
Footnotes
-
Unavailable as multiplexers (like tmux or screen) can be connected to multiple terminals (with different color settings) at the same time. โฉ โฉ2
-
This covers all vte-based terminals, including Gnome Terminal, guake, Pantheon Terminal, Terminator, Tilix, XFCE Terminal. โฉ โฉ2 โฉ3
-
OSC52 is not supported, for more info see bug#372116. โฉ
-
Workaround for urxvt not supporting OSC52. See this for more information. โฉ
-
OSC52 works with a workaround. โฉ