Repl Toolkit

A .NET framework for building composable command surfaces.

• Define your commands once — run them as a CLI, explore them in an interactive REPL,
• host them in session-based terminals, expose them as MCP servers for AI agents,
• or drive them from automation scripts.

New here? The DeepWiki has full architecture docs, diagrams, and an AI assistant you can ask questions about the toolkit.

Quick start

dotnet add package Repl

using Repl;

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

Features

• Unified command graph — one route map shared by CLI, REPL, and hosted sessions
• POSIX-like semantics — familiar flag syntax, -- separator, predictable parsing
• Hierarchical scopes — stateful navigation with .., contexts, route constraints ({id:int}, {when:date})
• Multiple output formats — --json, --xml, --yaml, --markdown, or --human
• MCP server — expose your commands as tools for AI agents with app.UseMcpServer() — zero boilerplate
• AI/agent-friendly — machine-readable contracts, deterministic outputs, pre-answered prompts (--answer:*)
• Typed results — Ok, Error, NotFound, Cancelled with payloads — not raw strings
• Typed interactions — prompts, progress, status, timeouts, cancellation
• Session-aware DI — per-session services and metadata (transport, terminal, window size)
• Hosting primitives — run sessions over WebSocket, Telnet, or custom carriers
• Shell completion — Bash, PowerShell, Zsh, Fish, Nushell with auto-install
• Testing toolkit — in-memory multi-session harness with typed assertions
• Cross-platform — same behavior on Windows, Linux, macOS, containers, and CI

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):

app.UseMcpServer();  // add one line

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

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

Packages

Package	Description
Repl	Meta-package — bundles Core + Defaults + Protocol (start here)
Repl.Core	Runtime: routing, parsing, binding, results, help, middleware
Repl.Defaults	DI, host composition, interactive mode, terminal UX
Repl.Protocol	Machine-readable contracts (help, errors, tool schemas)
Repl.WebSocket	Session hosting over WebSocket
Repl.Telnet	Telnet framing, negotiation, session adapters
Repl.Mcp	MCP server: expose commands as AI agent tools, resources, and prompts
Repl.Spectre	Spectre.Console integration: rich prompts, IAnsiConsole, table rendering
Repl.Testing	In-memory multi-session test harness

Samples

Progressive learning path — start with 01:

1. Core Basics — routing, constraints, help, output modes
2. Scoped Contacts — dynamic scoping, .. navigation
3. Modular Ops — composable modules, generic CRUD
4. Interactive Ops — prompts, progress, timeouts, cancellation
5. Hosting Remote — WebSocket / Telnet session hosting
6. Testing — multi-session typed assertions
7. Spectre — Spectre.Console renderables, visualizations, rich prompts
8. MCP Server — expose commands as MCP tools for AI agents

Documentation

Topic	Link
Architecture blueprint	docs/architecture.md
Command reference	docs/commands.md
Parameter system	docs/parameter-system.md
Terminal & session metadata	docs/terminal-metadata.md
Testing toolkit	docs/testing-toolkit.md
Shell completion	docs/shell-completion.md
Comparison & migration	docs/comparison.md
Interaction channel	docs/interaction.md
MCP server (AI agents)	docs/mcp-server.md
Conditional module presence	docs/module-presence.md
Publishing & deployment	docs/publishing.md
Interactive docs & AI Q&A	deepwiki.com/yllibed/repl

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