Albatross.CommandLine 8.0.2

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
• 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 an 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 depencency 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
        Console.WriteLine($"{result} is invoked with {parameter}");
    }
}

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