Skip to content

Interactivity

Repl provides a typed interaction channel (IReplInteractionChannel) that works across all execution modes: interactive REPL, hosted sessions, MCP tools, and automated scripts. The same handler code asks questions in a terminal, receives answers from an MCP client, or reads pre-filled values from --answer:* flags.

Inject IReplInteractionChannel (namespace Repl.Interaction) into your handler:

using Repl.Interaction;
app.Map("add", async (IReplInteractionChannel ui, IContactStore store, CancellationToken ct) =>
{
var name = await ui.AskTextAsync("name", "Full name:", ct: ct);
var email = await ui.AskTextAsync("email", "Email address:", ct: ct);
var contact = store.Add(name, email);
return Results.Success($"Added {contact.Name} (#{contact.Id}).");
});

The first argument to every prompt method is a name — a stable identifier used to match --answer:name=value flags and to route MCP elicitation responses to the right prompt.

var name = await ui.AskTextAsync("name", "Full name:", ct: ct);
var password = await ui.AskSecretAsync("password", "Password:", ct: ct);

In MCP mode, AskSecretAsync is prefill-only — the agent must supply the value upfront; elicitation and sampling are never used for secrets.

var confirmed = await ui.AskConfirmationAsync("confirm", "Delete this record? This cannot be undone.", ct: ct);
if (!confirmed)
return Results.Cancelled("Deletion cancelled.");
string[] options = ["admin", "editor", "viewer"];
var roleIndex = await ui.AskChoiceAsync("role", "Assign role:", options, ct: ct);
var role = options[roleIndex];

AskChoiceAsync returns the index of the selected item. In a capable terminal, this renders as an arrow-key menu; in plain mode it falls back to numbered choices.

string[] allPerms = ["read", "write", "delete", "export"];
var indices = await ui.AskMultiChoiceAsync("permissions", "Select permissions:", allPerms, ct: ct);
var selected = indices.Select(i => allPerms[i]).ToArray();

AskMultiChoiceAsync returns IReadOnlyList<int> — the indices of all selected items.

await ui.WriteWarningAsync("Rate limit approaching.", ct);
await ui.WriteProblemAsync("Connection failed.", ct);
await ui.WriteStatusAsync("Processing...", ct);
await ui.PressAnyKeyAsync("Press any key to continue.", ct);
await ui.ClearScreenAsync(ct);

Call WriteProgressAsync on each update — pass the label, a double? between 0 and 1, and the cancellation token:

app.Map("import {file}", static async (string file, IReplInteractionChannel ui, CancellationToken ct) =>
{
var lines = await File.ReadAllLinesAsync(file, ct);
for (int i = 0; i < lines.Length; i++)
{
ct.ThrowIfCancellationRequested();
await ImportLine(lines[i], ct);
await ui.WriteProgressAsync(
$"Importing {lines.Length} records…",
(double)(i + 1) / lines.Length,
ct);
}
return Results.Success($"Imported {lines.Length} records.");
});

Each WriteProgressAsync call is independent — there is no progress session object to manage.

await ui.WriteIndeterminateProgressAsync("Connecting…", ct: ct);
// … work …
await ui.WriteProgressAsync("Connecting…", 1.0, ct); // signals completion

Pre-fill prompts by name from the command line. Each --answer:name=value targets the prompt whose name parameter matches:

Terminal window
# Answers the 'name' prompt with "Alice", 'email' with "alice@example.com"
myapp add --answer:name=Alice --answer:email=alice@example.com

Positional answers (by order) also work:

Terminal window
myapp add --answer:1=Alice --answer:2=alice@example.com

Pass answers as a dictionary to the second overload of RunCommandAsync:

var result = await session.RunCommandAsync(
"add",
new Dictionary<string, string>
{
["name"] = "Alice",
["email"] = "alice@example.com",
},
ct);

Prefill tool arguments Elicitation client support Sampling client support Default prompt's own Fallback first, no, empty Fail tool error PrefillThenFail default mode PrefillThenDefaults PrefillThenElicitation PrefillThenSampling
What each interactivity mode tries, in order, when an MCP tool call reaches a prompt. A prompt's own default always comes before failing.

When a command is called via MCP, Repl tries to answer prompts in this order. AskMultiChoiceAsync skips elicitation, and AskSecretAsync uses prefill only:

TierMechanismNotes
1Prefill — from tool call argumentsAlways tried first
2Elicitation — structured form through the agentRequires elicitation capability
3Sampling — LLM generates an answerRequires sampling capability
4Default / FailThe prompt’s own default when it has one; otherwise PrefillThenDefaults answers the first choice, false or an empty value, and the other modes fail. See InteractivityMode

Configure the mode when enabling MCP:

app.UseMcpServer(o =>
{
o.InteractivityMode = InteractivityMode.PrefillThenFail; // the default
// or: PrefillThenDefaults, or the legacy PrefillThenElicitation | PrefillThenSampling
});

Elicitation and sampling are legacy on MCP 2026-07-28; see MCP — Advanced.


Add Repl.Spectre and register:

app.UseSpectreConsole();

IReplInteractionChannel prompts upgrade automatically to Spectre.Console widgets:

CallSpectre widget
AskTextAsyncTextPrompt<string>
AskSecretAsyncTextPrompt<string> (masked)
AskConfirmationAsyncConfirmationPrompt
AskChoiceAsyncSelectionPrompt
AskMultiChoiceAsyncMultiSelectionPrompt

No handler changes required. Spectre prompts are used where Spectre’s console is interactive; a console that is colored where the output may not drive the terminal is not, and Repl’s own text prompts answer there instead (Detecting Spectre capability). WriteProgressAsync and WriteIndeterminateProgressAsync keep Repl’s own progress line: Spectre’s Progress and Status are not connected to Repl progress.


Prefix a choice item with _ to designate it as the keyboard shortcut:

var actions = new[] { "_Retry", "_Abort", "_Skip" };
var idx = await ui.AskChoiceAsync("action", "What next?", actions, ct: ct);

The user can press R, A, or S without navigating the menu.


Every IReplInteractionChannel method accepts a CancellationToken. A cancelled prompt throws OperationCanceledException:

  • Esc cancels the prompt, including a secret prompt with a timeout.
  • Ctrl+C cancels the command’s token. In the interactive loop, Repl prints Cancelled. and the session continues; a second Ctrl+C exits.
  • A hosted terminal (WebSocket, Telnet, StreamedReplHost) that disconnects during a prompt cancels it, so no default is chosen for a user who has left.

Redirected input that simply ends still settles the prompt through its PromptFallback. A handler that prefers the old answer can catch the exception and use an empty string or the default.