System.CommandLine CLI Developer Skill

You are working on a .NET CLI application built with System.CommandLine v2.x.x, targeting .NET 8 or later or any .NET Standard 2.0 implementation, including .NET Framework 4.6.1 or later and .NET Core 2.0 or later. Follow these rules and patterns strictly when creating or modifying CLI commands.

Architecture Overview

<CLI Project>/
├── Program.cs                       # Entry point and command invocation
└── Commands/
    ├── CommandBase.cs               # Base class for all commands
    ├── GlobalOptions.cs             # Defines global options for the CLI
    ├── RootCommand.cs               # Registers top-level commands
    └── <Group>/                     # One folder per command group
        ├── <Group>Command.cs        # Parent command that registers its children
        └── <Group><Verb>Command.cs  # Leaf command with its handler

RULE 1 — Prefer a Project-Specific Command Base Class

Prefer defining a project-specific abstract CommandBase that inherits from System.CommandLine.Command. Concrete commands should inherit from this base class so shared behavior and conventions remain centralized.

internal abstract class CommandBase : Command
{
    protected CommandBase(string name, string? description = null)
        : base(name, description)
    {
    }
}

internal sealed class MyCommand : CommandBase
{
    public MyCommand()
        : base("command-name", "Help text shown in --help")
    {
        this.SetAction(CommandHandler);
    }

    private async Task<int> CommandHandler(
        ParseResult parseResult,
        CancellationToken cancellationToken)
    {
        // implementation
        return 0;
    }
}

When the project already has a command base class, preserve its established conventions. Otherwise, introduce one when commands need shared behavior; simple applications may inherit from Command directly when a base class adds no meaningful value.

RULE 2 — Options and Arguments

Defining Options

private readonly Option<string> _myOption;

// In constructor:
_myOption = new Option<string>("--my-option")
{
    Description = "Clear description of what this option does",
    Required = true,   // or false
};
_myOption.Aliases.Add("-m");       // Add a short alias
this.Options.Add(_myOption);

Defining Arguments (positional)

private readonly Argument<string> _fileArgument;

// In constructor:
_fileArgument = new Argument<string>("file")
{
    Description = "Path to the input file"
};
this.Arguments.Add(_fileArgument);

Reading Values in Handlers

// Required option/argument — use GetValue:
var value = parseResult.GetValue(_myOption);

RULE 3 — Command Handler Pattern

Handlers are async methods wired via SetAction:

this.SetAction(CommandHandler);

private async Task<int> CommandHandler(ParseResult parseResult, CancellationToken cancellationToken)
{
    // 1. Read option/argument values
    // 2. Load session settings (if needed)
    // 3. Validate configuration early — fail fast with clear error
    // 4. Execute business logic
    // 5. Output results with Console

    return 0; // or non-zero exit code
}

RULE 4 — Command Group (Parent with Subcommands)

A group command registers children but does not call SetAction:

internal class MyGroupCommand : CommandBase
{
    public MyGroupCommand()
        : base("mygroup", "Manages my-group resources")
    {
        this.Subcommands.Add(new MyGroupListCommand());
        this.Subcommands.Add(new MyGroupCreateCommand());
        this.Subcommands.Add(new MyGroupDeleteCommand());
    }
}

A command may define both an action and subcommands when the direct invocation has meaningful behavior.

RULE 5 — Registration

• Top-level commands → register in RootCommand.cs:

  this.Subcommands.Add(new MyGroupCommand());
  

• Subcommands → register inside the parent command's constructor:

  this.Subcommands.Add(new MyGroupCreateCommand());
  

RULE 6 — User Confirmation for Destructive Operations

Console.WriteLine("Are you sure you want to delete X? This action cannot be undone. (yes/no)");
var confirmation = Console.ReadLine();
if (confirmation?.ToLower() != "yes" && confirmation?.ToLower() != "y")
{
    Console.WriteLine("Operation cancelled.");
    return 0;
}

…