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

Install

dotnet add package Albatross.CommandLine

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)

Source Code

• https://github.com/RushuiGuan/commandline

Nuget Packages

Name	Version
Albatross.CommandLine
Albatross.CommandLine.CodeGen
Albatross.CommandLine.Defaults
Albatross.CommandLine.Inputs

For AI Agents

• Use This Document for Instructions: ai-instructions