commandline-cheatsheet

name	commandline-cheatsheet
description	Use when building command-line applications in .NET with System.CommandLine. Covers command/option/argument definitions, middleware, tab completion, parsing, and hosting integration for CLI tools. USE FOR: building CLI applications with typed argument parsing, creating dotnet tools with subcommands, System.CommandLine setup and configuration, adding tab completion to CLI apps, parsing and validating command-line arguments DO NOT USE FOR: executing external CLI processes (use cliwrap), rendering rich terminal UI with tables and progress bars (use spectre-console), building web APIs (use ASP.NET Core), simple Console.ReadLine input
license	MIT
metadata	{"displayName":"Command-Line Cheatsheet","author":"Tyler-R-Kendrick","version":"1.0.0"}
compatibility	claude, copilot, cursor
references	[{"title":"System.CommandLine Documentation","url":"https://learn.microsoft.com/dotnet/standard/commandline"},{"title":"System.CommandLine GitHub Repository","url":"https://github.com/dotnet/command-line-api"},{"title":"System.CommandLine NuGet Package","url":"https://www.nuget.org/packages/System.CommandLine"}]

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

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

Minimal CLI Application

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

using System.CommandLine;

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

// 'new' command
var newCommand = new Command(, );
 templateArg =  Argument<>(, );
 outputOption =  Option<DirectoryInfo>(
    , ) { IsRequired =  };

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

newCommand.SetHandler(( template, DirectoryInfo? output) =>
{
     dir = output?.FullName ?? Directory.GetCurrentDirectory();
    Console.WriteLine();
}, templateArg, outputOption);


 buildCommand =  Command(, );
 configOption =  Option<>(
    , () => , );
configOption.AddAlias();

 verbosityOption =  Option<Verbosity>(
    , () => Verbosity.Normal, );
verbosityOption.AddAlias();

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

buildCommand.SetHandler(( config, Verbosity verbosity) =>
{
    Console.WriteLine();
}, configOption, verbosityOption);


 testCommand =  Command(, );
 unitCommand =  Command(, );
 integrationCommand =  Command(, );

 filterOption =  Option<?>(, );

unitCommand.AddOption(filterOption);
unitCommand.SetHandler((? filter) =>
{
    Console.WriteLine();
}, filterOption);

integrationCommand.SetHandler(() =>
{
    Console.WriteLine();
});

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

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

  rootCommand.InvokeAsync();

 Verbosity { Quiet, Normal, Detailed, Diagnostic }