👁 Image
Albatross.CommandLine 8.0.14

Albatross.CommandLine

A .NET library that simplifies creating command-line applications with System.CommandLine. It provides automatic code generation and dependency injection support while maintaining full access to System.CommandLine's capabilities. The framework is opinionated toward async actions with out-of-the-box support for cancellation and graceful shutdown.

Designed for enterprise CLI applications, Albatross.CommandLine enforces consistent async patterns, built-in dependency injection, and graceful shutdown handling. These opinionated choices reduce complexity and ensure scalability from simple utilities to complex enterprise workflows.

Key Features

• Minimal Boilerplate - Attribute-based command definition with automatic code generation
• AOT-compatible - Uses compile-time Roslyn source generation (no runtime reflection or emit), making it friendly to Native AOT scenarios
• Dependency Injection - Built-in DI container integration
• Minimum Dependencies - Only depends on System.CommandLine and Microsoft.Extensions.Hosting.
• Full Flexibility - Direct access to System.CommandLine when needed
• Cancellation & Graceful Shutdown - Built-in support for Ctrl+C interruption via cancellation tokens and graceful shutdown handling
• Reusable Parameter - Create customized Option and Argument classes and use [UseOption<T>] and [UseArgument<T>] attributes to compose them into commands with automatic code generation
• Advanced Option Handlers - Injectable async option handlers with [OptionHandler] attribute for pre-processing and input transformation patterns. Execute database validation, API calls, or transform simple inputs into complex objects before command execution
• Easy Extensions - Use CommandHost.ConfigureHost() to bootstrap additional services, or use Albatross.CommandLine.Defaults for pre-configured Serilog logging and JSON/environment configuration support

Quick Start

Bootstrapping

Create a console app. In the program.cs file, insert the code below:

internal class Program {
 static async Task<int> Main(string[] args) {
 await using var host = new CommandHost("Sample Command Line Application")
 .RegisterServices(RegisterServices)
 // this method is generated by source generator
 // this line will not compile before the creation of the first command
 .AddCommands()
 .Parse(args)
 .Build();
 return await host.InvokeAsync();
 }
 static void RegisterServices(ParseResult result, IConfiguration configuration, IServiceCollection services) {
 // RegisterCommands method is generated by codegen
 services.RegisterCommands();
 // register the rest of the dependency here
 ...
 }
 }

Define a Verb

[Verb<HelloWorldCommandHandler>("hello", Description = "The HelloWorld command")]
public record class HelloWorldParams {
 [Option]
 public required string Name { get; init; }
}

Create the Command Handler

The Command Handler has to inherit interface: IAsyncCommandHandler

public class HelloWorldCommandHandler : IAsyncCommandHandler {
 ParseResult result;
 HelloWorldParams parameters;
 ILogger logger;
 
 public HelloWorldCommandHandler(ParseResult result, HelloWorldParams parameters, ILogger<HelloWorldCommandHandler> logger) {
 this.result = result;
 this.parameters = parameters;
 this.logger = logger;
 }
 public async Task<int> InvokeAsync(CancellationToken cancellationToken) {
 // do your work here
 await Console.WriteLineAsync($"{result} is invoked with {parameters}");
 return 0;
 }
}

Run the app

Usage: dotnet run -- hello --name test

Dependencies

• System.CommandLine 2.0.1+
• Microsoft.Extensions.Hosting 8.0.1+

Prerequisites

• C# Compiler 4.10.0+ (included with .NET 8 SDK)

📖 Documentation

📚 Complete Documentation

Links

• Core Concepts
• Conventions
• Command Customization
• Code Generator
• Mutually Exclusive Parameter Set
• Reusable Parameter
• Option PreProcessing and Transformation
• Command Context
• Execution Pipeline