Cocona

For .NET Standard 2.0, .NET 5, or older environments, use the class-based approach. You pass the class type to CoconaApp.Run<T>(args), and every public method in that class becomes a command available in the CLI.

using Cocona;

class Program
{
    static void Main(string[] args)
    {
        // Cocona parses command-line and executes a command.
        CoconaApp.Run<Program>(args);
    }

    // public method as a command ™
    public void Hello(string name)
    {
        Console.WriteLine($"Hello {name}");
    }
}

Cocona supports validation using .NET Data Annotations (System.ComponentModel.DataAnnotations). You can use built-in attributes like [Range], [MaxLength], and [MinLength].

To implement custom validation, inherit from ValidationAttribute and override IsValid.

For .NET 6 and later, you can use the Minimal API style to define your application logic directly within CoconaApp.Run. Parameters in the lambda expression are automatically mapped to command-line options or arguments.

CoconaApp.Run((string? name, bool hey) =>
    Console.WriteLine($"{(hey ? "Hey" : "Hello")} {(name ?? "Guest")}!"));

Cocona supports tab completion for bash and zsh. This feature is disabled by default. To use it, set EnableShellCompletionSupport to true in your configuration.

Once enabled, you can generate a completion script using the --completion built-in option:

# For bash
source <(./myapp --completion bash)

# For zsh
./myapp --completion zsh > ~/.zsh/functions

$ source <(./myapp --completion bash)

To handle shutdown signals (like Ctrl+C), monitor the CancellationToken provided by the CoconaAppContext or via ICoconaAppContextAccessor.

// Using CoconaAppContext directly
app.AddCommand(async (CoconaAppContext ctx) =>
{
    while (!ctx.CancellationToken.IsCancellationRequested)
    {
        await Task.Delay(100);
    }
});

// Using ICoconaAppContextAccessor (Dependency Injection style)
public async Task RunAsync([FromService] ICoconaAppContextAccessor contextAccessor)
{
    var ctx = contextAccessor.Current ?? throw new InvalidOperationException();
    while (!ctx.CancellationToken.IsCancellationRequested)
    {
        await Task.Delay(100);
    }
}

You can integrate Cocona with Microsoft.Extensions.Hosting.GenericHost using the ConfigureCocona extension method. This allows you to manage Cocona commands within a standard .NET GenericHost lifecycle.

class Program
{
    static async Task Main(string[] args)
    {
        await Host.CreateDefaultBuilder()
            .ConfigureCocona(args, new[] { typeof(Program) })
            .Build()
            .RunAsync();
    }

    public void Hello()
    {
        Console.WriteLine($"Hello Konnichiwa!");
    }
}

Cocona integrates with .NET Dependency Injection. If a command method or a class constructor has parameters, Cocona will attempt to inject instances from the IServiceProvider.

You can also explicitly mark a parameter with [FromService] to ensure it is resolved from the DI container.

If your application runs on .NET Core 3.0 or later, you can publish it as a single-file executable using the dotnet publish command with the PublishSingleFile property set to true.

Windows (x64):

dotnet publish -r win-x64 -p:PublishSingleFile=true

Linux (x64):

dotnet publish -r linux-x64 -p:PublishSingleFile=true

You can install the standard Cocona package or the lightweight Cocona.Lite version if you want to minimize dependencies. Use the following commands to add the package to your project:

Standard Cocona:

dotnet add package Cocona

Cocona.Lite:

dotnet add package Cocona.Lite

If you want to avoid Microsoft.Extensions.* dependencies (Logging, DI, Configuration), use Cocona.Lite. It provides almost the same features and APIs as Cocona but with fewer overheads and minimal Dependency Injection. Use the CoconaLiteApp class instead of CoconaApp.

$ dotnet add package Cocona.Lite

// Option 1: Run with an action
CoconaLiteApp.Run(() => { ... });

// Option 2: Manual creation and command addition
var app = CoconaLiteApp.Create();
app.AddCommand(() => { ... });
app.Run();

// Option 3: Using a Program class
static void Main(string[] args)
{
    CoconaLiteApp.Run<Program>(args);
}