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, or drive them from automation and AI agents.

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

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

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