https://github.com/yllibed/repl
Repl Toolkit is a foundational building block for .NET applications that need a serious command surface.
https://github.com/yllibed/repl
Last synced: about 1 month ago
JSON representation
Repl Toolkit is a foundational building block for .NET applications that need a serious command surface.
- Host: GitHub
- URL: https://github.com/yllibed/repl
- Owner: yllibed
- License: mit
- Created: 2026-02-24T16:02:50.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-20T20:13:23.000Z (about 1 month ago)
- Last Synced: 2026-04-20T22:18:28.016Z (about 1 month ago)
- Language: C#
- Homepage:
- Size: 1.25 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Repl Toolkit
[](https://www.nuget.org/packages/Repl)
[](https://www.nuget.org/packages/Repl)
[](https://github.com/yllibed/repl/actions/workflows/ci.yml)
[](LICENSE)
[](https://deepwiki.com/yllibed/repl)
**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 and MCP Apps for AI agents,
- or drive them from automation scripts.
> **New here?** The [DeepWiki](https://deepwiki.com/yllibed/repl) has full architecture docs, diagrams, and an AI assistant you can ask questions about the toolkit.
## Quick start
```bash
dotnet add package Repl
```
```csharp
using Repl;
var app = ReplApp.Create().UseDefaultInteractive();
app.Map("hello", () => "world");
return app.Run(args);
```
## Example
```csharp
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:**
```text
$ myapp client list --json
{
"clients": ["ACME", "Globex"]
}
```
**REPL mode** (same command graph):
```text
$ myapp
> client 42 show --json
{ "id": 42, "name": "ACME" }
> client
[client]> list
ACME
Globex
```
**MCP mode** (same command graph, exposed to AI agents):
```csharp
using Repl.Mcp;
app.UseMcpServer(); // add one line
```
```json
{ "command": "myapp", "args": ["mcp", "serve"] }
```
**MCP Apps** (same server, host-rendered UI for capable clients):
```csharp
app.Map("contacts dashboard", (IContactStore contacts) => BuildHtml(contacts))
.WithDescription("Open the contacts dashboard")
.AsMcpAppResource();
```
One command graph. CLI, REPL, remote sessions, and AI agents — all from the same code.
## What's included
| Feature | Package | Guides |
|---------|---------|--------|
| Unified command graph — routing, constraints, binding | [](https://www.nuget.org/packages/Repl.Core) |
- [Route system](docs/route-system.md)
- [Execution pipeline](docs/execution-pipeline.md)
- [Commands](docs/commands.md)
| Interactive REPL — scopes, history, autocomplete | [](https://www.nuget.org/packages/Repl.Defaults) |
- [Interactive loop](docs/interactive-loop.md)
- [Configuration](docs/configuration-reference.md)
| Parameters & options — typed binding, options groups, response files | [](https://www.nuget.org/packages/Repl.Core) |
- [Parameter system](docs/parameter-system.md)
- [Route system](docs/route-system.md)
| Multiple output formats — JSON, XML, YAML, Markdown | [](https://www.nuget.org/packages/Repl.Core) |
- [Output system](docs/output-system.md)
| MCP server + MCP Apps — expose commands as agent tools, resources, prompts, and UI | [](https://www.nuget.org/packages/Repl.Mcp) |
- [MCP overview](docs/mcp-overview.md)
- [MCP reference](docs/mcp-reference.md)
- [MCP advanced](docs/mcp-advanced.md)
- [MCP sample](samples/08-mcp-server/)
| Typed results & interactions — prompts, progress, cancellation | [](https://www.nuget.org/packages/Repl.Core) |
- [Interaction channel](docs/interaction.md)
| Session hosting — WebSocket, Telnet, remote terminals | [](https://www.nuget.org/packages/Repl.WebSocket) [](https://www.nuget.org/packages/Repl.Telnet) |
- [Runtime channels](docs/runtime-channels.md)
- [Terminal metadata](docs/terminal-metadata.md)
| Shell completion — Bash, PowerShell, Zsh, Fish, Nushell | [](https://www.nuget.org/packages/Repl.Core) |
- [Shell completion](docs/shell-completion.md)
| Spectre.Console — rich prompts, tables, charts | [](https://www.nuget.org/packages/Repl.Spectre) |
- [Interaction channel](docs/interaction.md)
- [Sample](samples/07-spectre/)
| Testing toolkit — in-memory multi-session harness | [](https://www.nuget.org/packages/Repl.Testing) |
- [Testing toolkit](docs/testing-toolkit.md)
| Machine-readable contracts — help schemas, error contracts | [](https://www.nuget.org/packages/Repl.Protocol) |
- [Help system](docs/help-system.md)
| Conditional modules — channel-aware, feature-gated commands | [](https://www.nuget.org/packages/Repl.Core) |
- [Module presence](docs/module-presence.md)
[**`Repl`**](https://www.nuget.org/packages/Repl) is the meta-package that bundles Core + Defaults + Protocol — **start here**.
## Learn by example
Progressive learning path — each sample builds on the previous:
1. **[Core Basics](samples/01-core-basics/)** — routing, constraints, help, output modes
2. **[Scoped Contacts](samples/02-scoped-contacts/)** — dynamic scoping, `..` navigation
3. **[Modular Ops](samples/03-modular-ops/)** — composable modules, generic CRUD
4. **[Interactive Ops](samples/04-interactive-ops/)** — prompts, progress, timeouts, cancellation
5. **[Hosting Remote](samples/05-hosting-remote/)** — WebSocket / Telnet session hosting
6. **[Testing](samples/06-testing/)** — multi-session typed assertions
7. **[Spectre](samples/07-spectre/)** — Spectre.Console renderables, visualizations, rich prompts
8. **[MCP Server](samples/08-mcp-server/)** — expose commands as MCP tools, resources, prompts, and a minimal MCP Apps UI
## More documentation
| | |
|---|---|
| [Architecture blueprint](docs/architecture.md) | [Best practices](docs/best-practices.md) |
| [Comparison & migration](docs/comparison.md) | [Publishing & deployment](docs/publishing.md) |
| [Glossary](docs/glossary.md) | [Interactive docs & AI Q&A](https://deepwiki.com/yllibed/repl) |
## AI-assisted development
If you use an AI coding agent (Claude Code, Cursor, Windsurf, Copilot, Codex, OpenCode, etc.) to build your Repl Toolkit app, install [Context7](https://context7.com) to give it access to Repl Toolkit documentation and code snippets.
**Library ID:** `/yllibed/repl`
Most agents that support [MCP](https://modelcontextprotocol.io/) can use Context7 directly. Refer to your agent's documentation for MCP server configuration.
> You can also explore the toolkit architecture and ask questions on [DeepWiki](https://deepwiki.com/yllibed/repl).
## Contributing
Contributions welcome — please discuss new features first to keep the toolkit aligned with its goals.
See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`SECURITY.md`](SECURITY.md).
## License
[MIT](LICENSE) — Copyright (c) 2026 Yllibed project / Carl de Billy