Repl Toolkit

Map your commands like ASP.NET Core routes. Run them as a CLI tool, an interactive REPL, hosted sessions, or MCP tools for AI agents — all from the same code.

Get Started View on GitHub

One graph. Every surface.

Familiar minimal-API style

app.Map("user {id:int}", handler) — typed routes, constraints, parameter binding, and structured output. If you’ve used ASP.NET Core minimal APIs, you already know the pattern.

CLI + REPL from the same graph

Pass arguments and you have a one-shot CLI invocation from your shell — --json, --xml, --yaml output and --help at every level. Skip the arguments and you have a read-eval-print loop instead: type a command, see the result, repeat — with scoped navigation, history, and autocomplete.

Hosted sessions

The same command surface runs over any text-based session transport. Multiple concurrent sessions, each with its own scope. Repl.WebSocket and Repl.Telnet are built-in implementations; any transport that delivers a stream pair works.

Full-fledged MCP server in one line

app.UseMcpServer() exposes every command over the Model Context Protocol — the open standard AI assistants like Claude use to discover and call tools. State-of-the-art coverage: tools, resources, prompts, and MCP Apps (ui://) — all generated from the same command graph, with behavioral hints derived from your route annotations.

Zero-dependency core

Repl.Core has zero NuGet dependencies. Build embedded command surfaces in strict environments. Compose only what you need.

Every interaction path, testable

Repl.Testing runs your full command graph in memory — multi-session, multi-step, with a typed assertion API. Prompts, scoped navigation, and MCP tools — all verifiable without a real terminal, with no hidden I/O. Production confidence by dotnet test.

Production-grade by default

Repl is a complete command surface toolkit. It implements the working CLI guidelines from clig.dev — the de facto reference for modern command-line tools — out of the box, then extends them for the era of AI agents and multi-channel automation.

What clig.dev asks for, you already have

--help at every level — root, contexts, individual commands, with examples
Machine-readable output — --json, --xml, --yaml, --markdown on every command
Color discipline — NO_COLOR, CLICOLOR_FORCE, and TERM=dumb honored without configuration
TTY-aware — progress bars, prompts, and styling adapt automatically to redirected output and CI
Forgiving input — prefix matching (co li → contact list), unique disambiguation, “Did you mean?” suggestions on typos
Two-tap Ctrl+C — first tap interrupts work, second tap exits, exactly as the guidelines prescribe
Shell completion — Bash, PowerShell, Zsh, Fish, and Nushell adapters generated from your command graph
Response files — @args.rsp for long invocations, ready for CI scripts
Structured exit codes — 0 for success, distinct codes for usage, validation, and runtime failures

What clig.dev couldn't predict

First-class MCP server — tools, resources (repl://), prompts, and MCP Apps (ui://) generated from the same routes
Behavioral annotations — .ReadOnly(), .Destructive(), .Idempotent(), .LongRunning() propagate into MCP hints and shape interactive confirmations
In-memory test harness — Repl.Testing runs the full graph (prompts, scoped navigation, multi-step sessions) without a terminal
Hosted remote sessions — the same graph served over WebSocket, Telnet, or any stream pair, with per-session DI scope
Channel-aware interactivity — prompts degrade automatically when stdin is redirected, when running under MCP, or in non-interactive transports
Conditional modules — register surfaces based on environment, license, or runtime detection without restructuring code

Quick start

dotnet add package Repl

using Repl;

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

app.Context("client", client =>
{
    client.Map("list", (IClientStore store) => store.All());

    client.Context("{id:int}", scoped =>
    {
        scoped.Map("show", (int id, IClientStore store) => store.Get(id));
        scoped.Map("remove", (int id, IClientStore store) =>
        {
            store.Remove(id);
            return Results.Success($"Removed {id}.");
        });
    });
});

return app.Run(args);

$ myapp client list --json
[{ "id": 1, "name": "ACME" }, { "id": 2, "name": "Globex" }]

$ myapp client 42 show
Id:   42
Name: ACME

$ myapp client --help
Commands:
  client list
  client {id} show
  client {id} remove

$ myapp
> client
[client]> list
ACME  (1)
Globex  (2)

[client]> 42
[client/42]> show
Id:   42
Name: ACME

[client/42]> ..
[client]>

using Repl.Mcp;
app.UseMcpServer();  // every Map(...) becomes an MCP tool

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

Every command is now discoverable as an MCP tool — the AI agent calls client list, client 42 show, etc. directly.

Built for the age of AI agents

The most expensive part of autonomous agent development isn’t writing code — it’s the feedback loop. Screenshots consume tokens. HTML parsing is fragile. Visual context is slow to reason about.

A Repl command surface removes the need for it in agent workflows.

# The agent discovers everything from one command
$ myapp --help --json
# → full command tree, parameter schemas, descriptions

# The agent calls commands and reads structured results
$ myapp contacts add "Alice Dupont" alice@example.com --json
# → { "id": 1, "name": "Alice Dupont" }

# The agent verifies behavior with Repl.Testing — in memory, no terminal needed
# → full multi-step interaction sequences with typed assertions

When the command surface is complete, the application is complete. The business logic is implemented, tested, and working. Adding a web UI, a full-screen terminal app (TUI), or a desktop front-end is the last step — layered on top of a command surface that is already fully tested and working. By then, the real work is done.

Where to go next

Getting Started

Install the package, write your first app, and understand the three execution modes in 10 minutes.

Start here →

Cookbook

Eight recipes from core routing to MCP servers, each backed by a full runnable sample.

Browse recipes →

Concepts

Routes, modules, DI, MCP, interactivity, output, pipelines, and terminal integration.

Read the docs →

API Reference

Complete generated API reference from the Repl.* assemblies.

Browse API →

The full story

Start with dotnet add package Repl. That single package gives you routing, typed parameter binding, an interactive REPL, CLI dispatch, and JSON/XML/YAML/Markdown output — no other dependencies required.

When your users need AI-agent access, add Repl.Mcp and call app.UseMcpServer(). Every command becomes an MCP tool with no handler changes. Add Repl.Spectre to upgrade all output and prompts to Spectre.Console richness — again, zero handler changes. The whole stack honors standard guidelines by default, so your CLI behaves the way operators, scripts, and CI pipelines expect.

Test the whole thing with Repl.Testing: an in-memory harness that runs full multi-step interaction sequences, including prompts and scoped navigation, with typed assertions.

If you’re embedding Repl in a constrained environment, Repl.Core is the zero-dependency foundation — pull only what you need.