Skip to main content

UtilityCli is built for simple utility console application scenarios. As a wrapper around System.CommandLine, UtilityCli provides simple APIs for extracting strongly-typed options and arguments from the command line args. UtilityCli does not require the CLI to be defined/modeled up-front. Instead, the model is progressively defined while extracting the option and argument values.

Total Downloads
1.3K
1,300
Published
Jan 25, 2026
9mo ago

Get Started

dotnet add package UtilityCli --version 2.0.0-preview.2
ProductVersions
.NET
net8.0

README

UtilityCli

Quickly build utility applications that parse the command-line

UtilityCli is built for simple utility console application scenarios. As a wrapper around System.CommandLine, UtilityCli provides simple APIs for extracting strongly-typed options and arguments from the command line args. UtilityCli does not require the CLI to be defined/modeled up-front. Instead, the model is progressively defined while extracting the option and argument values.

// --org dotnet --repo runtime area-System.Security untriaged --dry-run --issue 40074 --pr 40075 --verbose --clear
// -o dotnet -r runtime area-System.Security untriaged --dry-run -i 40074 -p 40075 -vc

var cli = UtilityCli.CliArgs.Parse(args);

string org = cli.GetRequiredString("org", aliases: ["owner"]);
string repo = cli.GetRequiredString("repo");
bool clearExistingLabels = cli.HasFlag("clear");

int[] issues = cli.GetInt32s("issue") ?? [];
int[] prs = cli.GetInt32s("pr") ?? [];

bool verboseOutput = cli.HasFlag("verbose");
bool dryRun = cli.HasFlag("dry-run", shortNames: []); // Do not infer a 'd' short name
string[] labels = cli.GetRequiredStrings();

Approachable, easy, opinionated

Working in happy-path scenarios, UtilityCli allows you to simply call Parse(args) in your console application and then extract elements into strongly-typed values. UtilityCli applies some opinionated formatting to your command-line to achieve an easy-to-use API.

  • Option names are always prefixed with a double dash; e.g. --name
  • Option short names must always be single characters, and are recognized with a single dash; e.g. -n
  • POSIX bundling is always enabled; e.g. -name would match options with short names n, a, m, e (regardless of order)
  • Option names (and short names) are case-sensitive; aliases can be specified with different casing if desired

UtilityCli is not intended for CLI applications that are distributed to other users; it's intended for utility applications you create for yourself or your team. Because UtilityCli does not require the CLI to be modeled up-front, there are functional limitations. Most notably:

  • Unmatched options and arguments do not cause parsing to fail
  • Options must always be extracted before arguments (to avoid ambiguity)

With a fully-modeled System.CommandLine CLI, there is no ambiguity in terms of how options and arguments are extracted. Using UtilityCli and skipping the step of modeling your CLI can introduce such ambiguities. For utility apps you author for yourself or your team, and even for single-use applications though, this trade-off can save time and frustration.

Error handling

Pass an error callback to Parse to display usage information when parsing fails. The callback receives a CliError with full context about what went wrong.

var cli = UtilityCli.CliArgs.Parse(args, error =>
{
    Console.WriteLine($"Error: {error.Message}");
    Console.WriteLine();
    Console.WriteLine("Usage: myapp --org <org> --repo <repo> [labels...]");
    Console.WriteLine("  --org, -o    Organization or owner name (required)");
    Console.WriteLine("  --repo, -r   Repository name (required)");
});

string org = cli.GetRequiredString("org");
string repo = cli.GetRequiredString("repo");

The CliError class provides:

  • Kind - The type of error (MissingRequiredArgument, MissingRequiredOption, InvalidArgumentValue, InvalidOptionValue, OptionsAfterArguments, OptionTypeMismatch)
  • Message - A descriptive error message
  • Exception - The exception that would be thrown if no callback were registered
  • OptionName - The name of the option that caused the error (if applicable)
  • ExpectedType - The expected type for the value
  • RawValue - The raw string value that could not be parsed (if applicable)

The callback is invoked instead of throwing the exception, allowing you to display helpful information to the user and exit gracefully.

Downloads by Version

Depended On By

Find packages that declare this package as a dependency. NuGet does not provide a reverse-dependency endpoint, so candidates are checked on demand.

Adoption Assessment

Assess this package against its supported frameworks, license, maintenance signals and dependency graph before making it a project standard.

This version is marked prerelease. Validate its API and upgrade path before production use.Compatibility metadata lists 1 target framework; confirm the exact target used by your application.

Related Guides & Workflows

Learn how to evaluate, integrate, or audit this package in your .NET project.