.NET TUIs with Spectre.Console & Terminal.Gui

Markup is a small inline language in square brackets: [bold red]text[/], [green on black], hexadecimal colours such as [#ff9900], rgb(r,g,b) values, decorations such as bold, italic, underline, strikethrough and invert, and a link attribute for hyperlinks on terminals that support them. A [/] closes the most recent open tag, tags nest, and emoji shortcodes such as :rocket: are expanded.

The important point for a tool that prints other people’s data is escaping. A literal bracket is written doubled, and dynamic text must go through Markup.Escape, otherwise a book titled "[Draft] Notes" is parsed as a style tag and throws or silently disappears. The documentation also lists MarkupLineInterpolated for interpolated strings and Markup.Remove to strip tags. The following example prints one line, escaping the data and not the template:

Source: Spectre.Console — Markup reference

A Table is built fluently from columns and rows. The documented options include the border (RoundedBorder() and sixteen-odd other built-in styles, or Border(TableBorder.None)), BorderColor, markup-capable Title and Caption, HideHeaders, ShowRowSeparators, Expand (a table sizes to its content unless told to fill the width) and per-column configuration through a lambda: Width, NoWrap, PadLeft, PadRight and alignment (LeftAligned, Centered, RightAligned). A table can be a cell of another table. Footers are set per column. A Tree has a label, AddNode (which returns the new node so children can be chained), AddNodes, a Guide (TreeGuide.Line is the default, with Ascii, DoubleLine and BoldLine), a Style for the guide lines and Expanded / Collapse() to fold branches. A Panel wraps any renderable in a border with an optional Header, Padding, Expand and a fixed Width.

The first example is the one-shot shelf list view: a table of books followed by a tree of the physical shelves. The two widgets are written one after the other, because the documentation pages consulted show no side-by-side composition.

Source: Spectre.Console — Table and Spectre.Console — Tree

When several regions must be arranged on screen, the documentation offers Layout. A layout is a named region that splits into columns or rows (SplitColumns, SplitRows), sized with Size(n) for a fixed width or height, Ratio(n) for a proportional share and MinimumSize(n); a child is reached by name (layout["Left"]) and filled with Update(renderable), and IsVisible = false hides a region. The documentation page renders a layout once with AnsiConsole.Write(layout) and, for updates, points to the live display. It does not describe a full-screen mode, so treat Layout as a way to compose a snapshot of a dashboard, not as a windowing system: it has no focus, no input and no scrolling. When you need those, use Terminal.Gui.

Source: Spectre.Console — Layout

Three APIs update a region of the terminal in place. They share three documented properties: each has synchronous Start and asynchronous StartAsync methods (with overloads that return a value), none is thread safe, and none may be combined with prompts or with each other.

The sync example below uses all three in the only combination the documentation allows, which is one at a time and in sequence: a status spinner while the program connects, a progress display while it downloads catalogue pages, and a live table while it prints the loans that changed.

Source: Spectre.Console — Status, Progress and Live display; the cancellation wiring uses the Console.CancelKeyPress event described in Console.CancelKeyPress.

The async-patterns guide of Spectre.Console adds that progress can track several concurrent tasks (for example with Task.WhenAll), that a CancellationToken can be passed through the live displays, and that exceptions in the async work should be handled so they do not break the display. The pages consulted for this section do not say how Status, Progress or Live behave when output is redirected or on a continuous-integration log. Check the profile yourself, as described below, and test the redirected case.

Prompts block for an answer. TextPrompt<T> converts the input to T and supports DefaultValue with ShowDefaultValue, AllowEmpty, Validate (a predicate with a message, or a function returning ValidationResult.Success() / ValidationResult.Error(...)), Secret() (asterisks), Secret(char) and Secret(null) (fully hidden), AddChoice with ShowChoices / HideChoices, and styling through PromptStyle, DefaultValueStyle and ChoicesStyle. SelectionPrompt<T> offers arrow-key selection with Title, AddChoices, AddChoiceGroup, UseConverter (display text for an object, returning the object), PageSize (default 10), MoreChoicesText, WrapAround, EnableSearch with SearchPlaceholderText, Mode(SelectionMode.Leaf | Independent) and HighlightStyle. MultiSelectionPrompt<T> is the check-box variant. Both TextPrompt and the selection prompts have Show(IAnsiConsole) and ShowAsync(IAnsiConsole, CancellationToken), and the documentation uses AnsiConsole.Prompt(prompt) as the usual entry point.

The documentation pages for the prompts do not describe what happens when no terminal is attached. The capability table does: Interactive is the property that says whether someone can answer prompts, and it is forced to false on GitHub Actions, Azure Pipelines, GitLab CI, Jenkins, Travis CI, TeamCity, AppVeyor, Bitbucket Pipelines, CircleCI and the other CI systems listed. A command-line tool should therefore read it before it prompts and fall back to a flag or a failure with a usage error, as the rules in TTY, Colour & Interactivity require.

Source: Spectre.Console — TextPrompt, SelectionPrompt and Capabilities reference

At startup Spectre.Console inspects environment variables, the console encoding and the CI environment and stores the result in AnsiConsole.Profile.Capabilities. The documented properties are:

The environment variables the capability reference names are NO_COLOR (disables all colour), COLORTERM (truecolor or 24bit enables 24-bit colour on Unix), TERM (for example xterm-256color) and ConEmuANSI (set to On on Windows under ConEmu when colours do not work). For GitHub Actions the library enables ANSI even though normal detection would not recognise it, and marks Interactive and Links as false. The width the console renders to is resolved in order from an explicitly set Profile.Width, the output stream’s width, Console.BufferWidth and finally a default of 80 columns. The profile and the AnsiConsoleSettings object can override detection, but the pages consulted show no code for doing so, so look at the API reference before relying on a particular property. As elsewhere in this section, NO_COLOR, COLORTERM and similar names are community conventions rather than something a standard guarantees, which is why the details of detection are in Escape Sequences & Terminal Capabilities.

The documentation recommends not writing to the static AnsiConsole from code you want to test. Take an IAnsiConsole parameter, call console.MarkupLine(...) and console.Prompt(...), pass AnsiConsole.Console in production and a TestConsole (from the separate Spectre.Console.Testing package) in a test. A test console collects what was written in its Output and accepts queued keystrokes for prompts through console.Input.PushTextWithEnter(...). The documentation page for testing is short; for snapshot tests of whole screens and for driving a real pseudo-terminal see Testing Terminal Apps & TUIs.

In version 2 the static Application class is obsolete. Application.Create() returns an IApplication instance, app.Init() starts it and returns the same instance so calls can be chained, and app.Run(runnable) starts the event loop and blocks until the runnable stops. Disposing the application stops its input thread and restores the terminal, which is why the documentation uses a using declaration. An instance cannot be reused after it has been disposed: calling Init again throws ObjectDisposedException.

Source: Terminal.Gui — Getting Started

The documented lifecycle pieces are:

The documentation does not say what state the terminal is left in when an unhandled exception escapes the loop, so keep the using scope tight, catch exceptions around app.Run and let Dispose run. The general rule that a TUI must restore the terminal on every exit path is in TUI Architecture & Concepts.

Everything on screen is a View. A view is built with an object initialiser, added with Add(...) to a container (SubViews is the read-only list, SuperView the back reference), and disposed with Dispose(), which also disposes adornments, scroll bars and sub-views. The caller disposes any view it created. The properties that matter most are:

The documentation states the convention: use the -ed event for side effects (button.Accepted += (_, _) => DoTheThing ();) and the -ing event only to inspect or veto (button.Accepting += (_, e) => { if (!CanProceed ()) e.Handled = true; };). Cancellable virtual methods return bool and true cancels. The older Accept event and v1’s Clicked are gone.

Keyboard input is expressed with Key (for example Key.Q.WithCtrl, Key.F1, Key.Enter). A view declares the operations it supports with AddCommand(Command.X, handler) and maps keys to them with KeyBindings.Add(key, command); HotKeyBindings apply regardless of focus. Application-wide defaults, including Command.Quit, are held in Application.DefaultKeyBindings and can be changed in code or in a JSON configuration. The documentation shows rebinding the quit key with Application.DefaultKeyBindings[Command.Quit] = Bind.All (Key.Q.WithCtrl); and the JSON configuration accepts a Quit entry whose All list holds key names such as Esc and Ctrl+Q, but it does not state what the default quit key is, so bind one explicitly if your help text mentions it. A Shortcut displays a command, its help text and its key and can be invoked even when its owning view is not focused.

Terminal.Gui’s layout engine is Pos for X and Y and Dim for Width and Height, both relative to the content area of the container.

Values combine with arithmetic: Dim.Fill () - 10, Pos.Bottom (anotherView) + 5, Dim.Percent (20) - 1. The view’s Frame is a result of layout, so read it after layout has run and do not assign it. A view also has a content area (always at 0,0, sized by GetContentSize() or SetContentSize(...)) and a viewport that is the visible part of it: when the content is larger than the viewport the view scrolls, which in version 2 is built into every View, with scroll bars enabled through ViewportSettings (HasVerticalScrollBar, HasHorizontalScrollBar, HasScrollBars). Adornments sit between the frame and the viewport: margin outermost, then border (which draws the lines and the title), then padding (where scroll bars are drawn). Each has a Thickness.

Source: Terminal.Gui — Layout

The menu system was redesigned in version 2 and is built on Bar and Shortcut. A MenuBar is made of MenuBarItem objects, each holding MenuItem`s (title with an underscore hot key, optional key and action) separated by `Line. MenuBar.Key defaults to F10 and PopoverMenu.Key to Shift+F10. A context menu is a PopoverMenu that must be registered with Application.Popover before it is made visible. A StatusBar snaps to the bottom of its container and shows context-sensitive shortcuts.

Dialogs are runnable views. Dialog is a modal window with buttons along the bottom and a zero-based result index of the pressed button, Dialog<T> returns a custom result type, Prompt<TView, TResult> wraps any view with OK and Cancel buttons (the documentation recommends nullable result types so cancellation can be told apart from a valid result), and OpenDialog, SaveDialog and FileDialog handle files. MessageBox.Query(...) appears in the documentation’s examples, but the pages consulted do not describe its parameters, so look it up in the API reference before using it.

The example builds the shelf tui screen of this section: a menu bar, a search box, a list of books on the left, a details pane on the right and a status bar. It uses only members that appear in the documentation pages cited below and could not be compiled for this page, so the exact event argument types (in particular for ListView and TextField) should be checked in the API reference when you build it.

Source: Terminal.Gui — Menus, Layout, View and Views overview. ListView.SetSource taking an ObservableCollection<T> and the ValueChanged event come from the ListView API reference. The Accepted and Activating events described above replace v1’s selection and click events, but the documentation does not state which of them a ListView raises on Enter, so a search filter or an "open this book" action should be tested on the version you install.

For a loans table, TableView takes an ITableSource through its Table property (built-in sources are DataTableSource, EnumerableTableSource<T>, ListTableSource and TreeTableSource<T>), exposes the selection as Value.SelectedCell, supports FullRowSelect and MultiSelect, raises ValueChanged and Accepted (on double-click or the Accept key) and styles columns through TableStyle and ColumnStyles. The pages consulted do not mention CellActivated or SelectedRow, which were v1 names.

Source: Terminal.Gui — TableView

All UI operations must run on the main thread; modifying views from another thread has undefined behaviour and may crash. From a view, App?.Invoke(...) runs a callback on the main thread; from the application, app.Invoke(...) and app.InvokeAsync(...) do the same, the latter returning a task that completes after the callback ran. After an await in code that started on the main thread, execution comes back to the main thread, so views can be updated directly. Periodic work uses App?.AddTimeout(TimeSpan, callback): return true to keep the timer and false to stop it, remove timers in Dispose to avoid leaks, and keep callbacks fast (the documentation gives about 100 ms as the maximum useful update rate). The shelf sync command inside the TUI therefore looks like this:

Source: Terminal.Gui — Multitasking. The app.Invoke(...) form is named in that page together with App?.Invoke(...); its exact parameter list should be taken from the API reference.

A driver is the layer between the toolkit and the terminal. The documentation names three:

Selection priority is a provided component factory, then the driverName argument to Init, then ForceDriver, then the platform default. ForceDriver can be set in JSON ({ "Application": { "ForceDriver": "ansi" } }), as an argument (app.Init (driverName: DriverRegistry.Names.ANSI)) or on the instance before Init (app.ForceDriver = DriverRegistry.Names.ANSI). Use Application.IsDriverNameValid and Application.GetRegisteredDriverNames() to validate a --driver option of your own tool. Colour defaults to 24-bit with an automatic fall back to 16 colours; ColorCapabilities reports the level (no colour, 16, 256, true colour) from TERM, COLORTERM and related variables, and Force16Colors forces the 16-colour palette. In inline mode (AppModel set to Inline, ANSI driver) the application stays in the primary buffer instead of the alternate screen, which suits a one-shot picker that leaves its answer in the scrollback, and app.PrintAboveAsync(...) prints completed text above the inline region.

What the documentation consulted does not state: which Windows versions are required for the ansi driver (see Windows Console & Processes for what Windows consoles support natively), whether Terminal.Gui supports trimming or Native AOT publishing (see .NET Console Applications for the general rules), and how the toolkit behaves under a multiplexer such as tmux. Test those on your targets.

Version 2.5.0 replaced ConfigurationManager with TuiConfigurationBuilder, built on Microsoft.Extensions.Configuration. Sources are applied from lowest to highest priority: the library defaults, the library’s embedded config.json, the application’s embedded config.json, ~/.tui/config.json and ./.tui/config.json, ~/.tui/{appName}.config.json and ./.tui/{appName}.config.json, the TUI_CONFIG environment variable (inline JSON) and finally RuntimeConfig. ./.tui/ resolves against the current working directory, not the install directory, which matters for a security-conscious tool: a shelf tui started inside a directory someone else controls reads that directory’s configuration. Themes are switched with builder.ThemeManager.SwitchTheme ("Dark"); schemes (colours and text styles such as bold and underline) are applied per view through view.Scheme or globally.

Source: Terminal.Gui — Configuration