Tab completion for System.CommandLine

Apps that use System.CommandLine have built-in support for tab completion in certain shells. To enable it, the end user must take a few steps once per shell. Once this is done, tab completion is automatic for static values in your app, such as enum values or values defined by calling System.CommandLine.Option<T>.AcceptOnlyFromAmong. You can also customize tab completion by providing values dynamically at runtime.

Enable tab completion

On the machine where you want to enable tab completion, follow these steps.

For the .NET CLI:

• See How to enable tab completion.

For other command-line apps built on System.CommandLine:

• Install the dotnet-suggest global tool.

• Add the appropriate shim script to your shell profile. You might need to create a shell profile file. The shim script forwards completion requests from your shell to the dotnet-suggest tool, which delegates them to the appropriate System.CommandLine-based app.

  • For bash, add the contents of dotnet-suggest-shim.bash to ~/.bash_profile.

  • For zsh, add the contents of dotnet-suggest-shim.zsh to ~/.zshrc.

  • For PowerShell, add the contents of dotnet-suggest-shim.ps1 to your PowerShell profile. You can find the expected path to your PowerShell profile by running the following command in your console:

    echo $profile
    

• Register the app by calling dotnet-suggest register --command-path $executableFilePath, where $executableFilePath is the path to the app's executable file.

Once the user's shell is set up and the executable is registered, completions will work for all apps that are built by using System.CommandLine.

For cmd.exe on Windows (the Windows Command Prompt) there is no pluggable tab completion mechanism, so no shim script is available. For other shells, look for a GitHub issue that is labeled Area-Completions. If you don't find an issue, you can open a new one.

Get tab completion values at run-time

The following code shows an app that retrieves values for tab completion dynamically at runtime. The code gets a list of the next two weeks of dates following the current date. The list is provided to the --date option by calling CompletionSources.Add:

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

new DateCommand().Parse(args).Invoke();

class DateCommand : Command
{
    private Argument<string> subjectArgument = new("subject")
    {
        Description = "The subject of the appointment."
    };
    private Option<DateTime> dateOption = new("--date")
    {
        Description = "The day of week to schedule. Should be within one week."
    };

    public DateCommand() : base("schedule", "Makes an appointment for sometime in the next week.")
    {
        this.Arguments.Add(subjectArgument);
        this.Options.Add(dateOption);

        dateOption.CompletionSources.Add(ctx => {
            var today = System.DateTime.Today;
            List<CompletionItem> dates = new();
            foreach (var i in Enumerable.Range(1, 7))
            {
                var date = today.AddDays(i);
                dates.Add(new CompletionItem(
                    label: date.ToShortDateString(),
                    sortText: $"{i:2}"));
            }
            return dates;
        });

        this.SetAction(parseResult =>
        {
            Console.WriteLine($"Scheduled \"{parseResult.GetValue(subjectArgument)}\" for {parseResult.GetValue(dateOption)}");
        });
    }
}

The values shown when the Tab key is pressed are provided as CompletionItem instances:

dates.Add(new CompletionItem(
    label: date.ToShortDateString(),
    sortText: $"{i:2}"));

The following CompletionItem properties are set:

• Label is the completion value to be shown.
• SortText ensures that the values in the list are presented in the correct order. It is set by converting i to a two-digit string, so that sorting is based on 01, 02, 03, and so on, through 14. If you do not set this parameter, sorting is based on the Label, which in this example is in short date format and will not sort correctly.

There are other CompletionItem properties, such as Documentation and Detail, but they are not yet used in System.CommandLine.

The dynamic tab completion list created by this code also appears in help output:

Description:
  Makes an appointment for sometime in the next week.

Usage:
  schedule <subject> [options]

Arguments:
  <subject>  The subject of the appointment.

Options:
  --date                                                                          The day of week to schedule. Should be within one week.
  <2/4/2022|2/5/2022|2/6/2022|2/7/2022|2/8/2022|2/9/2022|2/10/2022>
  --version                                                                       Show version information
  -?, -h, --help

See also

System.CommandLine overview