Route-based CLI framework for .NET - batteries included with telemetry, REPL, and shell completion

Install

dotnet add package TimeWarp.Nuru
dotnet add package TimeWarp.Nuru --prerelease

NuGet · Source · Part of the timewarp-nuru family

TimeWarp.Nuru

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:

using TimeWarp.Nuru;

[NuruRoute("add", Description = "Add two numbers together")]
public sealed class AddCommand : ICommand<Unit>
{
  [Parameter(Order = 0)] public double X { get; set; }
  [Parameter(Order = 1)] public double Y { get; set; }

  public sealed class Handler : ICommandHandler<AddCommand, Unit>
  {
    public ValueTask<Unit> Handle(AddCommand command, CancellationToken ct)
    {
      Console.WriteLine($"{command.X} + {command.Y} = {command.X + command.Y}");
      return default;
    }
  }
}

// In your main file:
NuruApp app = NuruApp.CreateBuilder()
  .DiscoverEndpoints()
  .Build();

return await app.RunAsync(args);

Fluent DSL

Define routes inline with a fluent builder API:

using TimeWarp.Nuru;

NuruApp app = NuruApp.CreateBuilder()
  .Map("add {x:double} {y:double}")
    .WithHandler((double x, double y) => Console.WriteLine($"{x} + {y} = {x + y}"))
    .AsCommand()
    .Done()
  .Build();

return await app.RunAsync(args);

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

→ Full Getting Started Guide

✨ Key Features

📚 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")]
public sealed class AddCommand : ICommand<Unit>
{
  [Parameter] public double X { get; set; }
  [Parameter] public double Y { get; set; }

  public sealed class Handler : ICommandHandler<AddCommand, Unit>
  {
    public ValueTask<Unit> Handle(AddCommand c, CancellationToken ct)
    {
      Console.WriteLine($"{c.X} + {c.Y} = {c.X + c.Y}");
      return default;
    }
  }
}

Fluent DSL approach (inline definitions):

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

🔄 Progressive Enhancement

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

NuruApp app = NuruApp.CreateBuilder(args)
  .Map("deploy prod")
    .WithHandler(async () =>
    {
      if (!await ValidateAccess()) return 1;
      return await Shell.ExecuteAsync("existing-cli", "deploy", "prod");
    })
    .AsCommand()
    .Done()
  .Map("{*args}")
    .WithHandler(async (string[] args) => await Shell.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

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:

NuruApp app = NuruApp.CreateBuilder(args)
  .Map("deploy {env} --version {tag}")
    .WithHandler((string env, string tag) => 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

📄 License

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