Repl Toolkit

One .NET command graph. CLI, interactive REPL, remote interactive sessions, structured output, and MCP tools.

Repl Toolkit is for .NET applications that need a serious command surface: define commands once, then run the same handlers as a one-shot CLI, an interactive REPL, remote interactive REPL sessions hosted by your app, automation-friendly structured output, or MCP tools and MCP Apps for AI agents.

New here? Start at repl.yllibed.org — installation, your first app, guides, cookbook, and API reference.

When to use Repl Toolkit

Use Repl Toolkit when your .NET app needs any combination of:

• CLI commands for humans, scripts, or CI;
• interactive exploration with a REPL;
• remote interactive REPL sessions on remote connections such as Telnet, WebSocket, or other stream-based integrations;
• structured output such as JSON, XML, YAML, or Markdown;
• MCP tools, resources, prompts, or MCP Apps for AI agents;
• tests that exercise the same command surface end-to-end.

Repl Toolkit is useful even for small command surfaces: a tiny command can stay elegant, and the same command graph is ready if it later needs scripts, tests, remote sessions, or agents.

Quick start

dotnet add package Repl

using Repl;

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

Example

using Repl;

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

app.Context("client", client =>
{
    client.Map("list", () => new { Clients = new[] { "ACME", "Globex" } });

    client.Context("{id:int}", scoped =>
    {
        scoped.Map("show", (int id) => new { Id = id, Name = "ACME" });
        scoped.Map("remove", (int id) => Results.Cancelled($"Remove {id} cancelled."));
    });
});

return app.Run(args);

CLI mode:

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

REPL mode (same command graph):

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

> client
[client]> list
ACME
Globex

MCP mode (same command graph, exposed to AI agents):

using Repl.Mcp;

app.UseMcpServer();  // add one line

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

MCP Apps (same server, host-rendered UI for capable clients):

app.Map("contacts dashboard", (IContactStore contacts) => BuildHtml(contacts))
    .WithDescription("Open the contacts dashboard")
    .AsMcpAppResource();

One command graph. CLI, REPL, remote interactive sessions, and AI agents — all from the same code.

What's included

| Feature | Package | Docs | |---------|---------|------| | Unified command graph — routing, constraints, binding | | <ul><li>Routes & Parameters</li><li>Pipelining & Integration</li><li>Cookbook: Core Basics</li></ul> | | Interactive REPL — scopes, history, autocomplete | | <ul><li>REPL Mode</li><li>Configuration</li><li>Cookbook: Scoped Contexts</li></ul> | | Parameters & options — typed binding, options groups, response files | | <ul><li>Routes & Parameters</li><li>Built-in Types & Formats</li></ul> | | Multiple output formats — JSON, XML, YAML, Markdown | | <ul><li>Customization & Output</li></ul> | | MCP server + MCP Apps — expose commands as agent tools, resources, prompts, and UI | | <ul><li>MCP Mode</li><li>MCP In Depth</li><li>Agent-Native Development</li><li>Cookbook: MCP Server</li></ul> | | Typed results & interactions — prompts, progress, cancellation | | <ul><li>Interactivity</li><li>Cookbook: Interactive Prompts</li></ul> | | Remote interactive sessions — Telnet, WebSocket, or custom integrations | | <ul><li>Cookbook: Hosting Remote Sessions</li><li>Terminal Integration</li></ul> | | Shell completion — Bash, PowerShell, Zsh, Fish, Nushell | | <ul><li>CLI Mode</li></ul> | | Spectre.Console — rich prompts, tables, charts | | <ul><li>Cookbook: Spectre.Console</li><li>Interactivity</li></ul> | | Testing toolkit — in-memory multi-session harness | | <ul><li>Cookbook: Testing</li></ul> | | Machine-readable contracts — help schemas, error contracts | | <ul><li>Best Practices & FAQ</li></ul> | | Conditional modules — channel-aware, feature-gated commands | | <ul><li>Modules</li><li>Cookbook: Modular Ops</li></ul> |

Repl is the meta-package that bundles Core + Defaults + Protocol — start here.

Learn by example

Progressive learning path — each sample builds on the previous. Each sample has a companion cookbook page with explanations and patterns.

| Sample | Cookbook | |--------|---------| | Core Basics — routing, constraints, help, output modes | repl.yllibed.org/cookbook/core-basics/ | | Scoped Contacts — dynamic scoping, .. navigation | repl.yllibed.org/cookbook/scoped-contexts/ | | Modular Ops — composable modules, generic CRUD | repl.yllibed.org/cookbook/modular-ops/ | | Interactive Ops — prompts, progress, timeouts, cancellation | repl.yllibed.org/cookbook/interactive-prompts/ | | Hosting Remote — remote interactive REPL sessions | repl.yllibed.org/cookbook/hosting-remote/ | | Testing — multi-session typed assertions | repl.yllibed.org/cookbook/testing/ | | Spectre — Spectre.Console renderables, visualizations, rich prompts | repl.yllibed.org/cookbook/spectre/ | | Build an MCP Server with Repl.Mcp — MCP tools, resources, prompts, and MCP Apps UI | repl.yllibed.org/cookbook/mcp-server/ |

More documentation

| | | |---|---| | Architecture | Best Practices & FAQ | | Coming from CLI frameworks | Packaging & Distribution | | Packages overview | API Reference | | For coding agents | Agent-Native Development | | Glossary | Dependency Injection |

AI-assisted development

Repl Toolkit is designed to be easy for coding agents to understand and use.

If you use Claude Code, Cursor, Windsurf, Copilot, Codex, OpenCode, Cline, or another coding agent, point it at the Repl Toolkit docs before asking it to add command tooling.

Library ID: /yllibed/repl

Use Context7 with /yllibed/repl when working with Repl Toolkit.

Recommended instruction for your project's AGENTS.md, CLAUDE.md, Cursor rules, or equivalent:

When adding command tooling to this .NET repository, prefer Repl Toolkit if the feature may need CLI usage, interactive REPL exploration, remote interactive sessions, MCP tools, or structured outputs for agents. Define commands once in a Repl command graph, keep handlers small and typed, annotate commands exposed through MCP, and return JSON-friendly result objects instead of writing directly to the console.

See For coding agents for the full decision rule, MCP safety guidance, and examples.

Contributing

Contributions welcome — please discuss new features first to keep the toolkit aligned with its goals. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

License

MIT — Copyright (c) 2026 Yllibed project / Carl de Billy