Customization & Output
Repl’s output pipeline is fully composable. The same command graph produces plain text for a CI log, syntax-highlighted JSON for a terminal, and Spectre.Console tables for a rich interactive session — all without touching handler code.
Output formats
Section titled “Output formats”Every command supports output format flags out of the box:
| Flag | Format |
|---|---|
| (none) | human — plain text / table |
--output:format=json (or --json) | JSON |
--output:format=xml | XML |
--output:format=yaml | YAML |
--output:format=markdown | Markdown table |
--output:format=spectre | Spectre.Console rendering |
Format selection order
Section titled “Format selection order”--output:formatflag on the command lineReplOptions.Output.DefaultFormat(configured at startup)human(built-in default)
Set the default format
Section titled “Set the default format”app.Options(o =>{ o.Output.DefaultFormat = "json"; // all commands default to JSON});Feedback stays out of machine output
Section titled “Feedback stays out of machine output”When the output is meant for a program, standard output carries the payload alone. Progress, status lines, notices and prompt labels go to standard error when either of these holds:
- the command renders a machine-readable format:
--json,--xml,--yaml, or a custom transformer whoseIsMachineReadableistrue; - or standard output is redirected, as in
myapp sync > report.txtormyapp sync | jq.
Otherwise feedback stays on standard output, beside the result. Framework diagnostics, such as a refused --output format, always go to standard error.
myapp sync --json > result.json # result.json holds the JSON; progress shows in the terminalJSON values render as data
Section titled “JSON values render as data”A handler can return a JsonNode or a JsonElement. With --json it is written as is; in human and spectre output, an object renders as key/value lines and an array of objects as a table, like any other result.
Paged result rendering
Section titled “Paged result rendering”When a command returns a ReplPage<T> or an IReplPageSource<T>, the output format determines how the page is rendered:
| Format | Rendering |
|---|---|
human / spectre (interactive TTY) | Table + integrated pager; continues fetching source pages as the user scrolls |
human / spectre (redirected stdout) | Table for the first source page; pager suppressed; nextCursor hint printed |
json / xml / yaml / markdown | Explicit page envelope: { "$type": "page", "items": [...], "pageInfo": { ... } } |
| MCP structured content | { "$type": "page", ... } in StructuredContent; text fallback via PagedResultTextMode |
The pager activates only for human and spectre on an interactive TTY. Redirected output and machine formats always receive the raw first page — use --result:cursor to advance.
See Result-Flow Paging for the full source paging model, CLI options, and MCP surface.
ANSI capability levels
Section titled “ANSI capability levels”Repl classifies the terminal’s color capability and chooses rendering accordingly. Capability tiers (informational):
| Detected tier | Rendering |
|---|---|
| No ANSI | Plain text, no escape sequences |
| Basic | 16 ANSI colors |
| Extended | 256 colors |
| TrueColor | 24-bit color |
Two questions are answered separately: may the output be colored, and may it drive the terminal (clear the screen, move the cursor for arrow-key menus, the full-screen pager or Spectre’s live displays, write shell-integration marks or advanced progress).
Checked in this order; the first row that decides wins:
| # | Check | Result |
|---|---|---|
| 1 | A hosted session states its ANSI support (for example TerminalSessionOverrides.AnsiSupported) | that answer |
| 2 | OutputOptions.AnsiMode is Always or Never | on or off |
| 3 | The host reports no ANSI support (CapabilityOptions.SupportsAnsi is false) | off |
| 4 | FORCE_COLOR has any non-empty value, including 0 (the rule .NET 11 applies, in its console logger and in System.Console on Linux) | on |
| 5 | NO_COLOR has a non-blank value (no-color.org) | off |
| 6 | CLICOLOR_FORCE=1 | on |
| 7 | TERM=dumb | off |
| 8 | The stream is redirected to a file or a pipe | off, otherwise on |
Terminal control
Section titled “Terminal control”Color must be on, and in addition one of these must hold:
- a hosted session stated its ANSI support;
- the application set
AnsiMode.Always; - the stream reaches a terminal, and neither
NO_COLORnorTERM=dumb(withoutCLICOLOR_FORCE=1) is set.
Independently of the color table, a hosted client that advertises ANSI through capability flags may be driven too, unless AnsiMode.Never, NO_COLOR or TERM=dumb says otherwise; see Detecting Spectre capability.
So FORCE_COLOR or CLICOLOR_FORCE=1 colors a file or a pipe without writing control sequences into it, and NO_COLOR keeps them off even where FORCE_COLOR turned color on. ITerminalInfo.IsAnsiSupported reports this answer, and ITerminalInfo.Palette the color one. Some features add their own conditions: screen clearing and progress need the stream they write to reach a terminal (a session’s writer always does), and shell-integration marks are never written to redirected local output, even under AnsiMode.Always.
Override
Section titled “Override”Override programmatically using AnsiMode:
app.Options(o =>{ o.Output.AnsiMode = AnsiMode.Always; // color on whatever the environment says; see Terminal control for its limits // or: Auto (default — let detection decide), Never (force off)});JSON colorization
Section titled “JSON colorization”In interactive mode with ANSI support, --json output is automatically syntax-highlighted (keys in one color, strings in another, numbers in a third). No configuration required. Highlighting follows the color rule: redirected output stays plain unless color is forced.
Render width
Section titled “Render width”Repl uses the terminal width for table column sizing, word wrap, and layout decisions.
Resolution order:
OutputOptions.PreferredWidth(explicit override)COLUMNSenvironment variable- Detected console window width
- Telnet NAWS / DTTERM resize for hosted sessions
OutputOptions.FallbackWidth(default:120)
app.Configure<OutputOptions>(o =>{ o.PreferredWidth = 160; o.FallbackWidth = 80;});Custom output transformers
Section titled “Custom output transformers”Register a transformer for a new format name:
app.Options(o =>{ o.Output.AddTransformer("csv", new CsvOutputTransformer()); o.Output.AddAlias("spreadsheet", "csv"); // both --output:format=csv and --output:format=spreadsheet work});IOutputTransformer receives the handler’s return value and returns a formatted string:
public class CsvOutputTransformer : IOutputTransformer{ public string Name => "csv";
public ValueTask<string> TransformAsync(object? value, CancellationToken ct) { var csv = value is IEnumerable<object> rows ? ToCsv(rows) : value?.ToString() ?? ""; return ValueTask.FromResult(csv); }}Suppressing the banner
Section titled “Suppressing the banner”The startup banner (shown in interactive mode) can be suppressed:
myapp --no-logoOr globally:
app.Options(o =>{ o.Output.BannerEnabled = false; // or: o.Output.BannerFormats = ["human"] — show only in human format (default)});Spectre.Console integration
Section titled “Spectre.Console integration”Add Repl.Spectre and register:
app.UseSpectreConsole(); // enables rich prompts and renderables in one callReturning renderables
Section titled “Returning renderables”Return any IRenderable from a handler — Spectre renders it automatically:
app.Map("contacts table", (IContactStore store) =>{ var table = new Table() .BorderStyle(Style.Parse("grey")) .AddColumn("[bold]Id[/]") .AddColumn("[bold]Name[/]") .AddColumn("[bold]Email[/]");
foreach (var c in store.All()) table.AddRow(c.Id.ToString(), c.Name, c.Email);
return table;});Color palette and style
Section titled “Color palette and style”Use Spectre.Console’s full Markup and Style API anywhere an IRenderable is expected:
return new Markup("[green bold]Success![/] Contact added.");return new Panel(new Markup(content)) .BorderStyle(Style.Parse("blue")) .Header("[bold]Summary[/]");Available renderables
Section titled “Available renderables”| Type | Description |
|---|---|
Table | Grid with borders, alignment, and markup |
Panel | Box with optional header and border |
Tree | Hierarchical tree view |
BarChart | Horizontal bar chart |
BreakdownChart | Proportion chart |
Calendar | Monthly calendar with highlighted dates |
JsonText | Syntax-highlighted JSON |
FigletText | Large ASCII art text |
TextPath | Breadcrumb path rendering |
Markup | Inline styled text |
Grid / Columns | Free-form layout |
Rule | Horizontal divider |
Progress / Status | Live progress widgets |
Detecting Spectre capability
Section titled “Detecting Spectre capability”Spectre rendering follows the same ANSI detection as the rest of the framework — no configuration required:
- Colors follow the color rule; when it says no, the color system degrades to
NoColorsand output stays plain text. A hosted client that advertises ANSI only through capability flags (terminal identity, control messages) gets Spectre styling even when the server console’s own state says no;AnsiMode.Never,NO_COLORandTERM=dumbstill win over that fallback. - Live displays and prompts: Spectre animates
ProgressandStatusonly when its console is interactive and ANSI. A console that is colored but may not drive the terminal (color forced onto redirected output, or onto a terminal underNO_COLORorTERM=dumb) is not interactive: live displays print static lines, a prompt on an injectedIAnsiConsolefails as it does in any non-interactive console, and Repl’s own text prompts answerIReplInteractionChannelrequests instead of Spectre’s. An uncolored console stays interactive: prompts on an injectedIAnsiConsolekeep working underapp | tee log, andNO_COLORon a terminal keeps Spectre’s prompts. - Unicode box-drawing degrades per output sink: full Unicode borders when the sink’s encoding carries them, Spectre’s square ASCII-safe fallback on a legacy OEM codepage, and ASCII transliteration (
+,-,|) when no box glyph survives (redirected consoles, CI logs, pipes). The active verdict is exposed asSpectreTerminalDetection.CurrentBoxDrawingSupportfor diagnostics. - CI logs are plain by default — Spectre’s built-in CI enrichers are disabled so they cannot override the host detection. Set
FORCE_COLOR=1(orCLICOLOR_FORCE=1) in the workflow to restore colored logs.
Outside a Repl container (bare AddSpectreConsole() without UseSpectreConsole()), the profile falls back to Spectre’s own detection.
Help output formatting
Section titled “Help output formatting”Help can also be rendered in structured formats:
myapp contacts --help # human-readablemyapp contacts --help --json # machine-readable JSONThe JSON format returns a structured ReplDocumentationModel — useful for tooling, documentation generators, and agents.
IAnsiConsole injection
Section titled “IAnsiConsole injection”Repl.Spectre registers Spectre’s IAnsiConsole in DI, bound to the current session’s output stream. Inject it directly when you need full Spectre control:
app.Map("demo", (IAnsiConsole console) =>{ console.Write(new FigletText("Repl").Color(Color.Blue)); console.MarkupLine("[bold green]Ready.[/]");});This is session-safe in hosted mode — each session gets its own IAnsiConsole bound to its output stream.
A prompt on the injected console fails where the console is colored but may not drive the terminal (see Detecting Spectre capability); ask through IReplInteractionChannel to keep working there.