Name: DotMake.CommandLine
Author: dotmake

DotMake.CommandLine v2.3.0 — nugetz

dotnet add package DotMake.CommandLine

PM> Install-Package DotMake.CommandLine

using System;
using DotMake.CommandLine;

// Add this single line to run you app!
Cli.Run<RootCliCommand>(args);

// Create a simple class like this to define your root command:
[CliCommand(Description = "A root cli command")]
public class RootCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";
 
    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }
 
    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();
    }
}

await Cli.RunAsync<RootCliCommand>(args);

try
{
    Cli.Run<RootCliCommand>(args);
}
catch (Exception e)
{
    Console.WriteLine(@"Exception in main: {0}", e.Message);
}

Cli.Run<RootCliCommand>(args, new CliSettings { EnableDefaultExceptionHandler = true });

var parseResult = Cli.Parse<RootCliCommand>(args);
var rootCliCommand = parseResult.Bind<RootCliCommand>();

var parseResult = Cli.Parse<RootCliCommand>(args);
if (parseResult.Errors.Count > 0)
{

}

using System;
using DotMake.CommandLine;

Cli.Run(([CliArgument]string arg1, bool opt1) =>
{
    Console.WriteLine($@"Value for {nameof(arg1)} parameter is '{arg1}'");
    Console.WriteLine($@"Value for {nameof(opt1)} parameter is '{opt1}'");
});

using System;
using DotMake.CommandLine;
 
[CliCommand(
    Description = "A cli command with snake_case name casing and forward slash prefix conventions",
    NameCasingConvention = CliNameCasingConvention.SnakeCase,
    NamePrefixConvention = CliNamePrefixConvention.ForwardSlash,
    ShortFormPrefixConvention = CliNamePrefixConvention.ForwardSlash
)]
public class RootSnakeSlashCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";
 
    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }
 
    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();
    }
}

DotMake Command-Line TestApp v1.6.0
Copyright © 2023-2024 DotMake

A cli command with snake_case name casing and forward slash prefix conventions

Usage:
  TestApp <argument_1> [options]

Arguments:
  <argument_1>  Description for Argument1 [required]

Options:
  /o, /option_1 <option_1>  Description for Option1 [default: DefaultForOption1]
  /v, /version              Show version information
  -?, -h, /help             Show help and usage information

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.Red });

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.DarkRed });

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.Green });

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.DarkGreen });

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.Blue });

Cli.Run<RootCliCommand>(args, new CliSettings { Theme = CliTheme.DarkBlue });

Cli.Run<RootCliCommand>(args, new CliSettings
{
    Theme = new CliTheme(CliTheme.Default)
    {
        HeadingCasing = CliNameCasingConvention.UpperCase,
        HeadingNoColon = true
    }
});

[CliCommand(Description = nameof(TestResources.CommandDescription))]
internal class LocalizedCliCommand
{
    [CliOption(Description = nameof(TestResources.OptionDescription))]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = nameof(TestResources.ArgumentDescription))]
    public string Argument1 { get; set; }

    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();
    }
}

[CliCommand(Description = "A root cli command")]
public class HelpCliCommand
{
  [CliOption(Description = "Description for Option1")]
  public string Option1 { get; set; } = "DefaultForOption1";

  [CliArgument(Description = "Description for Argument1")]
  public string Argument1 { get; set; } = "DefaultForArgument1";

  [CliCommand(Description = "A sub cli command")]
  public class SubCliCommand
  {
      [CliArgument(Description = "Description for Argument2")]
      public string Argument2 { get; set; } = "DefaultForArgument2";

      public void Run(CliContext context)
      {
          if (context.IsEmptyCommand())
              context.ShowHelp();
          else
              context.ShowValues();
      }
  }
}

/*
    Command hierarchy in below example is:
        
     TestApp
     └╴level-1
       └╴level-2
*/

[CliCommand(Description = "A root cli command with nested children")]
public class RootWithNestedChildrenCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; } = "DefaultForArgument1";

    public void Run(CliContext context)
    {
        if (context.IsEmptyCommand())
            context.ShowHierarchy();
        else
            context.ShowValues();
    }

    [CliCommand(Description = "A nested level 1 sub-command")]
    public class Level1SubCliCommand
    {
        [CliOption(Description = "Description for Option1")]
        public string Option1 { get; set; } = "DefaultForOption1";

        [CliArgument(Description = "Description for Argument1")]
        public string Argument1 { get; set; }

        public void Run(CliContext context)
        {
            context.ShowValues();
        }

        [CliCommand(Description = "A nested level 2 sub-command")]
        public class Level2SubCliCommand
        {
            [CliOption(Description = "Description for Option1")]
            public string Option1 { get; set; } = "DefaultForOption1";

            [CliArgument(Description = "Description for Argument1")]
            public string Argument1 { get; set; }

            public void Run(CliContext context)
            {
                context.ShowValues();
            }
        }
    }
}

/*
    Command hierarchy in below example is:

     TestApp
     └╴external-level-1
       └╴external-level-2
*/

[CliCommand(
    Description = "A root cli command with external children",
    Children = new []
    {
        typeof(ExternalLevel1SubCliCommand)
    }
)]
public class RootWithExternalChildrenCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; } = "DefaultForArgument1";

    public void Run(CliContext context)
    {
        if (context.IsEmptyCommand())
            context.ShowHierarchy();
        else
            context.ShowValues();
    }
}

[CliCommand(
    Description = "An external level 1 sub-command",
    Children = new[]
    {
        typeof(ExternalLevel2SubCliCommand)
    }
)]
public class ExternalLevel1SubCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}

[CliCommand(Description = "An external level 2 sub-command")]
public class ExternalLevel2SubCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}

/*
    Command hierarchy in below example is:

     TestApp
     └╴external-level-1-with-parent
       └╴external-level-2-with-parent
*/

[CliCommand(
    Description = "A root cli command with external children"
)]
public class RootAsExternalParentCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; } = "DefaultForArgument1";

    public void Run(CliContext context)
    {
        if (context.IsEmptyCommand())
            context.ShowHierarchy();
        else
            context.ShowValues();
    }
}

[CliCommand(
    Description = "An external level 1 sub-command",
    Parent = typeof(RootAsExternalParentCliCommand)
)]
public class ExternalLevel1WithParentSubCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}

[CliCommand(
    Description = "An external level 2 sub-command",
    Parent = typeof(ExternalLevel1WithParentSubCliCommand)
)]
public class ExternalLevel2WithParentSubCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}

 TestApp
 ├╴external-level-1-with-nested
 │ └╴level-2
 └╴level_1
   └╴external_level_2_with_nested
     └╴level_3

// Sub-commands can get a reference to the parent command by adding a property of the parent command type.

[CliCommand(Description = "A root cli command with children that can access parent commands")]
public class ParentCommandAccessorCliCommand
{
    [CliOption(
        Description = "This is a global option (Recursive option on the root command), it can appear anywhere on the command line",
        Recursive = true)]
    public string GlobalOption1 { get; set; } = "DefaultForGlobalOption1";

    [CliArgument(Description = "Description for RootArgument1")]
    public string RootArgument1 { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }

    [CliCommand(Description = "A nested level 1 sub-command which accesses the root command")]
    public class Level1SubCliCommand
    {
        [CliOption(
            Description = "This is global for all sub commands (it can appear anywhere after the level-1 verb)",
            Recursive = true)]
        public string Level1RecursiveOption1 { get; set; } = "DefaultForLevel1RecusiveOption1";

        [CliArgument(Description = "Description for Argument1")]
        public string Argument1 { get; set; }

        // The parent command gets automatically injected
        public ParentCommandAccessorCliCommand RootCommand { get; set; }

        public void Run(CliContext context)
        {
            context.ShowValues();
        }

        [CliCommand(Description = "A nested level 2 sub-command which accesses its parent commands")]
        public class Level2SubCliCommand
        {
            [CliOption(Description = "Description for Option1")]
            public string Option1 { get; set; } = "DefaultForOption1";

            [CliArgument(Description = "Description for Argument1")]
            public string Argument1 { get; set; }

            // All ancestor commands gets injected
            public ParentCommandAccessorCliCommand RootCommand { get; set; }
            public Level1SubCliCommand ParentCommand { get; set; }

            public void Run(CliContext context)
            {
                context.ShowValues();

                Console.WriteLine();
                Console.WriteLine(@$"Level1RecursiveOption1 = {ParentCommand.Level1RecursiveOption1}");
                Console.WriteLine(@$"parent Argument1 = {ParentCommand.Argument1}");
                Console.WriteLine(@$"GlobalOption1 = {RootCommand.GlobalOption1}");
                Console.WriteLine(@$"RootArgument1 = {RootCommand.RootArgument1}");
            }
        }
    }
}

[CliCommand]
public class InheritanceCliCommand : CredentialCommandBase, IDepartmentCommand
{
    public string Department { get; set; } = "Accounting";
}

public abstract class CredentialCommandBase
{
    [CliOption(Description = "Username of the identity performing the command")]
    public string Username { get; set; } = "admin";

    [CliOption(Description = "Password of the identity performing the command")]
    public string Password { get; set; }

    public void Run()
    {
        Console.WriteLine($@"I am {Username}");
    }
}

public interface IDepartmentCommand
{
    [CliOption(Description = "Department of the identity performing the command (interface)")]
    string Department { get; set; }
}

dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^

msbuild /version
        ^------^

dotnet tool update dotnet-suggest --verbosity quiet --global
                                              ^---^

dotnet build myapp.csproj
             ^----------^

dotnet tool update dotnet-suggest --global
                                  ^------^

dotnet tool update dotnet-suggest --global true
                                  ^-----------^

dotnet build --verbosity silent

Cannot parse argument 'silent' for option '-v' as expected type 'Microsoft.DotNet.Cli.VerbosityOptions'. Did you mean one of the following?
Detailed
Diagnostic
Minimal
Normal
Quiet

TestApp.exe NewValueForArgument1

dotnet run -- NewValueForArgument1

Handler for 'TestApp.Commands.RootCliCommand' is run:
Value for Option1 property is 'DefaultForOption1'
Value for Argument1 property is 'NewValueForArgument1'

[CliCommand]
public class WriteFileCliCommand
{
    [CliArgument]
    public FileInfo OutputFile { get; set; }

    [CliOption]
    public List<string> Lines { get; set; }
}

Booleans (flags) - If true or false is passed for an option having a bool argument, it is parsed and bound as expected. But an option whose argument type is bool doesn't require an argument to be specified. The presence of the option token on the command line, with no argument following it, results in a value of true.
Enums - The values are bound by name, and the binding is case insensitive
Common CLR types:
- FileSystemInfo, FileInfo, DirectoryInfo
- int, long, short, uint, ulong, ushort
- double, float, decimal
- byte, sbyte
- DateTime, DateTimeOffset, TimeSpan, DateOnly, TimeOnly
- Guid
- Uri, IPAddress, IPEndPoint
Any type with a public constructor or a static Parse method with a string parameter (other parameters, if any, should be optional) - These types can be bound/parsed automatically even if they are wrapped with Enumerable or Nullable type.
[CliCommand] public class ArgumentConverterCliCommand { [CliOption] public ClassWithConstructor Opt { get; set; } [CliOption(AllowMultipleArgumentsPerToken = true)] public ClassWithConstructor[] OptArray { get; set; } [CliOption] public CustomStruct? OptNullable { get; set; } [CliOption] public IEnumerable<ClassWithConstructor> OptEnumerable { get; set; } [CliOption] public List<ClassWithConstructor> OptList { get; set; } [CliOption] public CustomList<ClassWithConstructor> OptCustomList { get; set; } [CliArgument] public IEnumerable<ClassWithParser> Arg { get; set; } } public class ClassWithConstructor { private readonly string value; public ClassWithConstructor(string value) { this.value = value; } public override string ToString() { return value; } } public class ClassWithParser { private string value; public override string ToString() { return value; } public static ClassWithParser Parse(string value) { var instance = new ClassWithParser(); instance.value = value; return instance; } } public struct CustomStruct { private readonly string value; public CustomStruct(string value) { this.value = value; } public override string ToString() { return value; } }
Arrays, lists, collections:
- Any type that implements IEnumerable<T> and has a public constructor with a IEnumerable<T> or IList<T> parameter (other parameters, if any, should be optional). CLR collection types already satisfy this condition.
- If type is generic IEnumerable<T>, IList<T>, ICollection<T> interfaces itself, array T[] will be used to create an instance.
- If type is non-generic IEnumerable, IList, ICollection interfaces itself, array string[] will be used to create an instance.
[CliCommand] public class EnumerableCliCommand { [CliOption] public IEnumerable<int> OptEnumerable { get; set; } [CliOption] public List<string> OptList { get; set; } [CliOption(AllowMultipleArgumentsPerToken = true)] public FileAccess[] OptEnumArray { get; set; } [CliOption] public Collection<string> OptCollection { get; set; } [CliOption] public HashSet<string> OptHashSet { get; set; } [CliOption] public Queue<FileInfo> OptQueue { get; set; } [CliOption] public CustomList<string> OptCustomList { get; set; } [CliArgument] public IList ArgIList { get; set; } } public class CustomList<T> : List<T> { public CustomList(IEnumerable<T> items) : base(items) { } }

[CliCommand]
public class ValidationCliCommand
{
    [CliOption(Required = false, ValidationRules = CliValidationRules.ExistingFile)]
    public FileInfo OptFile1 { get; set; }

    [CliOption(Required = false, ValidationRules = CliValidationRules.NonExistingFile | CliValidationRules.LegalPath)]
    public string OptFile2 { get; set; }

    [CliOption(Required = false, ValidationPattern = @"(?i)^[a-z]+$")]
    public string OptPattern1 { get; set; }

    [CliOption(Required = false, ValidationPattern = @"(?i)^[a-z]+$", ValidationMessage = "Custom error message")]
    public string OptPattern2 { get; set; }

    [CliOption(Required = false, ValidationRules = CliValidationRules.LegalUrl)]
    public string OptUrl { get; set; }

    [CliOption(Required = false, ValidationRules = CliValidationRules.LegalUri)]
    public string OptUri { get; set; }

    [CliArgument(Required = false, ValidationRules = CliValidationRules.LegalFileName)]
    public string OptFileName { get; set; }

    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}

using System;
using System.Collections.Generic;
using System.CommandLine;
using System.CommandLine.Completions;
using System.Linq;
using DotMake.CommandLine;

[CliCommand(Description = "A root cli command with completions for options and arguments")]
public class AddCompletionsCliCommand : ICliAddCompletions
{
    [CliOption(Description = "Description for DateOption")]
    public DateTime DateOption { get; set; }

    [CliArgument(Description = "Description for FruitArgument")]
    public string FruitArgument { get; set; } = "DefaultForFruitArgument";

    public void Run(CliContext context)
    {
        if (context.IsEmptyCommand())
            context.ShowHelp();
        else
            context.ShowValues();
    }

    public void AddCompletions(string propertyName, List<Func<CompletionContext, IEnumerable<CompletionItem>>> completionSources)
    {
        switch (propertyName)
        {
            case nameof(DateOption):
                completionSources.Add(completionContext =>
                {
                    var today = System.DateTime.Today;
                    var dates = new List<CompletionItem>();
                    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;
                });
                break;

            case nameof(FruitArgument):
                completionSources.Add("apple", "orange", "banana");
                break;
        }
    }
}

DotMake Command-Line TestApp v2.3.0
Copyright © 2023-2025 DotMake

A root cli command with completions for options and arguments

Usage:
  TestApp [<fruit>] [options]

Arguments:
  <apple|banana|orange>  Description for FruitArgument [default: DefaultForFruitArgument]

Options:
  -d, --date                                                  Description for DateOption [default: 1.01.0001 00:00:00]
  <22.04.2025|23.04.2025|24.04.2025|25.04.2025|26.04.2025|27
  .04.2025|28.04.2025>
  -?, -h, --help                                              Show help and usage information
  -v, --version                                               Show version information

dotnet add package Microsoft.Extensions.DependencyInjection

PM> Install-Package Microsoft.Extensions.DependencyInjection

using DotMake.CommandLine;
using Microsoft.Extensions.DependencyInjection;

Cli.Ext.ConfigureServices(services =>
{
    services.AddTransient<TransientClass>();
    services.AddScoped<ScopedClass>();
    services.AddSingleton<SingletonClass>();
});

Cli.Run<RootCliCommand>();

[CliCommand(Description = "A root cli command with dependency injection")]
public class RootCliCommand
{
    private readonly TransientClass transientDisposable;
    private readonly ScopedClass scopedDisposable;
    private readonly SingletonClass singletonDisposable;

    public RootCliCommand(
        TransientClass transientDisposable,
        ScopedClass scopedDisposable,
        SingletonClass singletonDisposable
    )
    {
        this.transientDisposable = transientDisposable;
        this.scopedDisposable = scopedDisposable;
        this.singletonDisposable = singletonDisposable;
    }

    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();

        Console.WriteLine($"Instance for {transientDisposable.Name} is available");
        Console.WriteLine($"Instance for {scopedDisposable.Name} is available");
        Console.WriteLine($"Instance for {singletonDisposable.Name} is available");
        Console.WriteLine();
    }
}

public sealed class TransientClass : IDisposable
{
    public string Name => nameof(TransientClass);

    public void Dispose() => Console.WriteLine($"{nameof(TransientClass)}.Dispose()");
}

public sealed class ScopedClass : IDisposable
{
    public string Name => nameof(ScopedClass);

    public void Dispose() => Console.WriteLine($"{nameof(ScopedClass)}.Dispose()");
}

public sealed class SingletonClass : IDisposable
{
    public string Name => nameof(SingletonClass);

    public void Dispose() => Console.WriteLine($"{nameof(SingletonClass)}.Dispose()");
}

dotnet add package Microsoft.Extensions.DependencyInjection.Abstractions

PM> Install-Package Microsoft.Extensions.DependencyInjection.Abstractions

using DotMake.CommandLine;
using Autofac.Core;
using Autofac.Core.Registration;

var cb = new ContainerBuilder();
cb.RegisterType<object>();
var container = cb.Build();

Cli.Ext.SetServiceProvider(container);

Cli.Run<RootCliCommand>();

dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/

build
--no-restore 
--output
./build-output/

--no-restore

dotnet [diagram] build --no-restore --output ./build-output/
       ^-----^

[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]

myapp [diagram] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

dotnet [suggest] buil

build
build-server
msbuild

dotmake/DotMake.CommandLinev2.3.0

Get Started

Readme

DotMake Command-Line

Getting started

Prerequisites

Usage

Class-based model

Summary

Delegate-based model

Summary

Help output

Themes

Localization

Triggering help

Commands

Root commands

Subcommands

Command Hierarchy

Accessing parent commands

Command Inheritance

Options

Arguments

Model binding

Supported types

Validation

Completions

Dependency Injection

Response files

Directives

The `[diagram]` directive

The `[suggest]` directive

The environment variables directive

Additional documentation

dotmake/DotMake.CommandLinev2.3.0

Get Started

Readme

DotMake Command-Line

Getting started

Prerequisites

Usage

Class-based model

Summary

Delegate-based model

Summary

Help output

Themes

Localization

Triggering help

Commands

Root commands

Subcommands

Command Hierarchy

Accessing parent commands

Command Inheritance

Options

Arguments

Model binding

Supported types

Validation

Completions

Dependency Injection

Response files

Directives

The [diagram] directive

The [suggest] directive

The environment variables directive

Additional documentation

The `[diagram]` directive

The `[suggest]` directive