Edit

Share via

Tutorial: Get started with System.CommandLine

Important

System.CommandLine is currently in PREVIEW, and this documentation is for version 2.0 beta 5. 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 tutorial shows how to create a .NET command-line app that uses the System.CommandLine library. You'll begin by creating a simple root command that has one option. Then you'll build on that base, creating a more complex app that contains multiple subcommands and different options for each command.

In this tutorial, you learn how to:

  • Create commands, options, and arguments.
  • Specify default values for options.
  • Assign options and arguments to commands.
  • Assign an option recursively to all subcommands under a command.
  • Work with multiple levels of nested subcommands.
  • Create aliases for commands and options.
  • Work with string, string[], int, bool, FileInfo, and enum option types.
  • Read option values in command action code.
  • Use custom code for parsing and validating options.

Prerequisites

Or

Create the app

Create a .NET 9 console app project named "scl".

  1. Create a folder named scl for the project, and then open a command prompt in the new folder.

  2. Run the following command:

    dotnet new console --framework net9.0

Install the System.CommandLine package

  • Run the following command:

    dotnet add package System.CommandLine --prerelease

    Or, in .NET 10+:

    dotnet package add System.CommandLine --prerelease

    The --prerelease option is necessary because the library is still in beta.

Parse the arguments

  1. Replace the contents of Program.cs with the following code:

    using System.CommandLine;
using System.CommandLine.Parsing;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        ParseResult parseResult = rootCommand.Parse(args);
        if (parseResult.GetValue(fileOption) is FileInfo parsedFile)
        {
            ReadFile(parsedFile);
            return 0;
        }
        foreach (ParseError parseError in parseResult.Errors)
        {
            Console.Error.WriteLine(parseError.Message);
        }
        return 1;
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

The preceding code:

Option<FileInfo> fileOption = new("--file")
{
    Description = "The file to read and display on the console."
};

RootCommand rootCommand = new("Sample app for System.CommandLine");
rootCommand.Options.Add(fileOption);
  • Parses the args and checks whether any value was provided for --file option. If so, it calls the ReadFile method using parsed value and returns 0 exit code:
ParseResult parseResult = rootCommand.Parse(args);
if (parseResult.GetValue(fileOption) is FileInfo parsedFile)
{
    ReadFile(parsedFile);
    return 0;
}
  • If no value was provided for --file, it prints available parse errors and returns 1 exit code:
foreach (ParseError parseError in parseResult.Errors)
{
    Console.Error.WriteLine(parseError.Message);
}
return 1;
  • The ReadFile method reads the specified file and displays its contents on the console:
static void ReadFile(FileInfo file)
{
    foreach (string line in File.ReadLines(file.FullName))
    {
        Console.WriteLine(line);
    }
}

Test the app

You can use any of the following ways to test while developing a command-line app:

  • Run the dotnet build command, and then open a command prompt in the scl/bin/Debug/net9.0 folder to run the executable:

    dotnet build
cd bin/Debug/net9.0
scl --file scl.runtimeconfig.json

  • Use dotnet run and pass option values to the app instead of to the run command by including them after --, as in the following example:

    dotnet run -- --file bin/Debug/net9.0/scl.runtimeconfig.json

This tutorial assumes you're using the first of these options.

When you run the app, it displays the contents of the file specified by the --file option.

{
  "runtimeOptions": {
    "tfm": "net9.0",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "9.0.0"
    }
  }
}

But what happens if you ask it to display the help by providing --help? Nothing gets printed to the console, because the app doesn't yet handle the scenario where --file is not provided and there are no parse errors.

Parse the arguments and invoke the ParseResult

System.CommandLine allows you to specify an action that's invoked when a given symbol (command, directive, or option) is parsed successfully. The action is a delegate that takes a System.CommandLine.ParseResult parameter and returns an int exit code (async actions are also available). The exit code is returned by the System.CommandLine.Parsing.ParseResult.Invoke method and can be used to indicate whether the command was executed successfully or not.

  1. Replace the contents of Program.cs with the following code:

    using System.CommandLine;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        rootCommand.SetAction(parseResult =>
        {
            FileInfo parsedFile = parseResult.GetValue(fileOption);
            ReadFile(parsedFile);
            return 0;
        });

        ParseResult parseResult = rootCommand.Parse(args);
        return parseResult.Invoke();
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

The preceding code:

  • Specifies that ReadFile is the method that will be called when the root command is invoked:

    rootCommand.SetAction(parseResult =>
{
    FileInfo parsedFile = parseResult.GetValue(fileOption);
    ReadFile(parsedFile);
    return 0;
});

  • Parses the args and invokes the result:

    ParseResult parseResult = rootCommand.Parse(args);
return parseResult.Invoke();

When you run the app, it displays the contents of the file specified by the --file option.

What happens if you ask it to display the help by providing --help?

scl --help

Following output gets printed:

Description:
  Sample app for System.CommandLine

Usage:
  scl [options]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information
  --file          The file to read and display on the conso

System.CommandLine.RootCommand by default provides Help option, Version option and Suggest directive. ParseResult.Invoke method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for our command, or the help action defined by System.CommandLine for System.CommandLine.Help.HelpOption. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output and returns 1 exit code:

scl --invalid bla

Unrecognized command or argument '--invalid'.
Unrecognized command or argument 'bla'.

Add a subcommand and options

In this section, you:

  • Create more options.
  • Create a subcommand.
  • Assign the new options to the new subcommand.

The new options will let you configure the foreground and background text colors and the readout speed. These features will be used to read a collection of quotes that comes from the Teleprompter console app tutorial.

  1. Copy the sampleQuotes.txt file from the GitHub repository for this sample into your project directory. For information on how to download files, see the instructions in Samples and Tutorials.

  2. Open the project file and add an <ItemGroup> element just before the closing </Project> tag:

    <ItemGroup>
  <Content Include="sampleQuotes.txt">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

    Adding this markup causes the text file to be copied to the bin/debug/net9.0 folder when you build the app. So when you run the executable in that folder, you can access the file by name without specifying a folder path.

  3. In Program.cs, after the code that creates the --file option, create options to control the readout speed and text colors:

    Option<int> delayOption = new("--delay")
{
    Description = "Delay between lines, specified as milliseconds per character in a line.",
    DefaultValueFactory = parseResult => 42
};
Option<ConsoleColor> fgcolorOption = new("--fgcolor")
{
    Description = "Foreground color of text displayed on the console.",
    DefaultValueFactory = parseResult => ConsoleColor.White
};
Option<bool> lightModeOption = new("--light-mode")
{
    Description = "Background color of text displayed on the console: default is black, light mode is white."
};

  4. After the line that creates the root command, delete the code that adds the --file option to it. You're removing it here because you'll add it to a new subcommand.

  5. After the line that creates the root command, create a read subcommand. Add the options to this subcommand (by using collection initializer syntax rather than Options property), and add the subcommand to the root command.

    Command readCommand = new("read", "Read and display the file.")
{
    fileOption,
    delayOption,
    fgcolorOption,
    lightModeOption
};
rootCommand.Subcommands.Add(readCommand);

  6. Replace the SetAction code with the following SetAction code for the new subcommand:

    readCommand.SetAction(parseResult => ReadFile(
    parseResult.GetValue(fileOption),
    parseResult.GetValue(delayOption),
    parseResult.GetValue(fgcolorOption),
    parseResult.GetValue(lightModeOption)));

    You're no longer calling SetAction on the root command because the root command no longer needs an action. When a command has subcommands, you typically have to specify one of the subcommands when invoking a command-line app.

  7. Replace the ReadFile action method with the following code:

    internal static void ReadFile(FileInfo file, int delay, ConsoleColor fgColor, bool lightMode)
{
    Console.BackgroundColor = lightMode ? ConsoleColor.White : ConsoleColor.Black;
    Console.ForegroundColor = fgColor;
    foreach (string line in File.ReadLines(file.FullName))
    {
        Console.WriteLine(line);
        Thread.Sleep(TimeSpan.FromMilliseconds(delay * line.Length));
    }
}

The app now looks like this:

using System.CommandLine;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        Option<int> delayOption = new("--delay")
        {
            Description = "Delay between lines, specified as milliseconds per character in a line.",
            DefaultValueFactory = parseResult => 42
        };
        Option<ConsoleColor> fgcolorOption = new("--fgcolor")
        {
            Description = "Foreground color of text displayed on the console.",
            DefaultValueFactory = parseResult => ConsoleColor.White
        };
        Option<bool> lightModeOption = new("--light-mode")
        {
            Description = "Background color of text displayed on the console: default is black, light mode is white."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");

        Command readCommand = new("read", "Read and display the file.")
        {
            fileOption,
            delayOption,
            fgcolorOption,
            lightModeOption
        };
        rootCommand.Subcommands.Add(readCommand);

        readCommand.SetAction(parseResult => ReadFile(
            parseResult.GetValue(fileOption),
            parseResult.GetValue(delayOption),
            parseResult.GetValue(fgcolorOption),
            parseResult.GetValue(lightModeOption)));

        return rootCommand.Parse(args).Invoke();
    }

    internal static void ReadFile(FileInfo file, int delay, ConsoleColor fgColor, bool lightMode)
    {
        Console.BackgroundColor = lightMode ? ConsoleColor.White : ConsoleColor.Black;
        Console.ForegroundColor = fgColor;
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
            Thread.Sleep(TimeSpan.FromMilliseconds(delay * line.Length));
        }
    }
}

Test the new subcommand

Now if you try to run the app without specifying the subcommand, you get an error message followed by a help message that specifies the subcommand that is available.

scl --file sampleQuotes.txt

'--file' was not matched. Did you mean one of the following?
--help

Required command was not provided.
Unrecognized command or argument '--file'.
Unrecognized command or argument 'sampleQuotes.txt'.

Description:
  Sample app for System.CommandLine

Usage:
  scl [command] [options]

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

Commands:
  read  Read and display the file.

The help text for subcommand read shows that four options are available. It shows valid values for the enum.

scl read -h

Description:
  Read and display the file.

Usage:
  scl read [options]

Options:
  --file <file>                                               The file to read and display on the console.
  --delay <delay>                                             Delay between lines, specified as milliseconds per
                                                              character in a line. [default: 42]
  --fgcolor                                                   Foreground color of text displayed on the console.
  <Black|Blue|Cyan|DarkBlue|DarkCyan|DarkGray|DarkGreen|Dark  [default: White]
  Magenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|White|Ye
  llow>
  --light-mode                                                Background color of text displayed on the console:
                                                              default is black, light mode is white.
  -?, -h, --help                                              Show help and usage information

Run subcommand read specifying only the --file option, and you get the default values for the other three options.

scl read --file sampleQuotes.txt

The 42 milliseconds per character default delay causes a slow readout speed. You can speed it up by setting --delay to a lower number.

scl read --file sampleQuotes.txt --delay 0

You can use --fgcolor and --light-mode to set text colors:

scl read --file sampleQuotes.txt --fgcolor red --light-mode

Provide an invalid value for --delay and you get an error message:

scl read --file sampleQuotes.txt --delay forty-two

Cannot parse argument 'forty-two' for option '--int' as expected type 'System.Int32'.

Provide an invalid value for --file and you get an exception:

scl read --file nofile

Unhandled exception: System.IO.FileNotFoundException: Could not find file 'C:\bin\Debug\net9.0\nofile''.
File name: 'C:\bin\Debug\net9.0\nofile''

Add subcommands and custom validation

This section creates the final version of the app. When finished, the app will have the following commands and options:

  • root command with a recursive* option named --file
    • quotes command
      • read command with options named --delay, --fgcolor, and --light-mode
      • add command with arguments named quote and byline
      • delete command with option named --search-terms

* A recursive option is available to the command it's assigned to and recursively to all its subcommands.

Here's sample command line input that invokes each of the available commands with its options and arguments:

scl quotes read --file sampleQuotes.txt --delay 40 --fgcolor red --light-mode
scl quotes add "Hello world!" "Nancy Davolio"
scl quotes delete --search-terms David "You can do" Antoine "Perfection is achieved"

  1. In Program.cs, replace the code that creates the --file option with the following code:

    Option<FileInfo> fileOption = new("--file")
{
    Description = "An option whose argument is parsed as a FileInfo",
    Required = true,
    DefaultValueFactory = result =>
    {
        if (result.Tokens.Count == 0)
        {
            return new FileInfo("sampleQuotes.txt");

        }
        string filePath = result.Tokens.Single().Value;
        if (!File.Exists(filePath))
        {
            result.AddError("File does not exist");
            return null;
        }
        else
        {
            return new FileInfo(filePath);
        }
    }
};

    This code uses System.CommandLine.Parsing.ArgumentResult to provide custom parsing, validation, and error handling.

    Without this code, missing files are reported with an exception and stack trace. With this code just the specified error message is displayed.

    This code also specifies a default value, which is why it sets DefaultValueFactory to custom parsing method.

  2. After the code that creates lightModeOption, add options and arguments for the add and delete commands:

    Option<string[]> searchTermsOption = new("--search-terms")
{
    Description = "Strings to search for when deleting entries.",
    Required = true,
    AllowMultipleArgumentsPerToken = true
};
Argument<string> quoteArgument = new("quote")
{
    Description = "Text of quote."
};
Argument<string> bylineArgument = new("byline")
{
    Description = "Byline of quote."
};

    The xref:System.CommandLine.Option.AllowMultipleArgumentsPerToken setting lets you omit the --search-terms option name when specifying elements in the list after the first one. It makes the following examples of command-line input equivalent:

    scl quotes delete --search-terms David "You can do"
scl quotes delete --search-terms David --search-terms "You can do"

  3. Replace the code that creates the root command and the read command with the following code:

    RootCommand rootCommand = new("Sample app for System.CommandLine");
fileOption.Recursive = true;
rootCommand.Options.Add(fileOption);

Command quotesCommand = new("quotes", "Work with a file that contains quotes.");
rootCommand.Subcommands.Add(quotesCommand);

Command readCommand = new("read", "Read and display the file.")
{
    delayOption,
    fgcolorOption,
    lightModeOption
};
quotesCommand.Subcommands.Add(readCommand);

Command deleteCommand = new("delete", "Delete lines from the file.");
deleteCommand.Options.Add(searchTermsOption);
quotesCommand.Subcommands.Add(deleteCommand);

Command addCommand = new("add", "Add an entry to the file.");
addCommand.Arguments.Add(quoteArgument);
addCommand.Arguments.Add(bylineArgument);
addCommand.Aliases.Add("insert");
quotesCommand.Subcommands.Add(addCommand);

    This code makes the following changes:

    • Removes the --file option from the read command.

    • Adds the --file option as a recursive option to the root command.

    • Creates a quotes command and adds it to the root command.

    • Adds the read command to the quotes command instead of to the root command.

    • Creates add and delete commands and adds them to the quotes command.

    The result is the following command hierarchy:

    • Root command
      • quotes
        • read
        • add
        • delete

    The app now implements the recommended pattern where the parent command (quotes) specifies an area or group, and its children commands (read, add, delete) are actions.

    Recursive options are applied to the command and recursively to subcommands. Since --file is on the root command, it will be available automatically in all subcommands of the app.

  4. After the SetAction code, add new SetAction code for the new subcommands:

    deleteCommand.SetAction(parseResult => DeleteFromFile(
    parseResult.GetValue(fileOption),
    parseResult.GetValue(searchTermsOption)));

addCommand.SetAction(parseResult => AddToFile(
    parseResult.GetValue(fileOption),
    parseResult.GetValue(quoteArgument),
    parseResult.GetValue(bylineArgument))
    );

    Subcommand quotes doesn't have an action because it isn't a leaf command. Subcommands read, add, and delete are leaf commands under quotes, and SetAction is called for each of them.

  5. Add the actions for add and delete.

    internal static void DeleteFromFile(FileInfo file, string[] searchTerms)
{
    Console.WriteLine("Deleting from file");

    var lines = File.ReadLines(file.FullName).Where(line => searchTerms.All(s => !line.Contains(s)));
    File.WriteAllLines(file.FullName, lines);
}
internal static void AddToFile(FileInfo file, string quote, string byline)
{
    Console.WriteLine("Adding to file");

    using StreamWriter writer = file.AppendText();
    writer.WriteLine($"{Environment.NewLine}{Environment.NewLine}{quote}");
    writer.WriteLine($"{Environment.NewLine}-{byline}");
}

The finished app looks like this:

using System.CommandLine;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "An option whose argument is parsed as a FileInfo",
            Required = true,
            DefaultValueFactory = result =>
            {
                if (result.Tokens.Count == 0)
                {
                    return new FileInfo("sampleQuotes.txt");

                }
                string filePath = result.Tokens.Single().Value;
                if (!File.Exists(filePath))
                {
                    result.AddError("File does not exist");
                    return null;
                }
                else
                {
                    return new FileInfo(filePath);
                }
            }
        };

        Option<int> delayOption = new("--delay")
        {
            Description = "Delay between lines, specified as milliseconds per character in a line.",
            DefaultValueFactory = parseResult => 42
        };
        Option<ConsoleColor> fgcolorOption = new("--fgcolor")
        {
            Description = "Foreground color of text displayed on the console.",
            DefaultValueFactory = parseResult => ConsoleColor.White
        };
        Option<bool> lightModeOption = new("--light-mode")
        {
            Description = "Background color of text displayed on the console: default is black, light mode is white."
        };

        Option<string[]> searchTermsOption = new("--search-terms")
        {
            Description = "Strings to search for when deleting entries.",
            Required = true,
            AllowMultipleArgumentsPerToken = true
        };
        Argument<string> quoteArgument = new("quote")
        {
            Description = "Text of quote."
        };
        Argument<string> bylineArgument = new("byline")
        {
            Description = "Byline of quote."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        fileOption.Recursive = true;
        rootCommand.Options.Add(fileOption);

        Command quotesCommand = new("quotes", "Work with a file that contains quotes.");
        rootCommand.Subcommands.Add(quotesCommand);

        Command readCommand = new("read", "Read and display the file.")
        {
            delayOption,
            fgcolorOption,
            lightModeOption
        };
        quotesCommand.Subcommands.Add(readCommand);

        Command deleteCommand = new("delete", "Delete lines from the file.");
        deleteCommand.Options.Add(searchTermsOption);
        quotesCommand.Subcommands.Add(deleteCommand);

        Command addCommand = new("add", "Add an entry to the file.");
        addCommand.Arguments.Add(quoteArgument);
        addCommand.Arguments.Add(bylineArgument);
        addCommand.Aliases.Add("insert");
        quotesCommand.Subcommands.Add(addCommand);

        readCommand.SetAction(parseResult => ReadFile(
            parseResult.GetValue(fileOption),
            parseResult.GetValue(delayOption),
            parseResult.GetValue(fgcolorOption),
            parseResult.GetValue(lightModeOption)));

        deleteCommand.SetAction(parseResult => DeleteFromFile(
            parseResult.GetValue(fileOption),
            parseResult.GetValue(searchTermsOption)));

        addCommand.SetAction(parseResult => AddToFile(
            parseResult.GetValue(fileOption),
            parseResult.GetValue(quoteArgument),
            parseResult.GetValue(bylineArgument))
            );

        return rootCommand.Parse(args).Invoke();
    }

    internal static void ReadFile(FileInfo file, int delay, ConsoleColor fgColor, bool lightMode)
    {
        Console.BackgroundColor = lightMode ? ConsoleColor.White : ConsoleColor.Black;
        Console.ForegroundColor = fgColor;
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
            Thread.Sleep(TimeSpan.FromMilliseconds(delay * line.Length));
        }
    }
    internal static void DeleteFromFile(FileInfo file, string[] searchTerms)
    {
        Console.WriteLine("Deleting from file");

        var lines = File.ReadLines(file.FullName).Where(line => searchTerms.All(s => !line.Contains(s)));
        File.WriteAllLines(file.FullName, lines);
    }
    internal static void AddToFile(FileInfo file, string quote, string byline)
    {
        Console.WriteLine("Adding to file");

        using StreamWriter writer = file.AppendText();
        writer.WriteLine($"{Environment.NewLine}{Environment.NewLine}{quote}");
        writer.WriteLine($"{Environment.NewLine}-{byline}");
    }
}

Build the project, and then try the following commands.

Submit a nonexistent file to --file with the read command, and you get an error message instead of an exception and stack trace:

scl quotes read --file nofile

File does not exist

Try to run subcommand quotes and you get a message directing you to use read, add, or delete:

scl quotes

Required command was not provided.

Description:
  Work with a file that contains quotes.

Usage:
  scl quotes [command] [options]

Options:
  --file <file>   An option whose argument is parsed as a FileInfo [default: sampleQuotes.txt]
  -?, -h, --help  Show help and usage information

Commands:
  read                          Read and display the file.
  delete                        Delete lines from the file.
  add, insert <quote> <byline>  Add an entry to the file.

Run subcommand add, and then look at the end of the text file to see the added text:

scl quotes add "Hello world!" "Nancy Davolio"

Run subcommand delete with search strings from the beginning of the file, and then look at the beginning of the text file to see where text was removed:

scl quotes delete --search-terms David "You can do" Antoine "Perfection is achieved"

Note

If you're running in the bin/debug/net9.0 folder, that folder is where you'll find the file with changes from the add and delete commands. The copy of the file in the project folder remains unchanged.

Next steps

In this tutorial, you created a simple command-line app that uses System.CommandLine. To learn more about the library, see System.CommandLine overview.