Alveus Contour

A modern, lightweight framework for building command-line applications in C#. Alveus.Contour provides an intuitive attribute-based API for defining commands, supports middleware pipelines, includes a built-in REPL, and is fully AOT-compatible.

Features

• Attribute-based command definition - Use simple attributes to declare commands, subcommands, options, flags, and parameters
• Middleware pipeline - Wrap command execution with cross-cutting concerns (logging, validation, initialization)
• Global options - Define options available across all commands
• Built-in REPL - Interactive mode with command history, auto-completion, and customizable prompts
  • Intelligent auto-completion - Tab completion for commands, subcommands, options, and flags
  • Syntax highlighting - Real-time color highlighting of commands, subcommands, and options as you type
  • Command history - Navigate previous commands with arrow keys and recall with !<number> syntax
  • Configurable history - Option to save only successful commands
  • Environment variable expansion - Support for Bash, CMD, and PowerShell variable syntax
• Dependency injection - Built on Microsoft.Extensions.DependencyInjection
• Theming system - Customize colors and styles throughout the application with built-in themes or create your own
• Extensible help system - Customize help output with custom providers
• Version handling - Display version information with custom providers or inline delegates
• AOT-ready - Full support for Native AOT compilation
• Spectre.Console integration - Rich terminal output with colors, tables, and panels

Requirements

• .NET 10.0 SDK or later

Quick Start

Installation

dotnet add package Alveus.Contour

Basic Usage

using Alveus.Contour; var builder = new ContourBuilder(); // Register commands builder.AddCommand<MyCommand>(); // Configure the app var app = builder.Build(); return app.Run(args);

Defining a Command

using Alveus.Contour.Attributes; [Command("greet", Description = "Greets a person")] public class GreetCommand { [DefaultHandler] public int Execute( [Parameter(0, Description = "Name to greet")] string name, [Flag("formal", ShortName = "f", Description = "Use formal greeting")] bool formal) { var greeting = formal ? $"Good day, {name}" : $"Hi, {name}!"; Console.WriteLine(greeting); return 0; } } $ myapp greet Alice Hi, Alice! $ myapp greet Alice --formal Good day, Alice

Core Concepts

Commands

Commands are defined using the [Command] attribute on a class. Each command can have multiple handlers for subcommands.

[Command("git", Description = "Version control operations")] public class GitCommand { [DefaultHandler] public int Default() { Console.WriteLine("Usage: git <command>"); return 0; } [Subcommand("status", Description = "Show working tree status")] public int Status() { // Implementation return 0; } [Subcommand("commit", Description = "Record changes to the repository")] public int Commit( [Option("message", ShortName = "m", Description = "Commit message", Required = true)] string message) { // Implementation return 0; } }

Global Options

Global options are available across all commands:

public class AppGlobalOptions { [Flag("verbose", Description = "Enable verbose output")] public bool Verbose { get; set; } [Option("config", ShortName = "c", Description = "Configuration file path")] public string? ConfigPath { get; set; } } // Register in builder builder.UseGlobalOptions<AppGlobalOptions>(); // Access in commands via dependency injection [Command("build")] public class BuildCommand { private readonly AppGlobalOptions _options; public BuildCommand(AppGlobalOptions options) { _options = options; } [DefaultHandler] public int Execute() { if (_options.Verbose) Console.WriteLine("Verbose mode enabled"); return 0; } }

Middleware

Middleware wraps command execution with cross-cutting concerns like logging, validation, or initialization:

// Class-based middleware public class LoggingMiddleware : ICommandMiddleware { public int Execute(CommandContext context, Func<int> next) { Console.WriteLine($"Executing: {context.Arguments.Command}"); var result = next(); Console.WriteLine($"Completed with exit code: {result}"); return result; } } builder.UseMiddleware<LoggingMiddleware>(); // Or use inline middleware builder.UseMiddleware((context, next) => { var startTime = DateTime.Now; var result = next(); var elapsed = DateTime.Now - startTime; Console.WriteLine($"Execution time: {elapsed.TotalMilliseconds}ms"); return result; });

Skipping Middleware

You can skip middleware for specific commands or subcommands using the [SkipMiddleware] attribute. This is useful for informational commands (like help or version) or system commands where middleware would be inappropriate:

// Skip middleware for entire command [Command("info")] [SkipMiddleware] public class InfoCommand { [DefaultHandler] public int Execute() { Console.WriteLine("Application information..."); return 0; } } // Skip middleware for specific subcommands only [Command("database")] public class DatabaseCommand { [Subcommand("migrate")] public int Migrate() { // Middleware runs for this subcommand Console.WriteLine("Running migrations..."); return 0; } [Subcommand("status")] [SkipMiddleware] // Skip middleware for this subcommand public int Status() { Console.WriteLine("Database status: OK"); return 0; } }

Note: Middleware is automatically skipped for:

• Help requests (--help, -h, or the help command)
• Version requests (--version, -v)
• Invalid commands or validation errors

REPL Mode

Enable an interactive Read-Eval-Print Loop with advanced features:

builder.ConfigureRepl(config => { config.EnableRepl = true; config.EnableHistory = true; config.SaveHistoryOnSuccessOnly = false; // Save all commands, or only successful ones config.DefaultToRepl = true; // Start in REPL when no args provided config.EnableSyntaxHighlighting = true; // Enable real-time syntax highlighting (default: true) config.PersistGlobalOptions = true; // Persist global options across REPL commands (default: false) // Prompt receives ContourApp to access current theme config.Prompt = (app) => { var theme = app.Theme; AnsiConsole.Markup($"[{theme.InfoStyle.ToMarkup()}]> [/]"); }; // Enable environment variable expansion with multiple syntaxes config.EnableVariableExpansion = true; config.VariableExpansionSyntax = VariableExpansionSyntax.OsDefault; // Platform defaults config.ErrorOnUnknownVariable = false; // Return empty string for unknown vars (default: false) // Or combine multiple syntaxes using flags: // config.VariableExpansionSyntax = VariableExpansionSyntax.Bash | VariableExpansionSyntax.PowerShell; });

REPL Features:

• Syntax Highlighting - Commands, subcommands, and options are highlighted as you type

  • Commands appear in the theme's command color
  • Valid options and flags are highlighted in the option color
  • Invalid or unknown tokens remain unhighlighted
  • Colors update dynamically when you change themes

• Auto-completion - Press Tab to complete commands, subcommands, options, and flags

  > gre<Tab> # Completes to "greet" > greet --<Tab> # Shows all available options and flags > greet -<Tab> # Shows short-form options

• Command History - Navigate with arrow keys or recall by number

  > greet Alice > greet Bob > history # Shows numbered command history > !1 # Recalls "greet Alice" for editing > <Up Arrow> # Navigate to previous commands

• Environment Variable Expansion - Use environment variables in commands with support for multiple syntaxes

  # Bash/Linux style > greet $USER # Expands to current user > process ${HOME}/file.txt # Braced syntax # Windows CMD style > greet %USERNAME% # Windows user variable > process %TEMP%\file.txt # Temp directory # Enhanced Batch/DOS style with substring support > echo %PATH:~0,20% # First 20 characters of PATH > echo %USERNAME:~-5% # Last 5 characters of username > echo %TEMP:~3% # From character 3 to end # PowerShell style > greet $env:USERNAME # PowerShell syntax

  Available syntaxes (can be combined with |):

  • VariableExpansionSyntax.None - Disable expansion
  • VariableExpansionSyntax.Bash - $VAR or ${VAR}
  • VariableExpansionSyntax.Cmd - %VAR%
  • VariableExpansionSyntax.PowerShell - $env:VAR
  • VariableExpansionSyntax.BatchEnhanced - %VAR:~start,length% with substring support
  • VariableExpansionSyntax.OsDefault - Automatically use platform defaults
    • Windows: Cmd | BatchEnhanced
    • Linux/macOS: Bash

  Examples of combining syntaxes:

  // Support both Bash and PowerShell in same session config.VariableExpansionSyntax = VariableExpansionSyntax.Bash | VariableExpansionSyntax.PowerShell; // Support all Windows styles config.VariableExpansionSyntax = VariableExpansionSyntax.Cmd | VariableExpansionSyntax.BatchEnhanced | VariableExpansionSyntax.PowerShell; // Cross-platform support config.VariableExpansionSyntax = VariableExpansionSyntax.Bash | VariableExpansionSyntax.Cmd | VariableExpansionSyntax.PowerShell;

  Handling Unknown Variables:

  By default, unknown environment variables expand to an empty string:

  > echo $UNKNOWN_VAR something # Expands to "echo something"

  To receive an error when unknown variables are encountered:

  config.ErrorOnUnknownVariable = true;

  With this enabled:

  > echo $UNKNOWN_VAR Error: Unknown environment variable: UNKNOWN_VAR

• Persistent Global Options - Global options can persist across REPL commands

  When PersistGlobalOptions is enabled, global options set when starting the app will remain active for all REPL commands:

  # Start app with global options $ myapp --verbose --log-level 3 # In REPL, these options remain active > info # Shows: verbose=true, log-level=3 > build # Runs with verbose=true, log-level=3 > test --log-level 1 # Override log-level to 1, verbose stays true > deploy --nogopt # Reset to defaults for this command only

  Key Features:

  • Global options persist across all REPL commands
  • Options can be overridden on a per-command basis
  • Use --nogopt flag to temporarily reset to defaults
  • When disabled (default), options reset to defaults before each command

  Configuration:

  builder.ConfigureRepl(config => { config.PersistGlobalOptions = true; // Enable persistence (default: false) });

• Boolean Flag Values - Flags support explicit boolean values

  Flags can now accept explicit true/false values in addition to the traditional presence/absence:

  # Traditional syntax (presence = true) $ myapp --verbose # Explicit true values $ myapp --verbose true $ myapp --verbose yes $ myapp --verbose on $ myapp --verbose 1 # Explicit false values $ myapp --verbose false $ myapp --verbose no $ myapp --verbose off $ myapp --verbose 0

  This is particularly useful in REPL mode when you want to disable a flag that's already set:

  > info --verbose # Enable verbose > info --verbose false # Disable verbose

  Supported values:

  • True: true, yes, on, 1 (case-insensitive)
  • False: false, no, off, 0 (case-insensitive)
  • No value: Defaults to true (traditional behavior)

• Built-in Commands

  • exit or quit - Exit the REPL
  • help - Display available commands
  • history - Display command history
  • history clear - Clear command history
  • clear - Clear the screen

Example REPL Session:

$ myapp Interactive REPL - Type 'exit' to quit > greet Alice Hi, Alice! > greet Bob --formal Good day, Bob > history # | Command ---+------------------- 1 | greet Alice 2 | greet Bob --formal > !1 > greet Alice --formal # Edit recalled command before running Good day, Alice > exit

Theming

Customize the appearance of your CLI application with themes:

// Apply a built-in theme var app = builder.Build(); app.ApplyTheme(ContourTheme.Dark()); // Dark theme app.ApplyTheme(ContourTheme.Light()); // Light theme app.ApplyTheme(ContourTheme.Ultraviolet()); // Vibrant purple/neon app.ApplyTheme(ContourTheme.Rainbow()); // Colorful rainbow // Create a custom theme var customTheme = new ContourTheme { CommandStyle = new Style(Color.Magenta, decoration: Decoration.Bold), SubcommandStyle = new Style(Color.Cyan), OptionStyle = new Style(Color.Green), ErrorStyle = new Style(Color.Red, decoration: Decoration.Bold), WarningStyle = new Style(Color.Yellow), SuccessStyle = new Style(Color.Green1), InfoStyle = new Style(Color.Blue), DimStyle = new Style(Color.Grey), HighlightStyle = new Style(Color.White, decoration: Decoration.Bold) }; app.ApplyTheme(customTheme); // Themes affect: // - Syntax highlighting in REPL // - Help output (commands, options, descriptions) // - Error and success messages // - Tables, panels, and borders // - Version display // - Custom command output (when using theme)

Accessing Theme in Commands:

[Command("mycommand")] public class MyCommand { private readonly ContourApp _app; public MyCommand(ContourApp app) { _app = app; } [DefaultHandler] public int Execute() { // Option 1: Use theme-aware markup methods (recommended) _app.MarkupLine("[success]Operation completed successfully![/]"); _app.MarkupLine("[error]Something went wrong![/]"); _app.MarkupLine("[warning]Warning message[/]"); _app.MarkupLine("[info]Informational message[/]"); _app.MarkupLine("[dim]Dimmed text[/] [highlight]Highlighted text[/]"); _app.MarkupLine("[command]mycommand[/] [subcommand]subcommand[/] [option]--option[/]"); // Option 2: Access theme directly for advanced scenarios var theme = _app.Theme; AnsiConsole.MarkupLine($"[{theme.SuccessStyle.ToMarkup()}]Success![/]"); return 0; } }

Theme-Aware Markup Tags:

ContourApp provides convenient wrapper methods that automatically apply theme colors to your output. These methods support the following tags:

Tag	Description	Use Case
[error]...[/error]	Error messages	Errors, failures, exceptions
[warning]...[/warning]	Warning messages	Warnings, cautions
[success]...[/success]	Success messages	Confirmations, completions
[info]...[/info]	Informational messages	General information, prompts
[dim]...[/dim]	Dimmed/muted text	Secondary information, hints
[highlight]...[/highlight]	Highlighted/emphasized text	Important values, keywords
[command]...[/command]	Command names	Commands in help text
[subcommand]...[/subcommand]	Subcommand names	Subcommands in help text
[option]...[/option]	Option/flag names	Options and flags in help text

Available Methods:

// Write markup (no newline) _app.Markup("[error]Error:[/] Something went wrong"); // Write markup with newline _app.MarkupLine("[success]Success:[/] Task completed"); // Write interpolated markup (no newline) _app.MarkupInterpolated($"[info]Processing {filename}...[/]"); // Write interpolated markup with newline _app.MarkupLineInterpolated($"[success]Processed {count} files[/]"); // Parse theme markup without writing to console string spectreMarkup = _app.ParseThemeMarkup("[error]Error:[/] [warning]Warning[/]"); // Returns: "[red]Error:[/] [yellow]Warning[/]" (actual colors depend on theme) // Use with Spectre.Console directly var panel = new Panel(_app.ParseThemeMarkup("[info]Panel content[/]")); AnsiConsole.Write(panel);

Benefits:

• Theme-independent: Your code doesn't need to know about specific colors
• Automatic updates: Changes to the theme automatically affect all output
• Cleaner code: Simpler syntax compared to accessing theme styles directly
• Consistent styling: Ensures consistent use of theme colors across commands

Version Handling

Customize version display with access to the current theme:

// Using a custom provider class public class CustomVersionProvider : IVersionProvider { public int ShowVersion() { Console.WriteLine("MyApp v2.1.0"); return 0; } } builder.UseVersionProvider<CustomVersionProvider>(); // Or use inline version provider with theme access builder.UseVersionProvider((app) => { var theme = app?.Theme ?? ContourTheme.Default(); AnsiConsole.MarkupLine($"[{theme.InfoStyle.ToMarkup()}]MyApp v2.1.0 - Build 12345[/]"); return 0; });

Help System

Customize help output:

// Using a custom provider class public class CustomHelpProvider : IHelpProvider { public int ShowHelp(Type commandType, CommandAvailability context) { // Custom help implementation return 0; } public int ShowAllHelp(CommandAvailability context) { // Custom help implementation return 0; } } builder.UseHelpProvider<CustomHelpProvider>();

Attributes Reference

Command Attributes

• [Command] - Marks a class as a command

  • Name - Command name (required)
  • Description - Command description
  • Aliases - Alternative names
  • Availability - Where command is available (Cli, Repl, or Both)

• [DefaultHandler] - Marks the default command handler method

• [Subcommand] - Marks a method as a subcommand handler

  • Name - Subcommand name (required)
  • Description - Subcommand description
  • Availability - Where subcommand is available

Parameter Attributes

• [Parameter] - Positional parameter

  • Position - Zero-based position
  • Description - Parameter description
  • MinCount - Minimum required count (for collections)

• [Option] - Named option that accepts a value

  • Name - Option name (required)
  • ShortName - Short form (e.g., -o)
  • Description - Option description
  • DefaultValue - Default value if not provided
  • Required - Whether option is required

• [Flag] - Boolean flag

  • Name - Flag name (required)
  • ShortName - Short form (e.g., -v)
  • Description - Flag description
  • DefaultValue - Default value (defaults to false)

Building and Running

Build the Solution

dotnet restore dotnet build

Project Structure

Alveus.Contour/ ├── Alveus.Contour/ # Core library │ ├── Attributes/ # Command and parameter attributes │ ├── Commands/ # Built-in commands (help, history, etc.) │ ├── Help/ # Help system │ ├── Middleware/ # Middleware infrastructure │ ├── Parsing/ # Argument parsing │ ├── REPL/ # REPL implementation │ ├── Routing/ # Command routing │ ├── Version/ # Version handling │ ├── ContourApp.cs # Main application class │ └── ContourBuilder.cs # Fluent builder API └── Alveus.Contour.Demo/ # Demo application ├── Commands/ # Example commands ├── Middleware/ # Example middleware └── Program.cs # Demo entry point

Advanced Examples

Command with Collection Parameters

[Command("process")] public class ProcessCommand { [DefaultHandler] public int Execute( [Option("tag", ShortName = "t", Description = "Tags (can be specified multiple times)")] IEnumerable<string> tags, [Parameter(0, MinCount = 1, Description = "Files to process")] IEnumerable<string> files) { foreach (var file in files) { Console.WriteLine($"Processing: {file}"); foreach (var tag in tags ?? Enumerable.Empty<string>()) { Console.WriteLine($" Tag: {tag}"); } } return 0; } } $ myapp process file1.txt file2.txt -t alpha -t beta Processing: file1.txt Tag: alpha Tag: beta Processing: file2.txt Tag: alpha Tag: beta

Async Command Handlers

public class AsyncMiddleware : ICommandMiddlewareAsync { public async Task<int> ExecuteAsync(CommandContext context, Func<Task<int>> next) { await Task.Delay(100); // Async work return await next(); } } builder.UseMiddleware<AsyncMiddleware>();

Multiple Global Options Types

public class AppGlobalOptions { [Flag("verbose", ShortName = "v")] public bool Verbose { get; set; } } public class DatabaseOptions { [Option("connection", ShortName = "db")] public string? ConnectionString { get; set; } } builder.UseGlobalOptions<AppGlobalOptions>(); builder.UseGlobalOptions<DatabaseOptions>();

Dependencies

• Microsoft.Extensions.DependencyInjection (10.0.0) - Dependency injection
• Spectre.Console (0.54.0) - Rich terminal UI

What's New

Persistent Global Options in REPL

Global options can now persist across REPL commands, providing a more seamless interactive experience:

• Persistent State: Global options set when launching the app remain active for all REPL commands
• Per-command Override: Override global options on individual commands without changing the persisted values
• Reset to Defaults: Use the --nogopt flag to temporarily reset global options to defaults for a single command
• Configurable Behavior: Enable or disable persistence with config.PersistGlobalOptions

This feature is particularly useful when you want to maintain a consistent set of options (like --verbose or --log-level) throughout a REPL session without having to specify them on every command.

Boolean Flag Values

Flags now support explicit boolean values, giving you more control over their state:

• Explicit True/False: Set flags to true or false explicitly using --verbose true or --verbose false
• Multiple Formats: Supports multiple boolean formats: true/false, yes/no, on/off, 1/0
• Case Insensitive: All boolean values are parsed case-insensitively
• REPL Friendly: Especially useful in REPL mode for toggling flags on and off

This feature makes it easier to disable flags in REPL mode and provides a more intuitive syntax for flag manipulation.

Theming System

Alveus.Contour includes a comprehensive theming system that allows you to customize the appearance of your CLI application:

• Built-in themes: Default, Dark, Light, Monochrome, Ultraviolet, and Rainbow
• Custom themes: Create your own themes by defining styles for commands, options, errors, and more
• Dynamic theme switching: Change themes at runtime (even in REPL mode)
• Automatic propagation: Themes automatically apply to syntax highlighting, help output, error messages, and all UI elements
• Theme-aware commands: Commands can access the current theme via dependency injection

Syntax Highlighting in REPL

The REPL features real-time syntax highlighting:

• Commands, subcommands, and options are color-coded as you type
• Invalid or unknown elements remain unhighlighted for immediate visual feedback
• Highlighting uses the current theme and updates dynamically when themes change
• Provides a more intuitive and polished interactive experience

Custom Line Editor

Alveus.Contour includes a custom-built line editor, removing the dependency on the ReadLine library. This provides:

• Full control over keyboard input handling (arrow keys, Home, End, backspace, delete)
• Intelligent auto-completion for commands, subcommands, options, and flags (including global options)
• Command history with configurable success-only saving
• History recall with !<number> syntax allowing pre-execution editing
• Environment variable expansion with support for multiple shell syntaxes (Bash, CMD, PowerShell)
• Better integration with the REPL environment and syntax highlighting

License

Refer to the LICENSE file in the repository.