System.CommandLine Documentation

This repository provides the core libraries and tools for building command-line interfaces in .NET:

• System.CommandLine: A library for command-line parsing, model binding, invocation, and shell completions.
• dotnet-suggest: A global tool designed to provide shell completions for applications built using System.CommandLine.

The official documentation for System.CommandLine has moved. You can find all guides, API references, and usage instructions at the Microsoft Docs website.

https://docs.microsoft.com/en-us/dotnet/standard/commandline/

Once the completions command is integrated, users can generate scripts for their specific shell. If the shell argument is omitted, the tool detects the current shell from the environment (e.g., SHELL on Unix or PowerShell on Windows).

# Generate a script for a specific shell
> myapp completions script bash > ~/.local/share/bash-completion/completions/myapp

# The shell argument is optional - it defaults to the current shell
> myapp completions script >> $PROFILE

Arcade provides two distinct template sets depending on your pipeline requirements:

• 1ES Pipeline Templates: Use eng/common/templates-official for any internal production-graded pipelines or runs that must be managed by 1ES pipeline templates (including 1ES Microbuild templates).
• Standard Templates: Use eng/common/templates for all other pipeline runs.

Refer to azure-pipelines.yml for a templates-official example and azure-pipelines-pr.yml for a standard templates example.

You can consume these libraries via NuGet.

• Use System.CommandLine to build your CLI application logic.
• Use dotnet-suggest as a global tool to enable shell completion features for your users.

To enable tab completion in zsh, generate the completion script using dotnet-suggest script zsh, save it to a shim file, and source it in your ~/.zshrc file.

dotnet-suggest script zsh >~/.dotnet-suggest-shim.zsh
echo '. ~/.dotnet-suggest-shim.zsh' >>~/.zshrc

Use RootCommand to create the entry point of your application. A RootCommand automatically provides --help and --version options and integrates with dotnet-suggest for shell completions. You can define Options and use SetAction to define the logic that executes when the command is run.

using System.CommandLine;

RootCommand rootCommand = new("Sample command-line app");

Option<string> nameOption = new("--name", "-n")
{
    Description = "Your name"
};

rootCommand.Options.Add(nameOption);

rootCommand.SetAction(parseResult =>
{
    string name = parseResult.GetValue(nameOption);
    Console.WriteLine($"Hello, {name ?? "World"}!");
});

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

System.CommandLine supports tab completion. You can add custom suggestions to options using CompletionSources. To allow users to use these completions, they should install dotnet-suggest and register your command.

// Add custom completions using CompletionSources
var fileOption = new Option<FileInfo>("--file")
{
    Description = "The file to process"
};

fileOption.CompletionSources.Add(ctx =>
    // hard-coded list of files
    ["file1.txt", "file2.txt", "file3.txt" ]
);

// Or add simple string suggestions
fileOption.CompletionSources.Add("option1", "option2", "option3");

// To use in shell:
// 1. Install dotnet-suggest
// 2. Register your app:
// dotnet suggest register --command-path /path/to/myapp

To enable tab completion in PowerShell, add the contents of the dotnet-suggest-shim.ps1 script to your PowerShell profile. You can locate your profile path by running echo $profile in your PowerShell console.

> echo $profile

To enable tab completion in bash, generate the completion script using dotnet-suggest script bash, save it to a shim file, and source it in your ~/.bashrc file.

dotnet-suggest script bash >~/.dotnet-suggest-shim.bash
echo '. ~/.dotnet-suggest-shim.bash' >>~/.bashrc