putschoeglwe / CommandLineUtils

Command line parsing and utilities for .NET

CommandLineUtils

This project helps you create command line applications using .NET. It simplifies parsing arguments provided on the command line, validating user inputs, and generating help text.

The roadmap for this project is pinned to the top of the issue list.

Usage

See documentation for API reference, samples, and tutorials. See also docs/samples/ for more examples, such as:

• Hello world
• Async console apps
• Structuring an app with subcommands
• Defining options with attributes
• Interactive console prompts
• Required options and arguments

Installing the library

This project is available as a NuGet package.

$ dotnet add package McMaster.Extensions.CommandLineUtils

Code

CommandLineApplication is the main entry point for most console apps parsing. There are two primary ways to use this API, using the builder pattern and attributes.

Attribute API

using System;
using McMaster.Extensions.CommandLineUtils;

public class Program
{
    public static int Main(string[] args)
        => CommandLineApplication.Execute<Program>(args);

    [Option(Description = "The subject")]
    public string Subject { get; } = "world";

    [Option(ShortName = "n")]
    public int Count { get; } = 1;

    private void OnExecute()
    {
        for (var i = 0; i < Count; i++)
        {
            Console.WriteLine($"Hello {Subject}!");
        }
    }
}

Builder API

using System;
using McMaster.Extensions.CommandLineUtils;

var app = new CommandLineApplication();

app.HelpOption();

var subject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
subject.DefaultValue = "world";

var repeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
repeat.DefaultValue = 1;

app.OnExecute(() =>
{
    for (var i = 0; i < repeat.ParsedValue; i++)
    {
        Console.WriteLine($"Hello {subject.Value()}!");
    }
});

return app.Execute(args);

Utilities

The library also includes other utilities for interaction with the console. These include:

• ArgumentEscaper - use to escape arguments when starting a new command line process.

   var args = new [] { "Arg1", "arg with space", "args ' with \" quotes" };
   Process.Start("echo", ArgumentEscaper.EscapeAndConcatenate(args));

• Prompt - for getting feedback from users with a default answer. A few examples:

  // allows y/n responses, will return false by default in this case.
  // You may optionally change the prompt foreground and background color for
  // the message.
  Prompt.GetYesNo("Do you want to proceed?", false);
  
  // masks input as '*'
  Prompt.GetPassword("Password: ");

• DotNetExe - finds the path to the dotnet.exe file used to start a .NET Core process

  Process.Start(DotNetExe.FullPathOrDefault(), "run");

And more! See the documentation for more API, such as IConsole, IReporter, and others.

Project origin and status

This is a fork of Microsoft.Extensions.CommandLineUtils, which is no longer under active development. This fork, on the other hand, will continue to make improvements, release updates, and accept contributions. It is currently maintained by @natemcmaster.