NiceCli 1.2.0

dotnet add package NiceCli --version 1.2.0
NuGet\Install-Package NiceCli -Version 1.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NiceCli" Version="1.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add NiceCli --version 1.2.0
#r "nuget: NiceCli, 1.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install NiceCli as a Cake Addin
#addin nuget:?package=NiceCli&version=1.2.0

// Install NiceCli as a Cake Tool
#tool nuget:?package=NiceCli&version=1.2.0

NiceCli

CI

NiceCli is a command-based CLI framework for .NET applications.

Its main design goal is to keep the definition of the global options, commands and their options in one place using fluent syntax, and the commands themselves as separate classes.

By using convention over configuration the CLI definition can be kept clean and minimal. For example it is not necessary to define parameter names, the property names are used like for example CommandTimeout is mapped to "--command-timeout".

Quick start

Add the Nuget package NiceCli by using your IDE or through the terminal:

dotnet add package NiceCli

Define the CLI and add classes for commands:

  • Start with CliApp.WithArgs(args)
  • Add an optional global options class to any hold global options and flags with GlobalOptions<Type>, where Type is the global options class
  • Add one or more command definitions with Command<Type>, DefaultCommand<Type> or HiddenCommand<Type> where Type is the command class
  • Add one or more command classes that inherit the interface ICliCommand together with optional properties for command options and flags
  • End with RunAsync for a simple app that do not use IoC, or add the Nuget package NiceCli.Dotnet to use the .NET IoC framework

Examples

Global options, commands, options and flags

CLI app with some global options, one default command (that runs if no command is used) and a second non-default command with a flag.

Logging is setup early in the method InitializeLogging that receives GlobalOptions with the Verbose property as a parameter. It is called by the Configure method which is an optional extension for global options.

Not shown in this example is the optional char parameter in Option and Flag definitions to add shortcut parameters like for example "-h" for help.

Program.cs:

using NiceCli;

return await CliApp.WithArgs(args)
  .GlobalOptions<GlobalOptions>(c => c
    .Option(o => o.Db, "Database connection string")
    .Option(o => o.CommandTimeout, "Database command timeout", "mm:ss", CliValueConversion.MinutesAndSecondsToTimeSpan)
    .Flag(f => f.Verbose, "Verbose logging")
    .Configure(o => InitializeLogging(o)))
  .DefaultCommand<RunCommand>("Run service")
  .Command<MigrateCommand>("Migrate database to current version", c => c
    .Flag(f => f.DryRun, "Show migration SQL commands, but do not run them"))
  .RunAsync();

Help output for the above code when running: example -h

<img alt="Commands options and flags example" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/commands-options-flags.png" />

And help output for the command migrate: example migrate -h

<img alt="Migrate command help" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/commands-options-flags-migrate.png" />

Descriptive definitions

CLI app with overridden name and version, description, examples and learn more info.

Program.cs:

using NiceCli;

return await CliApp.WithArgs(args)
  .Named("custom-name")
  .Description("This app only serves as an example")
  .Version("1.0-custom-version")
  .Example("custom-name run")
  .Example("custom-name migrate")
  .Example("custom-name export <start-date> <end-date>")
  .LearnMore("Read about defining the CLI at https://github.com/nhedlund/nicecli")
  .RunAsync();

Help output for the above code when running: example -h

<img alt="Descriptive parameters example" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/cli-description.png" />

Positional parameters

CLI app with one command that has two positional parameters and a flag.

Program.cs:

using NiceCli;

return await CliApp.WithArgs(args)
  .Command<GenerateCommand>("Generate a list of dates from start date to end date", c => c
    .PositionalParameter(p => p.Start, "Start date: yyyy-mm-dd")
    .PositionalParameter(p => p.End, "End date: yyyy-mm-dd")
    .Flag(f => f.Weekday, "Include weekday name"))
  .RunAsync();

Help output for the above code when running: example -h

<img alt="Positional parameters example" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/command-positional-parameters.png" />

And help output for the command generate: example generate -h

<img alt="Generate command help" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/command-positional-parameters-generate.png" />

Dotnet host framework integration

CLI app has one default command that runs the host. The run command is not a normal command, it is a built-in command that starts the host.

The run command definition takes two arguments: description and whether the command should run by default when no command parameter is used, or if a command parameter is necessary.

Program.cs:

using NiceCli;
using NiceCli.Dotnet;

var cliApp = CliApp.WithArgs(args)
  .CommandRun("Start example service", CliDefault.Yes);

using var host = Host.CreateDefaultBuilder()
  .ConfigureCli(cliApp)
  .Build();

return await host.RunCliCommandAsync(cliApp);

Help output for the above code when running: example -h

<img alt="Dotnet run host help" width="827px" src="https://raw.githubusercontent.com/nhedlund/nicecli/main/docs/images/dotnet-run-host.png" />

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on NiceCli:

Package Downloads
NiceCli.Dotnet

NiceCli extensions to .NET host and host builder.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.2.0 159 7/26/2023
1.1.0 289 2/14/2023
1.0.0 404 1/30/2023