Note: the API surface has changed since v1.9.x and earlier. If you are looking for documentation on v1.9.x, please see stable-1.9.71.2
The Command Line Parser Library offers CLR applications a clean and concise API for manipulating command line arguments and related tasks, such as defining switches, options and verb commands. It allows you to display a help screen with a high degree of customization and a simple way to report syntax errors to the end user.
C:\Project> NuGet Install CommandLineParser
Nightly version of the CommandLineParser can be downloaded from github Releases.
The Last new features and fixes, read changelog
NOTE: Mentioned F# Support is provided via CommandLineParser.FSharp package with FSharp dependencies.
This library provides hassle free command line parsing with a constantly updated API since 2005.
- Compatible with .NET Framework 4.0+, Mono 2.1+ Profile, .NET Standard and .NET Core
- Doesn't depend on other packages (No dependencies beyond standard base libraries)
- One line parsing using default singleton:
CommandLine.Parser.Default.ParseArguments(...)and three overload methods. - Automatic or one line help screen generator:
HelpText.AutoBuild(...). - Supports
--help,--version,versionandhelp [verb]by default with customization. - Map to sequences (via
IEnumerable<T>and similar) and scalar types, including Enums andNullable<T>. - You can also map to every type with a constructor that accepts a string (like
System.Uri) for reference and value types. - Verbs can be array of types collected from Plugins or IoC container.
- Define verb commands similar to
git commit -a. - Support default verb.
- Support Mutable and Immutable types.
- Support HelpText localization.
- Support ordering of options in HelpText.
- Support Mutually Exclusive Options and Option groups.
- Support named and value options.
- Support Asynchronous programming with async and await.
- Unparsing support:
CommandLine.Parser.Default.FormatCommandLine<T>(T options). - CommandLineParser.FSharp package is F#-friendly with support for
option<'a>, see demo. NOTE: This is a separate NuGet package. - Include wiki documentation with lot of examples ready to run online.
- Support Source Link and symbolic nuget package snupkg.
- Tested in Windows, Linux Ubuntu 18.04 and Mac OS.
- Most of features applies with a CoC philosophy.
- C# demo: source here.
You can utilize the parser library in several ways:
- Install via NuGet/Paket: https://www.nuget.org/packages/CommandLineParser/
- Integrate directly into your project by copying the .cs files into your project.
- ILMerge during your build process.
- Create a class to define valid options, and to receive the parsed options.
- Call ParseArguments with the args string array.
C# Quick Start:
using System;
using CommandLine;
namespace QuickStart
{
class Program
{
public class Options
{
[Option('v', "verbose", Required = false, HelpText = "Set output to verbose messages.")]
public bool Verbose { get; set; }
}
static void Main(string[] args)
{
Parser.Default.ParseArguments<Options>(args)
.WithParsed<Options>(o =>
{
if (o.Verbose)
{
Console.WriteLine($"Verbose output enabled. Current Arguments: -v {o.Verbose}");
Console.WriteLine("Quick Start Example! App is in Verbose mode!");
}
else
{
Console.WriteLine($"Current Arguments: -v {o.Verbose}");
Console.WriteLine("Quick Start Example!");
}
});
}
}
}Click to expand!
class Options
{
[Option('r', "read", Required = true, HelpText = "Input files to be processed.")]
public IEnumerable<string> InputFiles { get; set; }
// Omitting long name, defaults to name of property, ie "--verbose"
[Option(
Default = false,
HelpText = "Prints all messages to standard output.")]
public bool Verbose { get; set; }
[Option("stdin",
Default = false,
HelpText = "Read from stdin")]
public bool stdin { get; set; }
[Value(0, MetaName = "offset", HelpText = "File offset.")]
public long? Offset { get; set; }
}
static void Main(string[] args)
{
CommandLine.Parser.Default.ParseArguments<Options>(args)
.WithParsed(RunOptions)
.WithNotParsed(HandleParseError);
}
static void RunOptions(Options opts)
{
//handle options
}
static void HandleParseError(IEnumerable<Error> errs)
{
//handle errors
}Demo to show IEnumerable options and other usage: Online Demo
Click to expand!
type options = {
[<Option('r', "read", Required = true, HelpText = "Input files.")>] files : seq<string>;
[<Option(HelpText = "Prints all messages to standard output.")>] verbose : bool;
[<Option(Default = "русский", HelpText = "Content language.")>] language : string;
[<Value(0, MetaName="offset", HelpText = "File offset.")>] offset : int64 option;
}
let main argv =
let result = CommandLine.Parser.Default.ParseArguments<options>(argv)
match result with
| :? Parsed<options> as parsed -> run parsed.Value
| :? NotParsed<options> as notParsed -> fail notParsed.ErrorsClick to expand!
Class Options
<CommandLine.Option('r', "read", Required := true,
HelpText:="Input files to be processed.")>
Public Property InputFiles As IEnumerable(Of String)
' Omitting long name, defaults to name of property, ie "--verbose"
<CommandLine.Option(
HelpText:="Prints all messages to standard output.")>
Public Property Verbose As Boolean
<CommandLine.Option(Default:="中文",
HelpText:="Content language.")>
Public Property Language As String
<CommandLine.Value(0, MetaName:="offset",
HelpText:="File offset.")>
Public Property Offset As Long?
End Class
Sub Main(ByVal args As String())
CommandLine.Parser.Default.ParseArguments(Of Options)(args) _
.WithParsed(Function(opts As Options) RunOptionsAndReturnExitCode(opts)) _
.WithNotParsed(Function(errs As IEnumerable(Of [Error])) 1)
End Sub- Create separate option classes for each verb. An options base class is supported.
- Call ParseArguments with all the verb attribute decorated options classes.
- Use MapResult to direct program flow to the verb that was parsed.
Click to expand!
[Verb("add", HelpText = "Add file contents to the index.")]
class AddOptions {
//normal options here
}
[Verb("commit", HelpText = "Record changes to the repository.")]
class CommitOptions {
//commit options here
}
[Verb("clone", HelpText = "Clone a repository into a new directory.")]
class CloneOptions {
//clone options here
}
int Main(string[] args) {
return CommandLine.Parser.Default.ParseArguments<AddOptions, CommitOptions, CloneOptions>(args)
.MapResult(
(AddOptions opts) => RunAddAndReturnExitCode(opts),
(CommitOptions opts) => RunCommitAndReturnExitCode(opts),
(CloneOptions opts) => RunCloneAndReturnExitCode(opts),
errs => 1);
}Click to expand!
<CommandLine.Verb("add", HelpText:="Add file contents to the index.")>
Public Class AddOptions
'Normal options here
End Class
<CommandLine.Verb("commit", HelpText:="Record changes to the repository.")>
Public Class CommitOptions
'Normal options here
End Class
<CommandLine.Verb("clone", HelpText:="Clone a repository into a new directory.")>
Public Class CloneOptions
'Normal options here
End Class
Function Main(ByVal args As String()) As Integer
Return CommandLine.Parser.Default.ParseArguments(Of AddOptions, CommitOptions, CloneOptions)(args) _
.MapResult(
(Function(opts As AddOptions) RunAddAndReturnExitCode(opts)),
(Function(opts As CommitOptions) RunCommitAndReturnExitCode(opts)),
(Function(opts As CloneOptions) RunCloneAndReturnExitCode(opts)),
(Function(errs As IEnumerable(Of [Error])) 1)
)
End FunctionClick to expand!
open CommandLine
[<Verb("add", HelpText = "Add file contents to the index.")>]
type AddOptions = {
// normal options here
}
[<Verb("commit", HelpText = "Record changes to the repository.")>]
type CommitOptions = {
// normal options here
}
[<Verb("clone", HelpText = "Clone a repository into a new directory.")>]
type CloneOptions = {
// normal options here
}
[<EntryPoint>]
let main args =
let result = Parser.Default.ParseArguments<AddOptions, CommitOptions, CloneOptions> args
match result with
| :? CommandLine.Parsed<obj> as command ->
match command.Value with
| :? AddOptions as opts -> RunAddAndReturnExitCode opts
| :? CommitOptions as opts -> RunCommitAndReturnExitCode opts
| :? CloneOptions as opts -> RunCloneAndReturnExitCode opts
| :? CommandLine.NotParsed<obj> -> 1See the changelog
First off, Thank you! All contributions are welcome.
Please consider sticking with the GNU getopt standard for command line parsing.
Additionally, for easiest diff compares, please follow the project's tabs settings. Utilizing the EditorConfig extension for Visual Studio/your favorite IDE is recommended.
And most importantly, please target the develop branch in your pull requests!
- Alexander Fast (@mizipzor)
- Dan Nemec (@nemec)
- Eric Newton (@ericnewton76)
- Kevin Moore (@gimmemoore)
- Moh-Hassan (@moh-hassan)
- Steven Evans
- Thomas Démoulins (@Thilas)
- Giacomo Stelluti Scala
- Dan Nemec
- Eric Newton
- ericnewton76+commandlineparser AT gmail DOT com
- GitHub: ericnewton76
- Blog:
- Twitter: enorl76
- Moh-Hassan
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent