{"id":13400494,"url":"https://github.com/muesli/termenv","last_synced_at":"2025-05-14T12:02:34.710Z","repository":{"id":37853310,"uuid":"226467495","full_name":"muesli/termenv","owner":"muesli","description":"Advanced ANSI style \u0026 color support for your terminal applications","archived":false,"fork":false,"pushed_at":"2025-05-05T08:51:28.000Z","size":961,"stargazers_count":1828,"open_issues_count":36,"forks_count":72,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-07T11:41:41.522Z","etag":null,"topics":["ansi","colors","console","golang","styling","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muesli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"muesli"}},"created_at":"2019-12-07T06:35:57.000Z","updated_at":"2025-05-01T18:40:15.000Z","dependencies_parsed_at":"2023-02-16T22:31:37.054Z","dependency_job_id":"63d202b3-ab8d-4611-9b98-fad26c2dc10d","html_url":"https://github.com/muesli/termenv","commit_stats":{"total_commits":214,"total_committers":21,"mean_commits":10.19047619047619,"dds":0.3317757009345794,"last_synced_commit":"81b8f94111d5f517b24f7790075ba73b5f910463"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muesli%2Ftermenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muesli%2Ftermenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muesli%2Ftermenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muesli%2Ftermenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muesli","download_url":"https://codeload.github.com/muesli/termenv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140738,"owners_count":22021218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi","colors","console","golang","styling","terminal","tui"],"created_at":"2024-07-30T19:00:52.614Z","updated_at":"2025-05-14T12:02:34.639Z","avatar_url":"https://github.com/muesli.png","language":"Go","funding_links":["https://github.com/sponsors/muesli"],"categories":["Go","命令行","Build Automation","开源类库","CLI frameworks","Command Line","Open source library","tui"],"sub_categories":["高级控制台用户界面","Advanced Console UIs","命令行","Command Line"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://stuff.charm.sh/termenv.png\" width=\"480\" alt=\"termenv Logo\"\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/muesli/termenv/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/muesli/termenv.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://godoc.org/github.com/muesli/termenv\"\u003e\u003cimg src=\"https://godoc.org/github.com/golang/gddo?status.svg\" alt=\"GoDoc\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/muesli/termenv/actions\"\u003e\u003cimg src=\"https://github.com/muesli/termenv/workflows/build/badge.svg\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://coveralls.io/github/muesli/termenv?branch=master\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/muesli/termenv/badge.svg?branch=master\" alt=\"Coverage Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/muesli/termenv\"\u003e\u003cimg src=\"https://goreportcard.com/badge/muesli/termenv\" alt=\"Go ReportCard\"\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cimg src=\"https://github.com/muesli/termenv/raw/master/examples/hello-world/hello-world.png\" alt=\"Example terminal output\"\u003e\n\u003c/p\u003e\n\n`termenv` lets you safely use advanced styling options on the terminal. It\ngathers information about the terminal environment in terms of its ANSI \u0026 color\nsupport and offers you convenient methods to colorize and style your output,\nwithout you having to deal with all kinds of weird ANSI escape sequences and\ncolor conversions.\n\n## Features\n\n- RGB/TrueColor support\n- Detects the supported color range of your terminal\n- Automatically converts colors to the best matching, available colors\n- Terminal theme (light/dark) detection\n- Chainable syntax\n- Nested styles\n\n## Installation\n\n```bash\ngo get github.com/muesli/termenv\n```\n\n## Usage\n\n```go\noutput := termenv.NewOutput(os.Stdout)\n```\n\n`termenv` queries the terminal's capabilities it is running in, so you can\nsafely use advanced features, like RGB colors or ANSI styles. `output.Profile`\nreturns the supported profile:\n\n- `termenv.Ascii` - no ANSI support detected, ASCII only\n- `termenv.ANSI` - 16 color ANSI support\n- `termenv.ANSI256` - Extended 256 color ANSI support\n- `termenv.TrueColor` - RGB/TrueColor support\n\nAlternatively, you can use `termenv.EnvColorProfile` which evaluates the\nterminal like `ColorProfile`, but also respects the `NO_COLOR` and\n`CLICOLOR_FORCE` environment variables.\n\nYou can also query the terminal for its color scheme, so you know whether your\napp is running in a light- or dark-themed environment:\n\n```go\n// Returns terminal's foreground color\ncolor := output.ForegroundColor()\n\n// Returns terminal's background color\ncolor := output.BackgroundColor()\n\n// Returns whether terminal uses a dark-ish background\ndarkTheme := output.HasDarkBackground()\n```\n\n### Manual Profile Selection\n\nIf you don't want to rely on the automatic detection, you can manually select\nthe profile you want to use:\n\n```go\noutput := termenv.NewOutput(os.Stdout, termenv.WithProfile(termenv.TrueColor))\n```\n\n## Colors\n\n`termenv` supports multiple color profiles: Ascii (black \u0026 white only),\nANSI (16 colors), ANSI Extended (256 colors), and TrueColor (24-bit RGB). Colors\nwill automatically be degraded to the best matching available color in the\ndesired profile:\n\n`TrueColor` =\u003e `ANSI 256 Colors` =\u003e `ANSI 16 Colors` =\u003e `Ascii`\n\n```go\ns := output.String(\"Hello World\")\n\n// Supports hex values\n// Will automatically degrade colors on terminals not supporting RGB\ns.Foreground(output.Color(\"#abcdef\"))\n// but also supports ANSI colors (0-255)\ns.Background(output.Color(\"69\"))\n// ...or the color.Color interface\ns.Foreground(output.FromColor(color.RGBA{255, 128, 0, 255}))\n\n// Combine fore- \u0026 background colors\ns.Foreground(output.Color(\"#ffffff\")).Background(output.Color(\"#0000ff\"))\n\n// Supports the fmt.Stringer interface\nfmt.Println(s)\n```\n\n## Styles\n\nYou can use a chainable syntax to compose your own styles:\n\n```go\ns := output.String(\"foobar\")\n\n// Text styles\ns.Bold()\ns.Faint()\ns.Italic()\ns.CrossOut()\ns.Underline()\ns.Overline()\n\n// Reverse swaps current fore- \u0026 background colors\ns.Reverse()\n\n// Blinking text\ns.Blink()\n\n// Combine multiple options\ns.Bold().Underline()\n```\n\n## Template Helpers\n\n`termenv` provides a set of helper functions to style your Go templates:\n\n```go\n// load template helpers\nf := output.TemplateFuncs()\ntpl := template.New(\"tpl\").Funcs(f)\n\n// apply bold style in a template\nbold := `{{ Bold \"Hello World\" }}`\n\n// examples for colorized templates\ncol := `{{ Color \"#ff0000\" \"#0000ff\" \"Red on Blue\" }}`\nfg := `{{ Foreground \"#ff0000\" \"Red Foreground\" }}`\nbg := `{{ Background \"#0000ff\" \"Blue Background\" }}`\n\n// wrap styles\nwrap := `{{ Bold (Underline \"Hello World\") }}`\n\n// parse and render\ntpl, err = tpl.Parse(bold)\n\nvar buf bytes.Buffer\ntpl.Execute(\u0026buf, nil)\nfmt.Println(\u0026buf)\n```\n\nOther available helper functions are: `Faint`, `Italic`, `CrossOut`,\n`Underline`, `Overline`, `Reverse`, and `Blink`.\n\n## Positioning\n\n```go\n// Move the cursor to a given position\noutput.MoveCursor(row, column)\n\n// Save the cursor position\noutput.SaveCursorPosition()\n\n// Restore a saved cursor position\noutput.RestoreCursorPosition()\n\n// Move the cursor up a given number of lines\noutput.CursorUp(n)\n\n// Move the cursor down a given number of lines\noutput.CursorDown(n)\n\n// Move the cursor up a given number of lines\noutput.CursorForward(n)\n\n// Move the cursor backwards a given number of cells\noutput.CursorBack(n)\n\n// Move the cursor down a given number of lines and place it at the beginning\n// of the line\noutput.CursorNextLine(n)\n\n// Move the cursor up a given number of lines and place it at the beginning of\n// the line\noutput.CursorPrevLine(n)\n```\n\n## Screen\n\n```go\n// Reset the terminal to its default style, removing any active styles\noutput.Reset()\n\n// RestoreScreen restores a previously saved screen state\noutput.RestoreScreen()\n\n// SaveScreen saves the screen state\noutput.SaveScreen()\n\n// Switch to the altscreen. The former view can be restored with ExitAltScreen()\noutput.AltScreen()\n\n// Exit the altscreen and return to the former terminal view\noutput.ExitAltScreen()\n\n// Clear the visible portion of the terminal\noutput.ClearScreen()\n\n// Clear the current line\noutput.ClearLine()\n\n// Clear a given number of lines\noutput.ClearLines(n)\n\n// Set the scrolling region of the terminal\noutput.ChangeScrollingRegion(top, bottom)\n\n// Insert the given number of lines at the top of the scrollable region, pushing\n// lines below down\noutput.InsertLines(n)\n\n// Delete the given number of lines, pulling any lines in the scrollable region\n// below up\noutput.DeleteLines(n)\n```\n\n## Session\n\n```go\n// SetWindowTitle sets the terminal window title\noutput.SetWindowTitle(title)\n\n// SetForegroundColor sets the default foreground color\noutput.SetForegroundColor(color)\n\n// SetBackgroundColor sets the default background color\noutput.SetBackgroundColor(color)\n\n// SetCursorColor sets the cursor color\noutput.SetCursorColor(color)\n\n// Hide the cursor\noutput.HideCursor()\n\n// Show the cursor\noutput.ShowCursor()\n\n// Copy to clipboard\noutput.Copy(message)\n\n// Copy to primary clipboard (X11)\noutput.CopyPrimary(message)\n\n// Trigger notification\noutput.Notify(title, body)\n```\n\n## Mouse\n\n```go\n// Enable X10 mouse mode, only button press events are sent\noutput.EnableMousePress()\n\n// Disable X10 mouse mode\noutput.DisableMousePress()\n\n// Enable Mouse Tracking mode\noutput.EnableMouse()\n\n// Disable Mouse Tracking mode\noutput.DisableMouse()\n\n// Enable Hilite Mouse Tracking mode\noutput.EnableMouseHilite()\n\n// Disable Hilite Mouse Tracking mode\noutput.DisableMouseHilite()\n\n// Enable Cell Motion Mouse Tracking mode\noutput.EnableMouseCellMotion()\n\n// Disable Cell Motion Mouse Tracking mode\noutput.DisableMouseCellMotion()\n\n// Enable All Motion Mouse mode\noutput.EnableMouseAllMotion()\n\n// Disable All Motion Mouse mode\noutput.DisableMouseAllMotion()\n```\n\n## Bracketed Paste\n\n```go\n// Enables bracketed paste mode\ntermenv.EnableBracketedPaste()\n\n// Disables bracketed paste mode\ntermenv.DisableBracketedPaste()\n```\n\n## Terminal Feature Support\n\n### Color Support\n\n- 24-bit (RGB): alacritty, foot, iTerm, kitty, Konsole, st, tmux, vte-based, wezterm, Ghostty, Windows Terminal\n- 8-bit (256): rxvt, screen, xterm, Apple Terminal\n- 4-bit (16): Linux Console\n\n### Control Sequences\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show feature matrix\u003c/summary\u003e\n\n| 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) |\n| ---------------- | :----------------: | :-------------------: | :--------------: | :-----------------: | :-------------------------------: | :-------------------------------: | :-------------: | :------------------: | :-----------------------: |\n| alacritty        |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| foot             |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ✅             |\n| kitty            |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ✅             |\n| Konsole          |         ✅         |          ✅           |        ✅        |         ❌          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| rxvt             |         ❌         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ❌          |            ❌             |\n| urxvt            |         ❌         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| screen           |      ⛔[^mux]      |          ✅           |        ✅        |         ❌          |                ❌                 |                ✅                 |       ❌        |          ❌          |            ❌             |\n| st               |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| tmux             |      ⛔[^mux]      |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| vte-based[^vte]  |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ❌                 |       ✅        |          ✅          |            ❌             |\n| wezterm          |         ✅         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ✅             |\n| xterm            |         ✅         |          ✅           |        ✅        |         ❌          |                ❌                 |                ❌                 |       ✅        |          ✅          |            ❌             |\n| Linux Console    |         ❌         |          ✅           |        ⛔        |         ❌          |                ❌                 |                ❌                 |       ❌        |          ❌          |            ❌             |\n| Apple Terminal   |         ✅         |          ✅           |        ✅        |         ❌          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n| iTerm            |         ✅         |          ✅           |        ✅        |         ❌          |                ❌                 |                ❌                 |       ✅        |          ✅          |            ❌             |\n| Windows cmd      |         ❌         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ❌        |          ❌          |            ❌             |\n| Windows Terminal |         ❌         |          ✅           |        ✅        |         ✅          |                ✅                 |                ✅                 |       ✅        |          ✅          |            ❌             |\n\n[^vte]: This covers all vte-based terminals, including Gnome Terminal, guake, Pantheon Terminal, Terminator, Tilix, XFCE Terminal.\n[^mux]: Unavailable as multiplexers (like tmux or screen) can be connected to multiple terminals (with different color settings) at the same time.\n\nYou can help improve this list! Check out [how to](ansi_compat.md) and open an issue or pull request.\n\n\u003c/details\u003e\n\n### System Commands\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show feature matrix\u003c/summary\u003e\n\n| Terminal         | Copy to Clipboard (OSC52) | Hyperlinks (OSC8) | Notifications (OSC777) |\n| ---------------- | :-----------------------: | :---------------: | :--------------------: |\n| alacritty        |            ✅             |  ✅[^alacritty]   |           ❌           |\n| foot             |            ✅             |        ✅         |           ✅           |\n| kitty            |            ✅             |        ✅         |           ✅           |\n| Konsole          |       ❌[^konsole]        |        ✅         |           ❌           |\n| rxvt             |            ❌             |        ❌         |           ❌           |\n| urxvt            |        ✅[^urxvt]         |        ❌         |           ✅           |\n| screen           |            ✅             |    ❌[^screen]    |           ❌           |\n| st               |            ✅             |        ❌         |           ❌           |\n| tmux             |            ✅             |     ❌[^tmux]     |           ❌           |\n| vte-based[^vte]  |         ❌[^vte]          |        ✅         |           ❌           |\n| wezterm          |            ✅             |        ✅         |           ❌           |\n| xterm            |            ✅             |        ❌         |           ❌           |\n| Linux Console    |            ⛔             |        ⛔         |           ❌           |\n| Apple Terminal   |        ✅[^apple]         |        ❌         |           ❌           |\n| iTerm            |            ✅             |        ✅         |           ❌           |\n| Windows cmd      |            ❌             |        ❌         |           ❌           |\n| Windows Terminal |            ✅             |        ✅         |           ❌           |\n\n[^vte]: This covers all vte-based terminals, including Gnome Terminal, guake, Pantheon Terminal, Terminator, Tilix, XFCE Terminal. OSC52 is not supported, see [issue#2495](https://gitlab.gnome.org/GNOME/vte/-/issues/2495).\n[^urxvt]: Workaround for urxvt not supporting OSC52. See [this](https://unix.stackexchange.com/a/629485) for more information.\n[^konsole]: OSC52 is not supported, for more info see [bug#372116](https://bugs.kde.org/show_bug.cgi?id=372116).\n[^apple]: OSC52 works with a [workaround](https://github.com/roy2220/osc52pty).\n[^tmux]: OSC8 is not supported, for more info see [issue#911](https://github.com/tmux/tmux/issues/911).\n[^screen]: OSC8 is not supported, for more info see [bug#50952](https://savannah.gnu.org/bugs/index.php?50952).\n[^alacritty]: OSC8 is supported since [v0.11.0](https://github.com/alacritty/alacritty/releases/tag/v0.11.0)\n\n\u003c/details\u003e\n\n## Platform Support\n\n`termenv` works on Unix systems (like Linux, macOS, or BSD) and Windows. While\nterminal applications on Unix support ANSI styling out-of-the-box, on Windows\nyou need to enable ANSI processing in your application first:\n\n```go\n    restoreConsole, err := termenv.EnableVirtualTerminalProcessing(termenv.DefaultOutput())\n    if err != nil {\n        panic(err)\n    }\n    defer restoreConsole()\n```\n\nThe above code is safe to include on non-Windows systems or when os.Stdout does\nnot refer to a terminal (e.g. in tests).\n\n## Color Chart\n\n![ANSI color chart](https://github.com/muesli/termenv/raw/master/examples/color-chart/color-chart.png)\n\nYou can find the source code used to create this chart in `termenv`'s examples.\n\n## Related Projects\n\n- [reflow](https://github.com/muesli/reflow) - ANSI-aware text operations\n- [Lip Gloss](https://github.com/charmbracelet/lipgloss) - style definitions for nice terminal layouts 👄\n- [ansi](https://github.com/muesli/ansi) - ANSI sequence helpers\n\n## termenv in the Wild\n\nNeed some inspiration or just want to see how others are using `termenv`? Check\nout these projects:\n\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - a powerful little TUI framework 🏗\n- [Glamour](https://github.com/charmbracelet/glamour) - stylesheet-based markdown rendering for your CLI apps 💇🏻‍♀️\n- [Glow](https://github.com/charmbracelet/glow) - a markdown renderer for the command-line 💅🏻\n- [duf](https://github.com/muesli/duf) - Disk Usage/Free Utility - a better 'df' alternative\n- [gitty](https://github.com/muesli/gitty) - contextual information about your git projects\n- [slides](https://github.com/maaslalani/slides) - terminal-based presentation tool\n\n## Feedback\n\nGot some feedback or suggestions? Please open an issue or drop me a note!\n\n- [Twitter](https://twitter.com/mueslix)\n- [The Fediverse](https://mastodon.social/@fribbledom)\n\n## License\n\n[MIT](https://github.com/muesli/termenv/raw/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuesli%2Ftermenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuesli%2Ftermenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuesli%2Ftermenv/lists"}