Command-Line Cheatsheet

Overview

System.CommandLine is the official .NET library for building command-line applications with typed argument parsing, automatic help generation, tab completion, and middleware support. It provides a structured way to define commands, options, and arguments that map directly to handler methods, with built-in validation and error reporting.

NuGet Packages

bash

dotnet add package System.CommandLine
dotnet add package System.CommandLine.Hosting   # Generic Host integration

Minimal CLI Application

csharp

using System.CommandLine;

var nameOption = new Option<string>(
    name: "--name",
    description: "Your name")
{ IsRequired = true };

var greetingOption = new Option<string>(
    name: "--greeting",
    description: "The greeting to use",
    getDefaultValue: () => "Hello");

var rootCommand = new RootCommand("A simple greeting CLI tool");
rootCommand.AddOption(nameOption);
rootCommand.AddOption(greetingOption);

rootCommand.SetHandler((string name, string greeting) =>
{
    Console.WriteLine($"{greeting}, {name}!");
}, nameOption, greetingOption);

return await rootCommand.InvokeAsync(args);
// Usage: myapp --name Alice --greeting "Good morning"

Commands with Subcommands

csharp

using System.CommandLine;

var rootCommand = new RootCommand("Project management CLI");

// 'new' command
var newCommand = new Command("new", "Create a new project");
var templateArg = new Argument<string>("template", "Project template name");
var outputOption = new Option<DirectoryInfo>(
    "--output", "Output directory") { IsRequired = false };

newCommand.AddArgument(templateArg);
newCommand.AddOption(outputOption);

newCommand.SetHandler((string template, DirectoryInfo? output) =>
{
    var dir = output?.FullName ?? Directory.GetCurrentDirectory();
    Console.WriteLine($"Creating '{template}' project in {dir}");
}, templateArg, outputOption);

// 'build' command
var buildCommand = new Command("build", "Build the project");
var configOption = new Option<string>(
    "--configuration", () => "Debug", "Build configuration");
configOption.AddAlias("-c");

var verbosityOption = new Option<Verbosity>(
    "--verbosity", () => Verbosity.Normal, "Output verbosity");
verbosityOption.AddAlias("-v");

buildCommand.AddOption(configOption);
buildCommand.AddOption(verbosityOption);

buildCommand.SetHandler((string config, Verbosity verbosity) =>
{
    Console.WriteLine($"Building with configuration={config}, verbosity={verbosity}");
}, configOption, verbosityOption);

// 'test' command with nested subcommands
var testCommand = new Command("test", "Run tests");
var unitCommand = new Command("unit", "Run unit tests");
var integrationCommand = new Command("integration", "Run integration tests");

var filterOption = new Option<string?>("--filter", "Test filter expression");

unitCommand.AddOption(filterOption);
unitCommand.SetHandler((string? filter) =>
{
    Console.WriteLine($"Running unit tests{(filter != null ? $" with filter: {filter}" : "")}");
}, filterOption);

integrationCommand.SetHandler(() =>
{
    Console.WriteLine("Running integration tests");
});

testCommand.AddCommand(unitCommand);
testCommand.AddCommand(integrationCommand);

rootCommand.AddCommand(newCommand);
rootCommand.AddCommand(buildCommand);
rootCommand.AddCommand(testCommand);

return await rootCommand.InvokeAsync(args);

enum Verbosity { Quiet, Normal, Detailed, Diagnostic }

// Usage:
// myapp new webapp --output ./MyApp
// myapp build -c Release -v Detailed
// myapp test unit --filter "Category=Smoke"
// myapp test integration

Options, Arguments, and Aliases

Concept	Description	Example
`Option<T>`	Named parameter with `--` prefix	`--output`, `-o`
`Argument<T>`	Positional parameter (no prefix)	`myapp <file>`
`AddAlias`	Short alias for an option	`-c` for `--configuration`
`IsRequired`	Makes an option mandatory	`{ IsRequired = true }`
`getDefaultValue`	Factory for default values	`() => "Debug"`
`FromAmong`	Restricts to allowed values	`FromAmong("Debug", "Release")`

Argument Validation

csharp

using System.CommandLine;

var portOption = new Option<int>("--port", "Server port");
portOption.AddValidator(result =>
{
    var port = result.GetValueForOption(portOption);
    if (port < 1024 || port > 65535)
    {
        result.ErrorMessage = "Port must be between 1024 and 65535";
    }
});

var fileArgument = new Argument<FileInfo>("file", "Input file");
fileArgument.AddValidator(result =>
{
    var file = result.GetValueForArgument(fileArgument);
    if (file is not null && !file.Exists)
    {
        result.ErrorMessage = $"File not found: {file.FullName}";
    }
});

// Restrict to specific values
var envOption = new Option<string>("--environment");
envOption.FromAmong("Development", "Staging", "Production");

Global Options

csharp

var verboseOption = new Option<bool>("--verbose", "Enable verbose logging");
verboseOption.AddAlias("-V");

var rootCommand = new RootCommand("My CLI");
rootCommand.AddGlobalOption(verboseOption); // Available to all subcommands

var serveCommand = new Command("serve", "Start the server");
serveCommand.SetHandler((bool verbose) =>
{
    if (verbose) Console.WriteLine("Verbose mode enabled");
    Console.WriteLine("Starting server...");
}, verboseOption);

rootCommand.AddCommand(serveCommand);

// Usage: myapp serve --verbose
// Usage: myapp --verbose serve   (global options work before or after subcommand)

Hosting Integration

Integrate System.CommandLine with the .NET Generic Host for DI, configuration, and logging.

csharp

using System.CommandLine;
using System.CommandLine.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var rootCommand = new RootCommand("CLI with hosting");

var nameOption = new Option<string>("--name", "User name") { IsRequired = true };
rootCommand.AddOption(nameOption);

rootCommand.SetHandler(async (IHost host) =>
{
    var greeter = host.Services.GetRequiredService<GreeterService>();
    var parseResult = host.Services.GetRequiredService<ParseResult>();
    var name = parseResult.GetValueForOption(nameOption)!;
    await greeter.GreetAsync(name);
});

var builder = new CommandLineBuilder(rootCommand)
    .UseHost(hostBuilder =>
    {
        hostBuilder.ConfigureServices(services =>
        {
            services.AddTransient<GreeterService>();
        });
        hostBuilder.ConfigureLogging(logging =>
        {
            logging.AddConsole();
            logging.SetMinimumLevel(LogLevel.Information);
        });
    })
    .UseDefaults();

return await builder.Build().InvokeAsync(args);

public class GreeterService(ILogger<GreeterService> logger)
{
    public Task GreetAsync(string name)
    {
        logger.LogInformation("Greeting user: {Name}", name);
        Console.WriteLine($"Hello, {name}!");
        return Task.CompletedTask;
    }
}

Middleware

csharp

var builder = new CommandLineBuilder(rootCommand)
    .UseDefaults()
    .AddMiddleware(async (context, next) =>
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        Console.WriteLine($"Executing: {context.ParseResult.CommandResult.Command.Name}");

        await next(context);

        sw.Stop();
        Console.WriteLine($"Completed in {sw.ElapsedMilliseconds}ms");
    });

var parser = builder.Build();
return await parser.InvokeAsync(args);

File and Directory Arguments

csharp

var inputFile = new Argument<FileInfo>("input", "Input file path");
var outputDir = new Option<DirectoryInfo>(
    "--output-dir", () => new DirectoryInfo("."), "Output directory");

var convertCommand = new Command("convert", "Convert a file");
convertCommand.AddArgument(inputFile);
convertCommand.AddOption(outputDir);

convertCommand.SetHandler((FileInfo input, DirectoryInfo outDir) =>
{
    if (!input.Exists)
    {
        Console.Error.WriteLine($"File not found: {input.FullName}");
        return;
    }
    Console.WriteLine($"Converting {input.Name} to {outDir.FullName}");
}, inputFile, outputDir);

Creating a dotnet Tool

xml

<!-- .csproj file -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>mytool</ToolCommandName>
    <PackageId>MyOrg.MyTool</PackageId>
    <Version>1.0.0</Version>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.*" />
  </ItemGroup>
</Project>

bash

# Pack and install locally
dotnet pack
dotnet tool install --global --add-source ./nupkg MyOrg.MyTool

# Usage
mytool build -c Release
mytool test unit --filter "Priority=1"

Best Practices

•Use RootCommand with descriptive text as the entry point and organize functionality into Command subcommands rather than overloading the root with many options.
•Add both long (--configuration) and short (-c) aliases for frequently used options to reduce typing in interactive use while keeping discoverability for scripts.
•Use Option<T> with strongly-typed generics (Option<int>, Option<FileInfo>, Option<Verbosity>) instead of Option<string> with manual parsing to get automatic validation and help text.
•Set IsRequired = true on mandatory options and provide getDefaultValue factories on optional ones so the help text accurately reflects what is required vs. optional.
•Use AddValidator for custom validation rules (port ranges, file existence, format checks) to provide clear error messages before the handler runs.
•Use FromAmong to restrict string options to a fixed set of allowed values (e.g., environments, log levels) with automatic validation and tab completion.
•Integrate with System.CommandLine.Hosting for applications that need dependency injection, IConfiguration, or ILogger rather than constructing services manually in handlers.
•Add AddGlobalOption for cross-cutting options like --verbose, --output-format, or --no-color that apply to all subcommands without repeating them.
•Set <PackAsTool>true</PackAsTool> in the .csproj to distribute the CLI as a dotnet tool that users install with dotnet tool install.
•Use CommandLineBuilder.UseDefaults() to enable automatic help (--help), version (--version), parse error reporting, and suggest-typo features without manual configuration.