TimeWarp.Nuru

Route-based CLI framework for .NET - bringing web-style routing to command-line applications

Nuru means "light" in Swahili - illuminating the path to your commands with clarity and simplicity.

📦 Installation

dotnet add package TimeWarp.Nuru

🚀 Quick Start

TimeWarp.Nuru offers two patterns for defining CLI commands. Start with the Endpoint DSL for structured apps, or Fluent DSL for quick scripts.

Endpoint DSL

Define routes as classes with [NuruRoute] attributes:

usingTimeWarp.Nuru;[NuruRoute("add",Description="Add two numbers together")]publicsealedclassAddCommand:ICommand<Unit>{[Parameter(Order=0)]publicdoubleX{get;set;}[Parameter(Order=1)]publicdoubleY{get;set;}publicsealedclassHandler:ICommandHandler<AddCommand,Unit>{publicValueTask<Unit>Handle(AddCommandcommand,CancellationTokenct){Console.WriteLine($"{command.X} + {command.Y} = {command.X+command.Y}");returndefault;}}}// In your main file:NuruAppapp=NuruApp.CreateBuilder().DiscoverEndpoints().Build();returnawaitapp.RunAsync(args);

Fluent DSL

Define routes inline with a fluent builder API:

usingTimeWarp.Nuru;NuruAppapp=NuruApp.CreateBuilder().Map("add {x:double} {y:double}").WithHandler((doublex,doubley)=>Console.WriteLine($"{x} + {y} = {x+y}")).AsCommand().Done().Build();returnawaitapp.RunAsync(args);

dotnet run -- add 15 25
# Output: 15 + 25 = 40

→ Full Getting Started Guide

✨ Key Features

Feature	Description	Learn More
🎯 Web-Style Routing	Familiar "deploy {env} --version {tag}" syntax	Routing Guide
📦 Endpoint DSL	Class-based commands with DiscoverEndpoints() auto-discovery	Architecture Choices
🔧 Fluent DSL	Inline routes with .Map().WithHandler().Done() chain	Architecture Choices
🛡️ Roslyn Analyzer	Catch route errors at compile-time	Analyzer Docs
⌨️ Shell Completion	Tab completion for bash, zsh, PowerShell, fish	Shell Completion
🤖 MCP Server	AI-assisted development with Claude	MCP Server Guide
📊 Logging Package	Zero-overhead structured logging	Logging Docs
🚀 Native AOT	Zero warnings, 3.3 MB binaries, instant startup	Deployment Guide
🔒 Type-Safe Parameters	Automatic type conversion and validation	Supported Types
📖 Auto-Help	Generate help from route patterns	Auto-Help Feature
🎨 Rich Terminal	Colors, tables, panels, rules via TimeWarp.Terminal	Terminal Guide

📚 Documentation

Getting Started

• Getting Started Guide - Build your first CLI app in 5 minutes
• Use Cases - Greenfield apps & progressive enhancement patterns
• Architecture Choices - Choose Endpoint DSL or Fluent DSL

Core Features

• Routing Patterns - Complete route syntax reference
• Roslyn Analyzer - Compile-time validation
• Logging System - Structured logging setup
• Auto-Help - Automatic help generation
• Output Handling - stdout/stderr best practices
• Terminal Abstractions - Testable I/O & colored output

Tools & Deployment

• MCP Server - AI-powered development assistance
• Deployment Guide - Native AOT, runfiles, distribution
• Best Practices - Patterns for maintainable CLIs

Reference

• Performance Benchmarks - Detailed performance metrics
• Supported Types - Complete type reference
• API Documentation - Technical reference

🎯 Two Powerful Use Cases

🆕 Greenfield CLI Applications

Build modern command-line tools from scratch:

myapp/
├── calculator.cs # Single runfile - just 5 lines
└── endpoints/
├── add-command.cs
├── factorial-command.cs
└── ...

Endpoint DSL approach (class-based, organized by file):

// In endpoints/add-command.cs[NuruRoute("add",Description="Add two numbers")]publicsealedclassAddCommand:ICommand<Unit>{[Parameter]publicdoubleX{get;set;}[Parameter]publicdoubleY{get;set;}publicsealedclassHandler:ICommandHandler<AddCommand,Unit>{publicValueTask<Unit>Handle(AddCommandc,CancellationTokenct){Console.WriteLine($"{c.X} + {c.Y} = {c.X+c.Y}");returndefault;}}}

Fluent DSL approach (inline definitions):

NuruApp.CreateBuilder().Map("deploy {env} --version {tag?}").WithHandler((stringenv,string?tag)=>Deploy(env,tag)).AsCommand().Done().Build();

🔄 Progressive Enhancement

Wrap existing CLIs to add auth, logging, or validation:

NuruAppapp=NuruApp.CreateBuilder(args).Map("deploy prod").WithHandler(async()=>{if(!awaitValidateAccess())return1;returnawaitShell.ExecuteAsync("existing-cli","deploy","prod");}).AsCommand().Done().Map("{*args}").WithHandler(async(string[]args)=>awaitShell.ExecuteAsync("existing-cli",args)).AsCommand().Done().Build();

→ Detailed Use Cases with Examples

🌟 Working Examples

Calculator Samples - Three complete implementations you can run now:

• 01-calc-endpoints.cs - Endpoint DSL pattern (testable, DI)
• 02-calc-fluent.cs - Fluent DSL approach (inline handlers)
• 03-calc-mixed.cs - Mixed approach (both patterns together)

./samples/02-calculator/01-calc-endpoints.cs add 10 20 # Endpoint DSL: structured
./samples/02-calculator/02-calc-fluent.cs factorial 5 # Fluent DSL: inline

AOT Example - Native AOT compilation with source generators

⚡ Performance

Implementation	Memory	Speed (37 tests)	Binary Size
Direct (JIT)	~4 KB	2.49s	N/A
Direct (AOT)	~4 KB	0.30s 🚀	3.3 MB
Endpoints (AOT)	Moderate	0.42s 🚀	4.8 MB

Native AOT is 88-93% faster than JIT → Full Performance Benchmarks

🤖 AI-Powered Development

For AI agents: Load the built-in Nuru Skill for instant access to:

• Complete DSL syntax and patterns
• Testing with TestTerminal
• Route examples and type conversion

💡 Tip: No MCP installation needed - the skill provides all essential patterns.

For MCP Server: Install for Claude Code, Roo Code, or Continue:

dotnet tool install --global TimeWarp.Nuru.Mcp

Get instant help:

• Validate route patterns before writing code
• Generate handler code automatically
• Get syntax examples on demand
• Real-time error guidance

→ MCP Server Setup Guide

⌨️ Shell Completion

Enable tab completion for your CLI with one line of code:

NuruAppapp=NuruApp.CreateBuilder(args).Map("deploy {env} --version {tag}").WithHandler((stringenv,stringtag)=>Deploy(env,tag)).AsCommand().Done().Map("status").WithHandler(()=>ShowStatus()).AsQuery().Done().EnableStaticCompletion()// ← Add this.Build();

Generate completion scripts for your shell:

# Bash
./myapp --generate-completion bash >>~/.bashrc
# Zsh
./myapp --generate-completion zsh >>~/.zshrc
# PowerShell
./myapp --generate-completion powershell >>$PROFILE# Fish
./myapp --generate-completion fish >~/.config/fish/completions/myapp.fish

Supports:

• ✅ Command completion (deploy, status)
• ✅ Option completion (--version, --force)
• ✅ Short option aliases (-v, -f)
• ✅ All 4 major shells (bash, zsh, PowerShell, fish)

See completion-example for a complete working example.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

For Contributors:

• Developer Documentation - Architecture and design
• Standards - Coding conventions
• Releasing Guide - How we cut and publish releases

📄 License

This project is licensed under the Unlicense - see the license file for details.

---

Ready to build powerful CLI applications?

Get Started in 5 Minutes • View Examples • Read the Docs