Edit

How to define commands, options, and arguments in System.CommandLine

  • Article

Important

System.CommandLine is currently in PREVIEW, and this documentation is for version 2.0 beta 4. Some information relates to prerelease product that may be substantially modified before it's released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

This article explains how to define commands, options, and arguments in command-line apps that are built with the System.CommandLine library. To build a complete application that illustrates these techniques, see the tutorial Get started with System.CommandLine.

For guidance on how to design a command-line app's commands, options, and arguments, see Design guidance.

Define a root command

Every command-line app has a root command, which refers to the executable file itself. The simplest case for invoking your code, if you have an app with no subcommands, options, or arguments, would look like this:

using System.CommandLine;

class Program
{
    static async Task Main(string[] args)
    {
        var rootCommand = new RootCommand("Sample command-line app");

        rootCommand.SetHandler(() =>
        {
            Console.WriteLine("Hello world!");
        });

        await rootCommand.InvokeAsync(args);
    }
}

Define subcommands

Commands can have child commands, known as subcommands or verbs, and they can nest as many levels as you need. You can add subcommands as shown in the following example:

var rootCommand = new RootCommand();
var sub1Command = new Command("sub1", "First-level subcommand");
rootCommand.Add(sub1Command);
var sub1aCommand = new Command("sub1a", "Second level subcommand");
sub1Command.Add(sub1aCommand);

The innermost subcommand in this example can be invoked like this:

myapp sub1 sub1a

Define options

A command handler method typically has parameters, and the values can come from command-line options. The following example creates two options and adds them to the root command. The option names include double-hyphen prefixes, which is typical for POSIX CLIs. The command handler code displays the values of those options:

var delayOption = new Option<int>
    (name: "--delay",
    description: "An option whose argument is parsed as an int.",
    getDefaultValue: () => 42);
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayOption);
rootCommand.Add(messageOption);

rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
        Console.WriteLine($"--message = {messageOptionValue}");
    },
    delayOption, messageOption);

Here's an example of command-line input and the resulting output for the preceding example code:

myapp --delay 21 --message "Hello world!"

--delay = 21
--message = Hello world!

Global options

To add an option to one command at a time, use the Add or AddOption method as shown in the preceding example. To add an option to a command and recursively to all of its subcommands, use the AddGlobalOption method, as shown in the following example:

var delayOption = new Option<int>
    ("--delay", "An option whose argument is parsed as an int.");
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.AddGlobalOption(delayOption);
rootCommand.Add(messageOption);

var subCommand1 = new Command("sub1", "First level subcommand");
rootCommand.Add(subCommand1);

var subCommand1a = new Command("sub1a", "Second level subcommand");
subCommand1.Add(subCommand1a);

subCommand1a.SetHandler((delayOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
    },
    delayOption);

await rootCommand.InvokeAsync(args);

The preceding code adds --delay as a global option to the root command, and it's available in the handler for subCommand1a.

Define arguments

Arguments are defined and added to commands like options. The following example is like the options example, but it defines arguments instead of options:

var delayArgument = new Argument<int>
    (name: "delay",
    description: "An argument that is parsed as an int.",
    getDefaultValue: () => 42);
var messageArgument = new Argument<string>
    ("message", "An argument that is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayArgument);
rootCommand.Add(messageArgument);

rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
    {
        Console.WriteLine($"<delay> argument = {delayArgumentValue}");
        Console.WriteLine($"<message> argument = {messageArgumentValue}");
    },
    delayArgument, messageArgument);

await rootCommand.InvokeAsync(args);

Here's an example of command-line input and the resulting output for the preceding example code:

myapp 42 "Hello world!"

<delay> argument = 42
<message> argument = Hello world!

An argument that is defined without a default value, such as messageArgument in the preceding example, is treated as a required argument. An error message is displayed, and the command handler isn't called, if a required argument isn't provided.

Define aliases

Both commands and options support aliases. You can add an alias to an option by calling AddAlias:

var option = new Option("--framework");
option.AddAlias("-f");

Given this alias, the following command lines are equivalent:

myapp -f net6.0
myapp --framework net6.0

Command aliases work the same way.

var command = new Command("serialize");
command.AddAlias("serialise");

This code makes the following command lines equivalent:

myapp serialize
myapp serialise

We recommend that you minimize the number of option aliases that you define, and avoid defining certain aliases in particular. For more information, see Short-form aliases.

Required options

To make an option required, set its IsRequired property to true, as shown in the following example:

var endpointOption = new Option<Uri>("--endpoint") { IsRequired = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

The options section of the command help indicates the option is required:

Options:
  --endpoint <uri> (REQUIRED)
  --version               Show version information
  -?, -h, --help          Show help and usage information

If the command line for this example app doesn't include --endpoint, an error message is displayed and the command handler isn't called:

Option '--endpoint' is required.

If a required option has a default value, the option doesn't have to be specified on the command line. In that case, the default value provides the required option value.

Hidden commands, options, and arguments

You might want to support a command, option, or argument, but avoid making it easy to discover. For example, it might be a deprecated or administrative or preview feature. Use the IsHidden property to prevent users from discovering such features by using tab completion or help, as shown in the following example:

var endpointOption = new Option<Uri>("--endpoint") { IsHidden = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

The options section of this example's command help omits the --endpoint option.

Options:
  --version               Show version information
  -?, -h, --help          Show help and usage information

Set argument arity

You can explicitly set argument arity by using the Arity property, but in most cases that is not necessary. System.CommandLine automatically determines the argument arity based on the argument type:

Argument type Default arity
Boolean ArgumentArity.ZeroOrOne
Collection types ArgumentArity.ZeroOrMore
Everything else ArgumentArity.ExactlyOne

Multiple arguments

By default, when you call a command, you can repeat an option name to specify multiple arguments for an option that has maximum arity greater than one.

myapp --items one --items two --items three

To allow multiple arguments without repeating the option name, set Option.AllowMultipleArgumentsPerToken to true. This setting lets you enter the following command line.

myapp --items one two three

The same setting has a different effect if maximum argument arity is 1. It allows you to repeat an option but takes only the last value on the line. In the following example, the value three would be passed to the app.

myapp --item one --item two --item three

List valid argument values

To specify a list of valid values for an option or argument, specify an enum as the option type or use FromAmong, as shown in the following example:

var languageOption = new Option<string>(
    "--language",
    "An option that that must be one of the values of a static list.")
        .FromAmong(
            "csharp",
            "fsharp",
            "vb",
            "pwsh",
            "sql");

Here's an example of command-line input and the resulting output for the preceding example code:

myapp --language not-a-language

Argument 'not-a-language' not recognized. Must be one of:
        'csharp'
        'fsharp'
        'vb'
        'pwsh'
        'sql'

The options section of command help shows the valid values:

Options:
  --language <csharp|fsharp|vb|pwsh|sql>  An option that must be one of the values of a static list.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

Option and argument validation

For information about argument validation and how to customize it, see the following sections in the Parameter binding article:

See also