### MCP Serve Command

Source: https://github.com/yllibed/repl/blob/main/README.md

Example of how to start the MCP server using a command-line argument.

```json
{ "command": "myapp", "args": ["mcp", "serve"] }
```

--------------------------------

### Basic MCP Server Setup

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-overview.md

Configure and run an MCP server with a simple 'greet' command. This setup allows AI agents to connect and interact with your application's commands.

```csharp
using Repl.Mcp;

var app = ReplApp.Create().UseDefaultInteractive();
app.UseMcpServer();

app.Map("greet {name}", (string name) => $"Hello, {name}!");

return app.Run(args);
```

--------------------------------

### Elicitation Examples

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-agent-capabilities.md

Examples demonstrating dynamic configuration and guided selection using the elicitation interface.

```APIDOC
## Dynamic Configuration

### Description
Ask the user for settings that depend on runtime context.

### Method
`ElicitChoiceAsync`, `ElicitBooleanAsync`

### Example
```csharp
var envIndex = await elicitation.ElicitChoiceAsync(
    $"Which environment for {service}?",
    availableEnvironments,
    ct);
var env = envIndex is not null ? availableEnvironments[envIndex.Value] : "dev";

var dryRun = await elicitation.ElicitBooleanAsync("Dry run?", ct);
```

## Guided Selection

### Description
Let the user choose when the code discovers multiple options.

### Method
`ElicitChoiceAsync`

### Example
```csharp
var instances = registry.GetInstances(service);
if (instances.Count > 1 && elicitation.IsSupported)
{
    var hosts = instances.Select(i => i.Host).ToList();
    var selected = await elicitation.ElicitChoiceAsync(
        $"Multiple {service} instances found. Which one?",
        hosts,
        ct);

    // ... connect to the chosen instance ...
}
```
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-overview.md

Example JSON configuration for MCP clients, specifying how to launch the 'myapp' MCP server. This format is common across various clients.

```json
{
  "mcpServers": {
    "myapp": {
      "command": "myapp",
      "args": ["mcp", "serve"]
    }
  }
}
```

--------------------------------

### Protocol Passthrough Command Examples

Source: https://github.com/yllibed/repl/blob/main/docs/commands.md

Examples demonstrating the usage of protocol passthrough mode for different command types.

```text
mytool mcp start        # protocol mode over stdin/stdout
mytool start            # normal CLI command
mytool status --json    # normal structured output

```

--------------------------------

### Basic Repl.Testing Example

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Testing/README.md

Demonstrates setting up a ReplTestHost, opening a session, and running a command. Ensure necessary using directives are present.

```csharp
using Repl;
using Repl.Testing;

await using var host = ReplTestHost.Create(() =>
{
    var app = ReplApp.Create().UseDefaultInteractive();
    app.Map("hello", () => "world");
    return app;
});

await using var session = await host.OpenSessionAsync();
var execution = await session.RunCommandAsync("hello --no-logo");
```

--------------------------------

### Command Examples

Source: https://github.com/yllibed/repl/blob/main/samples/01-core-basics/README.md

Demonstrates various command-line syntaxes for listing, showing, and reporting with different period formats.

```text
myapp list --format json
```

```text
myapp show 1 --no-verbose
```

```text
myapp report period --period 2024-01-15..2024-02-15
```

```text
myapp report period --period 2024-01-15@30d
```

--------------------------------

### Create Basic Repl App

Source: https://github.com/yllibed/repl/blob/main/README.md

Initialize a new Repl application and map a simple 'hello' command. This is the basic setup for a Repl application.

```csharp
using Repl;

var app = ReplApp.Create().UseDefaultInteractive();
app.Map("hello", () => "world");
return app.Run(args);
```

--------------------------------

### CLI Mode Example

Source: https://github.com/yllibed/repl/blob/main/README.md

Shows how a command defined in the Repl application can be invoked from the command line interface.

```text
$ myapp client list --json
{
  "clients": ["ACME", "Globex"]
}
```

--------------------------------

### Minimal Repl App Setup

Source: https://github.com/yllibed/repl/blob/main/src/Repl/README.md

Use this snippet to create a basic Repl application with default interactive features and map a simple command.

```csharp
using Repl;

var app = ReplApp.Create().UseDefaultInteractive();
app.Map("hello", () => "world");

return app.Run(args);
```

--------------------------------

### Fish Shell Completion Setup

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

Set up 'myapp' command completion in Fish shell by defining a completion function and using the complete command.

```fish
function _myapp_complete
  set -l line (commandline -p)
  set -l cursor (commandline -C)
  myapp completion __complete --shell fish --line "$line" --cursor "$cursor" --no-interactive --no-logo
end

complete -c myapp -f -a "(_myapp_complete)"
```

--------------------------------

### Install Repl.Protocol Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Protocol/README.md

Use this command to add the Repl.Protocol package to your .NET project.

```bash
dotnet add package Repl.Protocol
```

--------------------------------

### Setup Repl App with Spectre Console Integration

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Spectre/README.md

Registers Spectre.Console services and configures the ReplApp to use the Spectre output transformer. This setup is essential for enabling rich prompts and Spectre-based output.

```csharp
var app = ReplApp.Create(services =>
{
    services.AddSpectreConsole(); // DI: IAnsiConsole + SpectreInteractionHandler + SpectreInteractionPresenter
})
.UseSpectreConsole(); // Output transformer + banner format + UTF-8 encoding
```

--------------------------------

### Route Template Syntax Examples

Source: https://github.com/yllibed/repl/blob/main/docs/route-system.md

Examples of route templates with static and dynamic segments, explicit constraints, default string types, URI constraints, and optional trailing segments.

```csharp
app.Map("user {id:int}", handler);      // explicit constraint
app.Map("search {query}", handler);     // defaults to string
app.Map("file {path:uri}", handler);    // URI constraint
app.Map("item {id?}", handler);         // optional trailing segment
```

--------------------------------

### Run MCP Server Mode

Source: https://github.com/yllibed/repl/blob/main/samples/08-mcp-server/README.md

Start the sample as an MCP server for AI agent interaction.

```bash
dotnet run -- mcp serve
```

--------------------------------

### Install Repl.Testing Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Testing/README.md

Use the dotnet CLI to add the Repl.Testing package to your project.

```bash
dotnet add package Repl.Testing
```

--------------------------------

### REPL Mode Example

Source: https://github.com/yllibed/repl/blob/main/README.md

Illustrates interacting with the command graph in an interactive REPL session. Commands can be chained and parameters provided.

```text
$ myapp
> client 42 show --json
{ "id": 42, "name": "ACME" }

> client
[client]> list
ACME
Globex
```

--------------------------------

### Start MCP Server

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-overview.md

Command to start the MCP stdio server. The application also remains functional as a CLI or interactive REPL.

```bash
myapp mcp serve    # starts MCP stdio server
```

```bash
myapp              # still works as CLI / interactive REPL
```

--------------------------------

### Spectre.Console.Cli Command App Setup

Source: https://github.com/yllibed/repl/blob/main/docs/comparison.md

This snippet shows the setup for a command-line application using Spectre.Console.Cli. It requires defining settings classes, command classes, and DI bridge classes, resulting in a minimum of 5 additional types.

```csharp
// 1 settings class + 1 command class per command + 2 DI bridge classes
var registrar = new TypeRegistrar(services);
var app = new CommandApp(registrar);

app.Configure(config =>
{
    config.AddBranch<RemoteSettings>("remote", remote =>
    {
        remote.AddCommand<RemoteAddCommand>("add");
    });
});
return await app.RunAsync(args);

// RemoteSettings, RemoteAddSettings (inherits RemoteSettings),
// RemoteAddCommand : Command<RemoteAddSettings>,
// TypeRegistrar : ITypeRegistrar, TypeResolver : ITypeResolver
// Minimum 5 additional types required.
```

--------------------------------

### Repl Toolkit User Commands for Shell Completion

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

These CLI-only commands manage shell completion setup. They are used for installing, uninstalling, checking the status, and detecting the current shell.

```text
completion install [--shell bash|powershell|zsh|fish|nu] [--force] [--silent]
```

```text
completion uninstall [--shell bash|powershell|zsh|fish|nu] [--silent]
```

```text
completion status
```

```text
completion detect-shell
```

--------------------------------

### MCP-only Feedback Example

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-agent-capabilities.md

An example demonstrating how to use the IMcpFeedback interface for MCP-specific feedback.

```APIDOC
## Example: MCP-only feedback

### Description
This example shows how to use `IMcpFeedback` to report progress and send messages, with checks for support.

### Code
```csharp
app.Map("sync contacts",
    async (IMcpFeedback feedback, CancellationToken ct) =>
{
    if (feedback.IsLoggingSupported)
    {
        await feedback.SendMessageAsync(LoggingLevel.Info, "Starting sync.", ct);
    }

    if (feedback.IsProgressSupported)
    {
        await feedback.ReportProgressAsync(
            new ReplProgressEvent("Syncing", Percent: 25),
            ct);
        await feedback.ReportProgressAsync(
            new ReplProgressEvent(
                "Waiting for approval",
                State: ReplProgressState.Indeterminate,
                Details: "The remote agent is still reviewing the batch."),
            ct);
    }

    return Results.Success("Sync completed.");
});
```
```

--------------------------------

### Install Repl.Core Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Core/README.md

Use this command to add the Repl.Core package to your .NET project.

```bash
dotnet add package Repl.Core
```

--------------------------------

### Install Repl.WebSocket Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.WebSocket/README.md

Use this command to add the Repl.WebSocket package to your .NET project.

```bash
dotnet add package Repl.WebSocket
```

--------------------------------

### Add Repl.Defaults Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Defaults/README.md

Installs the Repl.Defaults NuGet package using the .NET CLI.

```bash
dotnet add package Repl.Defaults
```

--------------------------------

### MCP Server Publishing and Installation Commands

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-reference.md

These bash commands cover publishing a .NET NuGet package and installing/running an MCP tool. Use `dotnet nuget push` for publishing and `dotnet tool install` or `dnx` for running.

```bash
# Publish
dotnet pack -c Release
dotnet nuget push bin/Release/MyApp.1.0.0.nupkg --source https://api.nuget.org/v3/index.json
```

```bash
# Install and run
dotnet tool install -g MyApp
myapp mcp serve
```

```bash
# Run without install
dnx -y MyApp -- mcp serve
```

--------------------------------

### Install Repl.Telnet Package

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Telnet/README.md

Add the Repl.Telnet package to your .NET project using the dotnet CLI.

```bash
dotnet add package Repl.Telnet
```

--------------------------------

### Run a Telnet Session with Repl App

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Telnet/README.md

Example demonstrating how to create a ReplApp, configure it for interactive use, map a command, and run a session over a Telnet stream connected to a TcpClient.

```csharp
using System.Net.Sockets;
using Repl;
using Repl.Telnet;

var app = ReplApp.Create().UseDefaultInteractive();
app.Map("hello", () => "world");

using var client = new TcpClient("127.0.0.1", 23);
await using var stream = client.GetStream();
return await ReplTelnetSession.RunAsync(app, stream);
```

--------------------------------

### Interactive Transcript Example

Source: https://github.com/yllibed/repl/blob/main/samples/04-interactive-ops/README.md

Shows an example of an interactive transcript where user input and system responses are displayed. This is rendered by the host based on typed interaction events.

```text
> contact import contacts.csv
Parsing 'contacts.csv'...
Detected 2 duplicate(s).
How to handle duplicates? [SKIP/overwrite/cancel]: ov
Importing: 100%
5 imported, 2 overwritten, 0 skipped.
```

--------------------------------

### Run Repl.WebSocket Session

Source: https://github.com/yllibed/repl/blob/main/src/Repl.WebSocket/README.md

Example of setting up a ReplApp and running a session over a connected WebSocket. Ensure the 'socket' variable is initialized with a connected WebSocket.

```csharp
using System.Net.WebSockets;
using Repl;
using Repl.WebSocket;

var app = ReplApp.Create().UseDefaultInteractive();
app.Map("hello", () => "world");

WebSocket socket = /* connected socket */;
return await ReplWebSocketSession.RunAsync(app, socket);
```

--------------------------------

### Add Repl.Mcp Package

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-overview.md

Install the necessary NuGet package to enable MCP server integration.

```bash
dotnet add package Repl.Mcp
```

--------------------------------

### Repl Toolkit Interactive App Setup

Source: https://github.com/yllibed/repl/blob/main/docs/comparison.md

This snippet demonstrates setting up an interactive application using Repl Toolkit. It requires fewer additional types compared to Spectre.Console.Cli and allows handlers to work in both CLI and REPL modes.

```csharp
var app = ReplApp.Create(services =>
{
    services.AddSingleton<IRepositoryService, RepositoryService>();
}).UseDefaultInteractive();

app.Context("remote", remote =>
{
    remote.Map("add", (
        [Description("Repository URL")] string url,
        [Description("Remote name")] string name = "origin",
        IRepositoryService repo) =>
    {
        repo.AddRemote(name, url);
        return $"Remote '{name}' added.";
    });
});

return app.Run(args);
// Zero additional types. Same handler works in CLI and REPL modes.
```

--------------------------------

### Add Repl Package to Project

Source: https://github.com/yllibed/repl/blob/main/README.md

Install the Repl NuGet package to your .NET project.

```bash
dotnet add package Repl
```

--------------------------------

### Zsh Shell Completion Setup

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

Integrate 'myapp' command completion into Zsh by defining a completion function and using compdef.

```zsh
_myapp_complete() {
  local line cursor
  local candidate
  local -a reply
  line="$BUFFER"
  cursor=$((CURSOR > 0 ? CURSOR - 1 : 0))
  reply=()
  while IFS= read -r candidate; do
    reply+=("$candidate")
  done < <(myapp completion __complete --shell zsh --line "$line" --cursor "$cursor" --no-interactive --no-logo)
  if (( ${#reply[@]} > 0 )); then
    compadd -- "${reply[@]}"
  fi
}

compdef _myapp_complete myapp
```

--------------------------------

### Module Composition and DI Setup

Source: https://github.com/yllibed/repl/blob/main/samples/03-modular-ops/README.md

Configures the application with open-generic DI for entity stores and mounts reusable CRUD modules for different entities.

```csharp
var app = ReplApp.Create(services =>
{
    // Open-generic store registration:
    services.AddSingleton(typeof(IEntityStore<>), typeof(InMemoryEntityStore<>));
})
.UseDefaultInteractive()
.UseCliProfile();

// Mount the same CRUD module three times:
app.Context("client", m => m.MapModule<EntityCrudModule<Client>>());
app.Context("contact", m => m.MapModule<EntityCrudModule<Contact>>());
app.Context("invoice", m => m.MapModule<EntityCrudModule<Invoice>>());

// Ops module for non-CRUD commands
app.Context("ops", m => m.MapModule<OpsModule>());

return app.Run(args);
```

--------------------------------

### Bash Shell Completion Setup

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

Add this function and command to your .bashrc or .bash_profile to enable command completion for 'myapp' in Bash.

```bash
_myapp_complete() {
  local line cursor
  local candidate
  line="$COMP_LINE"
  cursor="$COMP_POINT"
  COMPREPLY=()
  while IFS= read -r candidate; do
    COMPREPLY[${#COMPREPLY[@]}]="$candidate"
  done < <(myapp completion __complete --shell bash --line "$line" --cursor "$cursor" --no-interactive --no-logo)
}

complete -F _myapp_complete myapp
```

--------------------------------

### Draft Content using Sampling

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-agent-capabilities.md

This example demonstrates using sampling to generate a draft reply to a support ticket. The LLM is provided with the ticket body and asked to draft a response.

```csharp
var draft = await sampling.SampleAsync(
    $"Draft a reply to this support ticket:\n\n{ticket.Body}",
    maxTokens: 512, cancellationToken: ct);
```

--------------------------------

### Create Documentation Model

Source: https://github.com/yllibed/repl/blob/main/docs/help-system.md

Call this method to get a structured representation of the application's commands, contexts, and resources. This model is used for rendering help text, generating schemas, and shell completion.

```csharp
var model = app.CreateDocumentationModel();
// model.App       — app metadata (name, version, description)
// model.Commands  — all commands with arguments, options, answers
// model.Contexts  — all contexts with descriptions
// model.Resources — resource-annotated commands
```

--------------------------------

### Response File Example

Source: https://github.com/yllibed/repl/blob/main/docs/commands.md

Response files (e.g., `@file.rsp`) are expanded before command option parsing. They support quotes and escapes, and standalone '@' tokens are treated as normal positional tokens.

```text
--output json
# comments are ignored outside quoted sections
"two words"
```

--------------------------------

### MCP-Only Feedback Example

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-agent-capabilities.md

Demonstrates using IMcpFeedback to report progress and send messages specifically within an MCP context. Always check IsLoggingSupported and IsProgressSupported before calling their respective methods.

```csharp
app.Map("sync contacts",
    async (IMcpFeedback feedback, CancellationToken ct) =>
{
    if (feedback.IsLoggingSupported)
    {
        await feedback.SendMessageAsync(LoggingLevel.Info, "Starting sync.", ct);
    }

    if (feedback.IsProgressSupported)
    {
        await feedback.ReportProgressAsync(
            new ReplProgressEvent("Syncing", Percent: 25),
            ct);
        await feedback.ReportProgressAsync(
            new ReplProgressEvent(
                "Waiting for approval",
                State: ReplProgressState.Indeterminate,
                Details: "The remote agent is still reviewing the batch."),
            ct);
    }

    return Results.Success("Sync completed.");
});
```

--------------------------------

### PowerShell Shell Completion Setup

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

Configure 'myapp' command completion in PowerShell by registering an argument completer. PowerShell 7+ is recommended for reliable native completion.

```powershell
$__replCompletionCommandNames = @('myapp')
$__replCompleter = {
    param($wordToComplete, $commandAst, $cursorPosition)

    $invokedCommand = if ($commandAst.CommandElements.Count -gt 0 -and $commandAst.CommandElements[0] -is [System.Management.Automation.Language.StringConstantExpressionAst]) {
        $commandAst.CommandElements[0].Value
    } else {
        'myapp'
    }

    & $invokedCommand completion __complete --shell powershell --line $commandAst.ToString() --cursor $cursorPosition --no-interactive --no-logo |
        ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
if ((Get-Command Register-ArgumentCompleter).Parameters.ContainsKey('Native')) {
    Register-ArgumentCompleter -Native -CommandName $__replCompletionCommandNames -ScriptBlock $__replCompleter
} else {
    Register-ArgumentCompleter -CommandName $__replCompletionCommandNames -ScriptBlock $__replCompleter
}
```

--------------------------------

### Configure Repl App Options

Source: https://github.com/yllibed/repl/blob/main/docs/configuration-reference.md

Set interactive prompt, default output format, and response file parsing behavior. This is a common starting point for customizing the REPL environment.

```csharp
var app = ReplApp.Create();
app.Options(o =>
{
    o.Interactive.Prompt = "$";
    o.Output.DefaultFormat = "json";
    o.Parsing.AllowResponseFiles = false;
});
```

--------------------------------

### Filter Commands in MCP Server

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-reference.md

Use `CommandFilter` to exclude commands from being exposed as tools. This example filters out commands starting with 'debug'.

```csharp
app.UseMcpServer(o =>
{
    o.CommandFilter = cmd => !cmd.Path.StartsWith("debug", StringComparison.OrdinalIgnoreCase);
});
```

--------------------------------

### Anonymized Human Output for Shell Completion Status

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

This example shows the human-readable output from the `completion status` command, detailing the configuration and installation status for various shells.

```text
Enabled                : True
Setup mode             : Manual
Detected shell         : powershell (env suggests PowerShell; parent process chain: <process-a> -> <process-b>)
Bash profile           : <home>/.bashrc
Bash profile exists    : True
Bash installed         : False
PowerShell profile     : <documents>/PowerShell/Microsoft.PowerShell_profile.ps1
PowerShell profile exists: True
PowerShell installed   : False
Zsh profile            : <home>/.zshrc
Zsh profile exists     : False
Zsh installed          : False
Fish profile           : <config>/fish/config.fish
Fish profile exists    : False
Fish installed         : False
Nushell profile        : <config>/nushell/config.nu
Nushell profile exists : False
Nushell installed      : False
```

--------------------------------

### Date Range Validation Example

Source: https://github.com/yllibed/repl/blob/main/samples/01-core-basics/README.md

Shows an example of an invalid date range literal and the expected validation error message.

```text
$ myapp report period --period 2024-01-15@8h
Validation: '2024-01-15@8h' is not a valid date range literal. Use start..end or start@duration with whole days.
```

--------------------------------

### Create a Minimal Repl.Core App

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Core/README.md

This C# snippet demonstrates how to create a minimal Repl.Core application, map a simple route, and run the application.

```csharp
using Repl;

var app = CoreReplApp.Create();
app.Map("hello", () => "world");

return app.Run(args);
```

--------------------------------

### Create Host and Open Session

Source: https://github.com/yllibed/repl/blob/main/docs/testing-toolkit.md

Initialize the test host and open a session to run commands. The host is created with a factory function that configures the REPL application.

```csharp
using Repl.Testing;
using Repl.Interaction;
using Repl.Terminal;

await using var host = ReplTestHost.Create(() =>
{
    var app = ReplApp.Create().UseDefaultInteractive();
    app.Map("hello", () => "world");
    return app;
});

await using var session = await host.OpenSessionAsync();
var execution = await session.RunCommandAsync("hello --no-logo");
```

--------------------------------

### Basic CLI Commands

Source: https://github.com/yllibed/repl/blob/main/samples/03-modular-ops/README.md

Demonstrates simple CLI commands like ping, add, and list for different entities.

```text
$ myapp ops ping
pong
```

```text
$ myapp client add "ACME Corp" --json
{ "id": 1, "name": "ACME Corp" }
```

```text
$ myapp client list --json
[{ "id": 1, "name": "ACME Corp" }]
```

--------------------------------

### Agent-style CLI Help and Usage

Source: https://github.com/yllibed/repl/blob/main/samples/03-modular-ops/README.md

Demonstrates how agents can discover and use commands through the CLI, showing help messages and specific command execution.

```text
$ myapp --help
Commands:
  ops
  client
  contact
  invoice
```

```text
$ myapp client --help
Commands:
  list
  add {name}
  {id} ...
```

```text
$ myapp client 1 show --json
{ "id": 1, "name": "ACME Corp" }
```

--------------------------------

### Run Spectre Sample

Source: https://github.com/yllibed/repl/blob/main/samples/07-spectre/README.md

Command to execute the Spectre.Console integration sample project.

```bash
dotnet run --project samples/07-spectre/SpectreOpsSample.csproj
```

--------------------------------

### Example Custom Interaction Handler

Source: https://github.com/yllibed/repl/blob/main/docs/interaction.md

An example of a custom interaction handler that implements the `IReplInteractionHandler` interface. This handler pattern-matches on specific request types and provides custom logic for handling them, delegating to Spectre.Console for rendering.

```csharp
public class SpectreInteractionHandler : IReplInteractionHandler
{
    public ValueTask<InteractionResult> TryHandleAsync(
        InteractionRequest request, CancellationToken ct) => request switch
    {
        AskChoiceRequest r => HandleChoice(r, ct),
        AskSecretRequest r => HandleSecret(r, ct),
        _ => new ValueTask<InteractionResult>(InteractionResult.Unhandled),
    };

    private async ValueTask<InteractionResult> HandleChoice(
        AskChoiceRequest r, CancellationToken ct)
    {
        // Spectre.Console rendering...
        var index = 0; // resolved from Spectre prompt
        return InteractionResult.Success(index);
    }

    private async ValueTask<InteractionResult> HandleSecret(
        AskSecretRequest r, CancellationToken ct)
    {
        // Spectre.Console secret prompt...
        var secret = ""; // resolved from Spectre prompt
        return InteractionResult.Success(secret);
    }
}
```

--------------------------------

### CLI Help and Discovery

Source: https://github.com/yllibed/repl/blob/main/samples/01-core-basics/README.md

Demonstrates how to access command help and discovery information directly from the CLI.

```text
$ myapp --help
Commands:
  list
  add {name} {email}
  show {id}
  count
```

--------------------------------

### Run Commands and Sessions with ReplTestHost

Source: https://github.com/yllibed/repl/blob/main/samples/06-testing/README.md

Demonstrates a multi-step, multi-session scenario using ReplTestHost to open sessions and run commands. Assertions are made on exit codes, output text, and typed results.

```csharp
await using var host = ReplTestHost.Create(() => SampleReplApp.Create(shared));
await using var admin = await host.OpenSessionAsync(new SessionDescriptor { TransportName = "signalr" });
await using var op = await host.OpenSessionAsync(new SessionDescriptor { TransportName = "websocket" });

var set = await admin.RunCommandAsync("settings set maintenance on --no-logo");
var show = await op.RunCommandAsync("settings show maintenance --no-logo");
var widget = await op.RunCommandAsync("widget show 2 --json --no-logo");

set.ExitCode.Should().Be(0);
show.OutputText.Should().Contain("on");
widget.GetResult<SampleReplApp.Widget>().Name.Should().Be("Beta");
```

--------------------------------

### Agent-style Discovery Help

Source: https://github.com/yllibed/repl/blob/main/samples/01-core-basics/README.md

Shows how an automated client can discover command details, including usage and arguments, using the `--help` flag.

```text
$ myapp add --help
Usage: add {name} {email}

Arguments:
  name    Full name
  email   Email address
```

--------------------------------

### Run REPL Testing Sample

Source: https://github.com/yllibed/repl/blob/main/samples/06-testing/README.md

Execute the REPL testing sample project using the dotnet test command with minimal verbosity.

```powershell
dotnet test --project samples/06-testing/TestingSample.csproj -v minimal
```

--------------------------------

### Get Feature Values

Source: https://github.com/yllibed/repl/blob/main/samples/05-hosting-remote/wwwroot/index.html

Collects the current checked state of all feature checkboxes and returns them as an object.

```javascript
function getFeatureValues() {
  return Object.fromEntries(featureInputs.map(input => [input.value, input.checked]));
}
```

--------------------------------

### Run Repl Toolkit Sample Project

Source: https://github.com/yllibed/repl/blob/main/samples/README.md

Use this command to run a specific Repl Toolkit sample project. Replace the project path with the desired sample's .csproj file.

```powershell
dotnet run --project samples/01-core-basics/CoreBasicsSample.csproj
```

--------------------------------

### Create Help Document and Project to MCP Tool Descriptor

Source: https://github.com/yllibed/repl/blob/main/src/Repl.Protocol/README.md

This C# code demonstrates how to create a help document with commands and then project it to an MCP tool descriptor using Repl.Protocol.

```csharp
using Repl.Protocol;

var help = ProtocolContracts.CreateHelpDocument(
    scope: "root",
    commands: new[]
    {
        new HelpCommand(
            Name: "contact list",
            Description: "List contacts",
            Usage: "contact list [--json]")
    });

var tool = ProtocolContracts.CreateMcpTool(help.Commands[0]);
```

--------------------------------

### Seed History for Discoverability in C#

Source: https://github.com/yllibed/repl/blob/main/docs/best-practices.md

Seed the history provider with common commands to improve discoverability. This example uses an in-memory provider.

```csharp
services.AddSingleton<IHistoryProvider>(new InMemoryHistoryProvider([
    "contacts list", "contacts add", "status"
]));
```

--------------------------------

### Scope Module to CLI Channel

Source: https://github.com/yllibed/repl/blob/main/docs/module-presence.md

This example demonstrates how to scope a module to be present only in the CLI channel. The module will be absent in Interactive and Session channels.

```csharp
app.MapModule(
    new ShellCompletionModule(),
    context => context.Channel == ReplRuntimeChannel.Cli);

```

--------------------------------

### Command Using Response File

Source: https://github.com/yllibed/repl/blob/main/docs/commands.md

This command demonstrates how to use a response file to pass arguments to the application.

```text
myapp echo @args.rsp
```

--------------------------------

### Run Remote REPL Sample

Source: https://github.com/yllibed/repl/blob/main/samples/05-hosting-remote/README.md

Execute the remote REPL sample using the .NET CLI. Ensure you are in the project directory.

```powershell
dotnet run --project samples/05-hosting-remote/HostingRemoteSample.csproj
```

--------------------------------

### Agent Discovery: Specific Contact Help

Source: https://github.com/yllibed/repl/blob/main/samples/02-scoped-contacts/README.md

Illustrates how an agent can get help for commands related to a specific contact by resolving the dynamic segment.

```text
$ myapp contact "Alice Martin" --help
Commands:
  show      Show contact details
  remove    Remove this contact
```

--------------------------------

### Agent Discovery: App Help

Source: https://github.com/yllibed/repl/blob/main/samples/02-scoped-contacts/README.md

Demonstrates how an automated client can discover available commands by querying the application's help information.

```text
$ myapp --help
Commands:
  contact    Manage contacts
```

--------------------------------

### Register Ambient Commands in C#

Source: https://github.com/yllibed/repl/blob/main/docs/best-practices.md

Register ambient commands for common actions to enhance interactivity. This example maps the 'clear' command to clear the screen.

```csharp
app.Options(o => o.AmbientCommands.MapAmbient(
    "clear",
    static async (IReplInteractionChannel ch, CancellationToken ct) =>
        await ch.ClearScreenAsync(ct),
    "Clear the screen"));
```

--------------------------------

### Debug MCP Server with Inspector

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-reference.md

Launch the MCP Inspector to debug an MCP server named 'myapp'. This command starts the server and connects it to the inspector.

```bash
npx @modelcontextprotocol/inspector myapp mcp serve
```

--------------------------------

### Agent Discovery: Contact Context Help

Source: https://github.com/yllibed/repl/blob/main/samples/02-scoped-contacts/README.md

Shows how an agent can discover commands within the 'contact' context, including dynamic segments.

```text
$ myapp contact --help
Commands:
  list                  List all contacts
  add {name} {email}    Add a contact
  {name} ...            Manage a specific contact
```

--------------------------------

### Nushell Shell Completion Setup

Source: https://github.com/yllibed/repl/blob/main/docs/shell-completion.md

Configure 'myapp' command completion in Nushell by defining a custom completer in the environment configuration. This uses a global dispatcher for completions.

```nu
const __repl_completion_entries = [
  { appId: "myapp", command: "myapp" }
]
def _repl_nu_dispatch_completion [spans: list<string>] {
  if (($spans | length) == 0) {
    return []
  }

  let head = ($spans | get 0)
  let matches = ($__repl_completion_entries | where { |item| $item.command == $head })
  if (($matches | length) == 0) {
    return []
  }

  let entry = ($matches | get 0)
  let line = ($spans | str join ' ')
  let cursor = ($line | str length)
  (
    ^$entry.command completion __complete --shell nu --line $line --cursor $cursor --no-interactive --no-logo
    | lines
    | each { |line| { value: $line, description: "" } }
  )
}

$env.config = (
  $env.config
  | upsert completions.external.enable true
)
$env.config.completions.external.completer = { |spans| _repl_nu_dispatch_completion $spans }
```

--------------------------------

### Run Interactive REPL

Source: https://github.com/yllibed/repl/blob/main/samples/08-mcp-server/README.md

Execute the sample in interactive REPL mode.

```bash
dotnet run
```

--------------------------------

### Get Session Configuration

Source: https://github.com/yllibed/repl/blob/main/samples/05-hosting-remote/wwwroot/index.html

Gathers the current feature settings to construct the session configuration object, which is advertised to the host. Includes ANSI support and transport type.

```javascript
function getSessionConfig() {
  const features = getFeatureValues();
  const ansi = !!features.ansi;
  const transport = getSelectedTransport();
  const capabilities = [];
  if (ansi) {
    capabilities.push('Ansi');
  }
  if (features.resize) {
    capabili
```

--------------------------------

### Create REPL App with Scoped Contacts

Source: https://github.com/yllibed/repl/blob/main/samples/02-scoped-contacts/README.md

Initializes the REPL application, registers a singleton contact store, and defines the 'contact' context with nested commands for managing contacts.

```csharp
var app = ReplApp.Create(services =>
{
    services.AddSingleton<IContactStore, InMemoryContactStore>();
})
    .WithDescription("Scoped contacts sample: dynamic contact scope with DI-backed storage.")
    .UseDefaultInteractive()
    .UseCliProfile();

app.Context(
    "contact",
    [Description("Manage contacts")]
    (IReplMap contact) =>
    {
        contact.WithBanner((TextWriter w, IContactStore store) =>
        {
            w.WriteLine($"  {store.All().Count} contact(s) in store. Try: list, add, remove");
        });

        // Root-level commands inside contact scope.
        contact.Map(
            "list",
            [Description("List all contacts")]
            (IContactStore store) => store.All());

        contact.Map(
            "add {name} {email:email}",
            [Description("Add a contact")]
            (string name, string email, IContactStore store) =>
            {
                store.Add(new Contact(name, email));
                return "Contact '" + name + "' added.";
            });

        contact.Context(
            "{name}",
            [Description("Manage a specific contact")]
            (IReplMap scope) =>
            {
                // Scoped commands resolved for one selected contact name.
                scope.Map(
                    "show",
                    [Description("Show contact details")]
                    (string name, IContactStore store) => store.Get(name));

                scope.Map(
                    "remove",
                    [Description("Remove this contact")]
                    (string name, IContactStore store) =>
                    {
                        store.Remove(name);
                        return Results.NavigateUp($"Contact '{name}' removed.");
                    });
            },
            validation: (string name, IContactStore store) => store.Get(name) is not null);
    });

return app.Run(args);
```

--------------------------------

### Guided Selection for Multiple Instances

Source: https://github.com/yllibed/repl/blob/main/docs/mcp-agent-capabilities.md

When multiple service instances are found, use ElicitChoiceAsync to let the user select one. This requires the elicitation capability to be supported.

```csharp
var instances = registry.GetInstances(service);
if (instances.Count > 1 && elicitation.IsSupported)
{
    var hosts = instances.Select(i => i.Host).ToList();
    var selected = await elicitation.ElicitChoiceAsync(
        $"Multiple {service} instances found. Which one?",
        hosts,
        ct);

    // ... connect to the chosen instance ...
}
```

--------------------------------

### Get Selected Transport

Source: https://github.com/yllibed/repl/blob/main/samples/05-hosting-remote/wwwroot/index.html

Retrieves the currently selected transport method (e.g., WebSocket, SignalR, Telnet) from the radio button input. Defaults to 'ws' if no selection is made.

```javascript
function getSelectedTransport() {
  return document.querySelector('input[name="transport"]:checked')?.value ?? 'ws';
}
```

--------------------------------

### Register Services with DI

Source: https://github.com/yllibed/repl/blob/main/docs/best-practices.md

Register services using 'ReplApp.Create' and prefer constructor injection or implicit injection in handlers. Use '[FromServices]' only when necessary for disambiguation.

```csharp
var app = ReplApp.Create(services =>
{
    services.AddSingleton<IContactStore, InMemoryContactStore>();
    services.AddSingleton(typeof(IEntityStore<>), typeof(InMemoryEntityStore<>));  // open-generic
});
```

```csharp
app.Map("show", static (IContactStore store) => store.All());  // implicit
app.Map("show", static ([FromServices] IContactStore store) => store.All());  // explicit (same result)
```

```csharp
app.Context("project {id:int}", project =>
{
    project.Map("status", static ([FromContext] int id, IProjectService svc) =>
        svc.GetStatus(id));
});
```