Skip to content

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.

Every command supports output format flags out of the box:

FlagFormat
(none)human — plain text / table
--output:format=json (or --json)JSON
--output:format=xmlXML
--output:format=yamlYAML
--output:format=markdownMarkdown table
--output:format=spectreSpectre.Console rendering
  1. --output:format flag on the command line
  2. ReplOptions.Output.DefaultFormat (configured at startup)
  3. human (built-in default)
app.Options(o =>
{
o.Output.DefaultFormat = "json"; // all commands default to JSON
});

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 whose IsMachineReadable is true;
  • or standard output is redirected, as in myapp sync > report.txt or myapp sync | jq.
Human output, to a terminal result feedback stdout the screen stderr the screen --json, or stdout redirected result feedback stdout payload only stderr the screen
Where the result and the feedback of one command go, depending on the output format and on where standard output leads.

Otherwise feedback stays on standard output, beside the result. Framework diagnostics, such as a refused --output format, always go to standard error.

Terminal window
myapp sync --json > result.json # result.json holds the JSON; progress shows in the terminal

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.


When a command returns a ReplPage<T> or an IReplPageSource<T>, the output format determines how the page is rendered:

FormatRendering
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 / markdownExplicit 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.


Repl classifies the terminal’s color capability and chooses rendering accordingly. Capability tiers (informational):

Detected tierRendering
No ANSIPlain text, no escape sequences
Basic16 ANSI colors
Extended256 colors
TrueColor24-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:

#CheckResult
1A hosted session states its ANSI support (for example TerminalSessionOverrides.AnsiSupported)that answer
2OutputOptions.AnsiMode is Always or Neveron or off
3The host reports no ANSI support (CapabilityOptions.SupportsAnsi is false)off
4FORCE_COLOR has any non-empty value, including 0 (the rule .NET 11 applies, in its console logger and in System.Console on Linux)on
5NO_COLOR has a non-blank value (no-color.org)off
6CLICOLOR_FORCE=1on
7TERM=dumboff
8The stream is redirected to a file or a pipeoff, otherwise on

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_COLOR nor TERM=dumb (without CLICOLOR_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 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)
});

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.


Repl uses the terminal width for table column sizing, word wrap, and layout decisions.

Resolution order:

  1. OutputOptions.PreferredWidth (explicit override)
  2. COLUMNS environment variable
  3. Detected console window width
  4. Telnet NAWS / DTTERM resize for hosted sessions
  5. OutputOptions.FallbackWidth (default: 120)
app.Configure<OutputOptions>(o =>
{
o.PreferredWidth = 160;
o.FallbackWidth = 80;
});

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);
}
}

The startup banner (shown in interactive mode) can be suppressed:

Terminal window
myapp --no-logo

Or globally:

app.Options(o =>
{
o.Output.BannerEnabled = false;
// or: o.Output.BannerFormats = ["human"] — show only in human format (default)
});

Add Repl.Spectre and register:

app.UseSpectreConsole(); // enables rich prompts and renderables in one call

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;
});

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[/]");
TypeDescription
TableGrid with borders, alignment, and markup
PanelBox with optional header and border
TreeHierarchical tree view
BarChartHorizontal bar chart
BreakdownChartProportion chart
CalendarMonthly calendar with highlighted dates
JsonTextSyntax-highlighted JSON
FigletTextLarge ASCII art text
TextPathBreadcrumb path rendering
MarkupInline styled text
Grid / ColumnsFree-form layout
RuleHorizontal divider
Progress / StatusLive progress widgets

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 NoColors and 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_COLOR and TERM=dumb still win over that fallback.
  • Live displays and prompts: Spectre animates Progress and Status only 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 under NO_COLOR or TERM=dumb) is not interactive: live displays print static lines, a prompt on an injected IAnsiConsole fails as it does in any non-interactive console, and Repl’s own text prompts answer IReplInteractionChannel requests instead of Spectre’s. An uncolored console stays interactive: prompts on an injected IAnsiConsole keep working under app | tee log, and NO_COLOR on 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 as SpectreTerminalDetection.CurrentBoxDrawingSupport for 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 (or CLICOLOR_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 can also be rendered in structured formats:

Terminal window
myapp contacts --help # human-readable
myapp contacts --help --json # machine-readable JSON

The JSON format returns a structured ReplDocumentationModel — useful for tooling, documentation generators, and agents.


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.