Repl Toolkit

https://github.com/yllibed/repl
Admin
Repl Toolkit is a .NET framework for building composable command surfaces that can be run as a CLI,...
Tokens:122,708
Snippets:988
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Repl.WebSocket package

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

Installs the Repl.WebSocket NuGet package into the current project.

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

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

### Install Repl and create a minimal app

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

Install the Repl package and create a minimal interactive application. The C# code sets up a default interactive REPL, maps a simple "hello" command, and runs the app.

```bash
dotnet add package Repl
```

```csharp
using Repl;

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

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

### Install Repl.Telnet package

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

Install the Repl.Telnet package from NuGet.

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

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

### Install Repl.Protocol package

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

Install the Repl.Protocol NuGet package into a .NET project.

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

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

### Publish, install, and run the MCP server tool

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

Publish the tool to NuGet, install it globally, and run it. The dnx command runs the tool without installation.

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

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

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

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

### Agent-style command examples for myapp

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

Shows the command surface exposed by the modular demo. The first block lists top-level commands; the second shows the client subcommand's options; the third demonstrates a JSON output for a specific client. These are sequential examples of the same agent-style usage.

```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 the Spectre sample project

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

Starts the sample application. Use this command to launch the REPL and explore the Spectre.Console integration.

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

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

### Install Repl.Core package

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

Install the Repl.Core NuGet package using the dotnet CLI. This is the primary dependency-free runtime core without Microsoft.Extensions.* dependencies.

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

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

### Enable MCP server and start command

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

Enable MCP mode by adding a single line to the app. The JSON shows the command and arguments used to start the MCP server.

```csharp
using Repl.Mcp;

app.UseMcpServer();  // add one line
```

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

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

### Install Repl.Defaults package

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

Adds the Repl.Defaults NuGet package to the project.

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

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

### Run MCP server and CLI

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

Commands to start the MCP stdio server and run the app as CLI/interactive REPL. The 'myapp mcp serve' starts a hidden context.

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

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

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

### Test command graph with Repl.Testing

Source: https://github.com/yllibed/repl/blob/main/docs/for-coding-agents.md

Use Repl.Testing to create a test host, open a session, and run a command. This example verifies the exit code and output text for a 'hello' command.

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

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

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

execution.ExitCode.Should().Be(0);
execution.OutputText.Should().Contain("world");
```

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

### Start stdio MCP server without rebuilding

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

Starts the stdio MCP server for the sample app without rebuilding, waiting for an MCP client over stdin/stdout.

```bash
dotnet run --no-build --project samples/08-mcp-server/McpServerSample.csproj -- mcp serve
```

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

### Install Repl package

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

Adds the Repl meta-package to a .NET project, bringing in Repl.Core, Repl.Defaults, and Repl.Protocol.

```bash
dotnet add package Repl
```

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

### Run interactive REPL mode

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

Starts the sample in interactive REPL mode, allowing manual command entry.

```bash
dotnet run --project samples/08-mcp-server/McpServerSample.csproj
```

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

### completion status

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

Prints the current completion setup status including mode, detection, profile paths, profile existence, and install status for each shell. Supports JSON output.

```APIDOC
## completion status

### Description
Prints the current completion setup status including mode, detection, profile paths, profile existence, and install status for each shell. Supports JSON output.

### Method
CLI command

### Endpoint
completion status

### Parameters
#### Flags
- **--json** (boolean) - Optional - Output in JSON format

### Request Example
```
completion status --json
```

### Response
#### Success Response
- **Enabled** (boolean) - Whether completion is enabled
- **Setup mode** (string) - Manual or automatic
- **Detected shell** (string) - Detected shell and reason
- **Bash profile** (string) - Path to bash profile
- **Bash profile exists** (boolean) - Whether bash profile exists
- **Bash installed** (boolean) - Whether bash completion is installed
- **PowerShell profile** (string) - Path to PowerShell profile
- **PowerShell profile exists** (boolean) - Whether PowerShell profile exists
- **PowerShell installed** (boolean) - Whether PowerShell completion is installed
- **Zsh profile** (string) - Path to zsh profile
- **Zsh profile exists** (boolean) - Whether zsh profile exists
- **Zsh installed** (boolean) - Whether zsh completion is installed
- **Fish profile** (string) - Path to fish profile
- **Fish profile exists** (boolean) - Whether fish profile exists
- **Fish installed** (boolean) - Whether fish completion is installed
- **Nushell profile** (string) - Path to Nushell profile
- **Nushell profile exists** (boolean) - Whether Nushell profile exists
- **Nushell installed** (boolean) - Whether Nushell completion is installed

#### JSON Output Fields
- **bashProfilePath** (string) - Path to bash profile
- **bashProfileExists** (boolean) - Whether bash profile exists
- **bashInstalled** (boolean) - Whether bash completion is installed
- **powerShellProfilePath** (string) - Path to PowerShell profile
- **powerShellProfileExists** (boolean) - Whether PowerShell profile exists
- **powerShellInstalled** (boolean) - Whether PowerShell completion is installed
- **zshProfilePath** (string) - Path to zsh profile
- **zshProfileExists** (boolean) - Whether zsh profile exists
- **zshInstalled** (boolean) - Whether zsh completion is installed
- **fishProfilePath** (string) - Path to fish profile
- **fishProfileExists** (boolean) - Whether fish profile exists
- **fishInstalled** (boolean) - Whether fish completion is installed
- **nuProfilePath** (string) - Path to Nushell profile
- **nuProfileExists** (boolean) - Whether Nushell profile exists
- **nuInstalled** (boolean) - Whether Nushell completion is installed

### Response Example
```json
{
  "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
}
```

```

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

### Create test host and run command

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

Shows how to set up an in-memory test host, open a session, and run a command. The host configures a ReplApp with a 'hello' command that returns 'world', then executes 'hello --no-logo' in a new session.

```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");
```

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

### Create host and run first command with ReplTestHost

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

Create a host with ReplTestHost.Create, open a session, and run a command. The app maps "hello" to return "world". Use this as the starting point for any Repl.Testing test.

```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");
```

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

### Assert semantic interaction event with ReplStatusEvent

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

Assert on semantic interaction events. This example checks that exactly one ReplStatusEvent with text "Import started" appears in the execution's InteractionEvents.

```csharp
execution.InteractionEvents
    .OfType<ReplStatusEvent>()
    .Should()
    .ContainSingle(e => string.Equals(e.Text, "Import started", StringComparison.Ordinal));
```

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

### Request structured output with --json flag

Source: https://github.com/yllibed/repl/blob/main/docs/for-coding-agents.md

Use this command to request structured JSON output from the command defined in the previous example. The --json flag is used to get machine-readable output.

```bash
myapp project status 42 --json
```

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

### Build the MCP server sample

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

Builds the sample project once before launching it from MCP Inspector or an agent host.

```bash
dotnet build samples/08-mcp-server/McpServerSample.csproj
```

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

### Discover CLI commands via --help

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

Run the CLI's help commands to discover available commands and their arguments. The first output lists all commands, and the second shows the usage and arguments for the 'add' command. This enables an agent to understand the interface without prior knowledge.

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

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

Arguments:
  name    Full name
  email   Email address
```

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

### Minimal ReplApp with UseDefaultInteractive

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

Creates a REPL app with default interactive profile, maps a 'hello' command to return 'world', and runs it with the provided arguments.

```csharp
using Repl;

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

return app.Run(args);
```

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

### Minimal Repl app

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

Creates a minimal Repl app with default interactive mode, maps a 'hello' command that returns 'world', and runs it with the provided arguments.

```csharp
using Repl;

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

return app.Run(args);
```

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

### completion install

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

Installs shell completion by writing a managed block into the shell profile. Supports bash, powershell, zsh, fish, and nu shells. Use --force to merge if another app manages the Nushell dispatcher block.

```APIDOC
## completion install

### Description
Installs shell completion by writing a managed block into the shell profile. Supports bash, powershell, zsh, fish, and nu shells. Use --force to merge if another app manages the Nushell dispatcher block.

### Method
CLI command

### Endpoint
completion install

### Parameters
#### Flags
- **--shell** (string) - Optional - Shell to install for: bash, powershell, zsh, fish, nu
- **--force** (boolean) - Optional - Force merge for Nushell dispatcher block
- **--silent** (boolean) - Optional - Suppress output
- **--json** (boolean) - Optional - Output in JSON format

### Request Example
```
completion install --shell bash
```

### Response
#### Success Response
No structured response documented.

```

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

### Invalid temporal range validation error

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

Shows the validation error when a temporal range uses a duration that is not a whole day. The command fails with a message explaining the required format: start..end or start@duration with whole days.

```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.
```

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

### Run a sample project with dotnet run

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

Runs the CoreBasicsSample project. Replace the project path with any of the listed sample project paths to run that sample.

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

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

### Minimal Repl.Core app

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

Create a core Repl app, map the "hello" path to return "world", and run with arguments. Requires the Repl using directive; the returned value is the app exit code.

```csharp
using Repl;

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

return app.Run(args);
```

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

### Run MCP server and CLI

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

Shows the two entry points: `myapp mcp serve` for AI agents and `myapp` for the normal CLI/REPL.

```bash
myapp mcp serve   # AI agents connect here
myapp              # still a CLI / interactive REPL
```

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

### Install ExitCodes.Resolver to observe outcome kind and exit code

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

Install a resolver to observe every final outcome kind and exit code. It does not fire for runs that end by propagating an exception or for nested MCP sub-invocations. Return the outcome's exit code to keep the contract unchanged.

```csharp
options.ExitCodes.Resolver = outcome =>
{
    logger.LogInformation(
        "run ended {Kind} → {ExitCode} ({Scope})", outcome.Kind, outcome.ExitCode, outcome.Scope);
    return outcome.ExitCode;   // observe without changing the contract
};
```

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

### WebSocket REPL connection setup

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

Establishes a WebSocket connection to the REPL endpoint, wires up message/close/error handlers, sets the send function, attaches terminal input handler, and on open sends the hello message and an initial VT resize sequence if ResizeReporting is enabled.

```javascript
function connectWS(config) { const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/ws/repl${buildConnectionQuery(config)}`); ws.onmessage = e => writeTerminalOutput(e.data); ws.onclose = ws.onerror = () => { send = null; setConnectionState('disconnected'); resetFeedbackMirror(); term.writeln('\r\n[disconnected]'); }; send = d => { if (ws.readyState === 1) ws.send(d); }; inputHandler = term.onData(send); // Send initial DTTERM size so the VT probe detects it. ws.onopen = () => { setConnectionState('connected'); send(buildHello(config)); if (config.capabilities.includes('ResizeReporting')) { send(`\x1b[8;${term.rows};${term.cols}t`); } term.focus(); }; // DTTERM in-band VT resize sequence.
```

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

### Add Repl.Mcp package

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

Install the Repl.Mcp NuGet package before configuring the MCP server.

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

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

### Use options groups and temporal ranges

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

Try commands that use the reusable options group ([ReplOptionsGroup]) and date-only temporal ranges ([ReplDateRange]). The options group provides --format and --no-verbose, while 'report period' accepts start..end or start@duration literals. ReplDateRange only accepts whole-day durations.

```text
myapp list --format json
myapp show 1 --no-verbose
myapp report period --period 2024-01-15..2024-02-15
myapp report period --period 2024-01-15@30d
```

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

### CoreReplApp setup with delegate routes

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

Single-file C# REPL app without DI. Maps routes directly to delegates, uses type constraints like {id:int} and {email:email}, and returns semantic values (IEnumerable<Contact>, IReplPageSource<ActivityEvent>, Contact, string) that the framework renders appropriately.

```csharp
using System.ComponentModel;
using Repl;
using Repl.Parameters;

var store = new ContactStore();
var commands = new ContactCommands(store);

var app = CoreReplApp.Create()
    .WithDescription("Core basics sample: minimal contacts REPL without DI dependencies.")
    .WithBanner("""
          Try: list, add Alice alice@test.com, show 1, count
          Also: error (exception handling), debug reset
        """);

app.Map("list", commands.List);
app.Map("add {name} {email:email}", commands.Add);
app.Map("show {id:int}", commands.Show);
app.Map("count", commands.Count);
app.Map("activity", commands.Activity);
app.Map("report period", commands.ReportPeriod);
app.Map("error", ErrorCommand);
app.Map("debug reset", commands.Reset);

return app.Run(args);

```

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

### Add Repl.Testing package

Source: https://github.com/yllibed/repl/blob/main/docs/for-coding-agents.md

Install the Repl.Testing NuGet package to enable testing of command behavior.

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

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

### Create help document and MCP tool descriptor

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

Creates a help document with a single command and projects it to an MCP tool descriptor using ProtocolContracts.

```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]);
```

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

### Manual completion setup for Bash, PowerShell, Fish, and Nushell

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

Manual shell completion setup for Bash, PowerShell, Fish, and Nushell. Each block registers a completer that invokes `myapp completion __complete` with the appropriate shell flag and forwards the result. The PowerShell block includes a fallback for older PowerShell versions and the Nushell block enables external completions in the config.

```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

```

```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'
    }

    # Rebuild the line and pad it to the cursor: $commandAst drops trailing
    # whitespace, so an empty value position ('myapp deploy ') would otherwise be
    # analyzed as the previous token.
    $replLine = $commandAst.Extent.Text
    $replCursor = $cursor - $commandAst.Extent.StartOffset
    if ($replCursor -lt 0) { $replCursor = 0 }
    if ($replLine.Length -lt $replCursor) { $replLine = $replLine.PadRight($replCursor) }

    & $invokedCommand completion __complete --shell powershell --line $replLine --cursor $replCursor --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
}

```

```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)"

```

```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 }

```

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

### Multi-session test scenario with ReplTestHost

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

Shows a 30-second tour of Repl.Testing: create a host, open two sessions with different transports, run commands, and assert on exit codes, output text, and typed results. Uses AAA-style tests and requires a SampleReplApp with a shared context.

```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");
```
Tokens:
Raw