Arguments

Arguments are defined as parameters of a method or properties of a class (see Argument Models)

As discussed in Terminology, Option and Operand are the two concrete types of IArgument

• Option: named argument
• Operand: positional argument

By default, arguments are operands. Change the default by assigning AppSettings.DefaultArgumentMode = ArgumentMode.Option

Use the [Operand] and [Option] attributes to explicity denote which argument type and to configure the arguments.

Tip

See Option vs Operand for recommendations on when to use one vs the other.

Operand Attribute

The operand attribute has the following properties:

• Name: Used in help documentation only. Defaults to the parameter or property name.
• Description: Used in help documentation.

Option Attribute

The option attribute has the following properties:

• LongName: Used in help documentation and on the command line. Defaults to the parameter or property name.
• ShortName: Used in help documentation and on the command line. Defaults to null.
• Description: Used in help documentation.
• BooleanMode: When the option is a bool, this determines if the presence of the option indicates true (Implicit) or if the user must specify true or false (Explicit).
  • The default is Implicit and can be changed with AppSettings.BooleanMode = BooleanMode.Explicit
  • Implicit boolean options are also called Flags
• AssignToExecutableSubcommands: only valid when used in Interceptor methods.

ShortName and LongName interactions

When ShortName is set, LongName will no longer default to the parameter or property name. If an option should have both a short and long name, then both attributes need to be set. This can result in duplicating the name that was already used to define the option.

In the next major release, this behavior will change so that LongName will always default to the parameter or property name. An option can be configured to have only a short name by setting LongName = null.

In the meantime, this behavior can be achieved by setting AppSettings.LongNameAlwaysDefaultsToSymbolName = true

Example

public void LaunchRocket(
    [Operand(Name = "planet", 
        Description = "Name of the planet you wish the rocket to go")] 
    string planetName,
    [Option(LongName = "turbo", ShortName = "t", 
        Description = "Name of the planet you wish the rocket to go")] 
    bool turbo,
    [Option(ShortName="a",
         Description="Abort the launch before takeoff", 
         BooleanMode=BooleanMode.Explicit)]
    bool abort)

and help looks like:

Usage: dotnet CommandDotNet.Example.dll launch-rocket [options] [arguments]  

Arguments:                                                                   

  planet  <TEXT>                                                             
  Name of the planet you wish the rocket to go                               

Options:                                                                     

  -t | --turbo                                                               
  Name of the planet you wish the rocket to go                               

  -a      <BOOLEAN>                                                    
  Abort the launch before takeoff                                            
  Allowed values: true, false                                                

and called any of these ways:

dotnet example.dll LaunchRocket -t -a true mars
dotnet example.dll LaunchRocket --turbo -a true mars
dotnet example.dll LaunchRocket mars -t -a true
dotnet example.dll LaunchRocket mars --turbo -a true

Options are not positional so they can appear in any order within the command.

Configuring a ShortName nullifies the default long name so LongName must also be configured if you need both.

Parameter name	Longname	Shortname	Generated template
turbo			--turbo
turbo	turbo		--turbo
turbo		t	-t
turbo	turbo	t	-t | --turbo
t			-t

Flags

Flags are boolean options with a default value of false. The presence of the flag indicates true. This simplifies the user experience by allowing them to specifiy -b instead of -b true. This also enables clubbing.

Define them as Options with BooleanMode = BooleanMode.Implicit. Implicit is the default defined for AppSettings.DefaultBooleanMode or OptionAttribute.BooleanMode.

Flag Clubbing

Clubbing (aka bundling) is when several flags are specified together using their short names.

For example: -abc is the same as -a -b -c

Clubbing is only available for flags by short name.

Option assignments

When assigning option values, the following are the same

• --time tomorrow
• --time=tomorrow
• --time:tomorrow