Skip to content

Configuration

Jump to bottom
Denis Zykov edited this page Oct 25, 2026 · 3 revisions

Configuration

General settings

You can change the behavior of CommandLine through a setting values in ICommandLineBuilder.Configure() method:

int Main(string[] arguments)
{
  var exitCode = CommandLine
    .CreateFromArguments(arguments)
    .Configure(config =>
    {

      config.DefaultVerbName = "Index";
//    ^----^ 
//    set CommandLineConfiguration values here
    })
    .Use<Program>()
    .Run();
  return exitCode;
}

Settings reference

Setting Default Description
DefaultVerbName null Verb to run when none is specified on the command line.
OutputHelpOnFailure true Print an error and help when binding fails. When false, a CommandLineException is passed to the exception handler instead.
OutputDetailedErrors false Print the full error message when binding fails.
OutputSubVerbHelpTitle false Print the description of the sub-verb class in the sub-verb list.
FailureExitCode 1 Exit code when binding fails (unknown verb, invalid or unknown options, no verb specified).
HelpExitCode 2 Exit code when help is requested.
UnhandledExceptionHandler null Called for exceptions thrown by a verb. See Error handling.
HookConsoleCancelKeyPress false Turn Ctrl+C into the verb's CancellationToken. See Cancellation.
MaxOutputWidth console width Maximum width of help text. Unlimited when output is redirected.
VerbNameMatchingMode OrdinalIgnoreCase How verb names are compared.
LongOptionNameMatchingMode OrdinalIgnoreCase How long option names (--name) are compared.
ShortOptionNameMatchingMode Ordinal How short option names (-n) are compared. Case-sensitive by default, so -v and -V can be different options.
ShortOptionNamePrefixes -, / Prefixes of short options.
LongOptionNamePrefixes --, / Prefixes of long options.
OptionArgumentSplitters ' ', '=' Characters separating an option from its value, as in --name=value.
OptionsBreaks -- Tokens that end options. Everything after is a value.
HelpOptions -h, /h, --help, -?, /? Options that request help.
TreatUnknownOptionsAsValues false See Unknown options.
AllowPrefixesInOptionValues true See Unknown options.
FailOnUnknownOptions false See Unknown options.

Configuration from file

CommandLineConfiguration is a plain class, so it could be bound from IConfiguration (appsettings.json) in .NET Generic Host:

{
  "CommandLine": {
    "DefaultVerbName": "Default",
    "OutputDetailedErrors": true,
    "FailOnUnknownOptions": true
  }
}

Unknown options

An option matching no parameter of the verb is an "unknown option". Three settings control what happens with it:

  • By default it is ignored, together with its =value:
> myapp paint --unknown --color Red
color=Red
  • AllowPrefixesInOptionValues (on by default) lets an option's value start with -- or /. As a side effect, an unknown option placed after an option that takes a value is captured as that option's value:
> myapp paint --color Red --unknown
Error: Invalid options or values specified for 'Paint' verb.
  --color    Option expects a single argument but received 2.

Set it to false and such unknown option is ignored like any other.

  • TreatUnknownOptionsAsValues = true passes unknown options to values instead of ignoring them.
  • FailOnUnknownOptions = true fails binding with an "Unknown option" error and FailureExitCode:
> myapp paint --color Red --unknown
Error: Invalid options or values specified for 'Paint' verb.
  --unknown    Unknown option.

While it is on, AllowPrefixesInOptionValues is treated as false, so an unknown option is never captured as a value. Verbs with sub-verbs are not checked, their sub-verbs are. Sub-verbs inherit the setting, and calling Configure() on a sub-verb's builder turns it on or off for that sub-verb set only:

public static int Account(ICommandLineBuilder subVerbBuilder) =>
  subVerbBuilder
    .Configure(config => config.FailOnUnknownOptions = true) // only for 'account' sub-verbs
    .Use<AccountApi>()
    .Run();

Error handling

Exit codes

Situation Exit code
Verb executed value returned by the verb
Help requested HelpExitCode (2)
Binding failed and OutputHelpOnFailure is true FailureExitCode (1)
Verb threw an exception, or binding failed and OutputHelpOnFailure is false CommandLine.DOT_NET_EXCEPTION_EXIT_CODE (-2147023895)

Exception handler

Exceptions thrown by a verb are not re-thrown. They are written to the standard error of IConsole and CommandLine.DOT_NET_EXCEPTION_EXIT_CODE is returned. To handle them yourself, set UnhandledExceptionHandler:

CommandLine
  .CreateFromArguments(arguments)
  .Configure(config =>
  {
    config.UnhandledExceptionHandler = (sender, args) => logger.LogError(args.Exception, "Verb failed.");
  })
  .Use<Program>()
  .Run();

Handlers could also be registered in your IServiceProvider as ExceptionEventHandler services. All registered handlers are called:

services.AddTransient<ExceptionEventHandler>(serviceProvider => (sender, args) => { /* ... */ });

With a handler set, the default output to standard error is replaced.

Custom service provider

You can provide your own service provider using 'ICommandLineBuilder.UseServiceProvider()' method:

int Main(string[] arguments)
{
  var services = new ServiceContainer();
  services.AddService(typeof(IConsole), new MyConsole());

  var exitCode = CommandLine
    .CreateFromArguments(arguments)

    .UseServiceProvider(() => services)
//                            ^------^
//                       your IServiceProvider
    .Use<Program>()
    .Run();
  return exitCode;
}

Services used by CommandLine itself are listed in Extensibility.

Clone this wiki locally