CliFx

CliFx is an opinionated framework for building command-line applications. Instead of manually parsing arguments, you express command interactions through classes and properties.

Key features include:

• Class-first configuration: Use attributes to define commands and properties.
• Automatic Infrastructure: Handles argument parsing, routing, error handling, and help generation automatically.
• Command Hierarchies: Supports deeply nested command structures.
• Lifecycle Management: Provides graceful cancellation via interrupt signals.
• Advanced Capabilities: Support for reading/writing binary data and a testable console interaction layer.
• Deployment Friendly: Compatible with Native AOT and trimming; targets .NET Standard 2.0+.

Commands can be named or unnamed (root commands). Named commands allow for complex, hierarchical CLI structures.

• Root Command: A command with no name in [Command] is treated as the default command executed when no command name is provided.
• Named Commands: Specify a name in [Command("name")] to create a specific entry point.
• Hierarchical Commands: Commands with common name segments are treated as nested. For example, [Command("cmd1")] and [Command("cmd1 sub")] create a parent-child relationship where sub is a subcommand of cmd1.

CliFx commands can be tested in isolation using the IConsole abstraction. Use FakeConsole or FakeInMemoryConsole to simulate console interaction.

Command-level testing: Instantiate the command, set its properties, and call ExecuteAsync(console) directly.

Application-level (End-to-End) testing: Use CommandLineApplicationBuilder to build the full application, inject a FakeInMemoryConsole via .UseConsole(console), and call .RunAsync(args).

You can install CliFx as a NuGet package using the .NET CLI. It targets .NET Standard 2.0+ and has no external dependencies, making it compatible with Native AOT and trimming.

dotnet add package CliFx

To use an external dependency container (like Microsoft.Extensions.DependencyInjection), use UseTypeInstantiator(...) on the CommandLineApplicationBuilder. You can pass a factory delegate or an IServiceProvider.

public static async Task<int> Main() =>
    await new CommandLineApplicationBuilder()
        .AddCommandsFromThisAssembly()
        .UseTypeInstantiator(commands =>
        {
            var services = new ServiceCollection();
            services.AddSingleton<MyService>();
            foreach (var command in commands)
                services.AddTransient(command.Type);

            return services.BuildServiceProvider();
        })
        .Build()
        .RunAsync();

Commands communicate errors and exit codes by throwing a CommandException. This exception allows you to:

1. Print a specific error message.
2. Return a specific exit code (recommended range: 1-255 to avoid Unix overflow).
3. Optionally show help text for the current command.

Warning: On Unix systems, using exit codes outside the 8-bit unsigned range (1-255) can cause overflows.

CliFx automatically converts strings to common types (bool, enum, int, etc.). For custom types, implement IInputConverter<T>.

• Scalar types: Derive from ScalarInputConverter<T>.
• Sequence types: Derive from SequenceInputConverter<T>.
• Requirement: Converters must have a public parameter-less constructor.

To use a converter, assign it to the Converter property of the [CommandParameter] or [CommandOption] attribute.

Validators verify converted values before the command executes. Implement IInputValidator<T> by deriving from InputValidator<T>.

• Execution: Validators run sequentially. All errors are merged and reported together.
• Requirement: Validators must have a public parameter-less constructor.

To use a validator, assign it to the Validators property of the [CommandParameter] or [CommandOption] attribute.

using CliFx.Activation;

public class PositiveNumberValidator : InputValidator<double>
{
    public override IEnumerable<InputValidationError> Validate(double value)
    {
        if (value <= 0)
            yield return Error("Value must be positive.");
    }
}

// Usage in command
[CommandParameter(0, Validators = [typeof(PositiveNumberValidator)])]
public required double Value { get; set; }