commandline-cheatsheet
/commandline-cheatsheet
Use when building command-line applications in .NET with System.CommandLine. Covers command/option/argument definitions, middleware, tab completion, parsing, and hosting integration for CLI tools. USE FOR: building CLI applications with typed argument parsing, creating dotnet tools with subcommands, System.CommandLine setup and configuration, adding tab completion to CLI apps, parsing and validating command-line arguments DO NOT USE FOR: executing external CLI processes (use cliwrap), rendering rich terminal UI with tables and progress bars (use spectre-console), building web APIs (use ASP.NET
- Author
- Tyler-R-Kendrick ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 09.06.2026
Assessment and security
- Files in this package
- 21
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Use when building command-line applications in .NET with System.CommandLine. Covers command/option/argument definitions, middleware, tab completion, parsing, and hosting integration for CLI tools. USE FOR: building CLI applications with typed argument parsing, creating dotnet tools with subcommands, System.CommandLine setup and configuration, adding tab completion to CLI apps, parsing and validating command-line arguments DO NOT USE FOR: executing external CLI processes (use cliwrap), rendering rich terminal UI with tables and progress bars (use spectre-console), building web APIs (use ASP.NET
Original author description
Use when building command-line applications in .NET with System.CommandLine. Covers command/option/argument definitions, middleware, tab completion, parsing, and hosting integration for CLI tools. USE FOR: building CLI applications with typed argument parsing, creating dotnet tools with subcommands, System.CommandLine setup and configuration, adding tab completion to CLI apps, parsing and validating command-line arguments DO NOT USE FOR: executing external CLI processes (use cliwrap), rendering rich terminal UI with tables and progress bars (use spectre-console), building web APIs (use ASP.NET
How it works
- Overview
- NuGet Packages
- Minimal CLI Application
- Commands with Subcommands
- Options, Arguments, and Aliases
- Argument Validation
- Global Options
- Hosting Integration
- Middleware
- File and Directory Arguments
SKILL.md preview
---
name: commandline-cheatsheet
description: |
Use when building command-line applications in .NET with System.CommandLine. Covers command/option/argument definitions, middleware, tab completion, parsing, and hosting integration for CLI tools.
USE FOR: building CLI applications with typed argument parsing, creating dotnet tools with subcommands, System.CommandLine setup and configuration, adding tab completion to CLI apps, parsing and validating command-line arguments
DO NOT USE FOR: executing external CLI processes (use cliwrap), rendering rich terminal UI with tables and progress bars (use spectre-console), building web APIs (use ASP.NET Core), simple Console.ReadLine input
license: MIT
metadata:
displayName: "Command-Line Cheatsheet"
author: "Tyler-R-Kendrick"
version: "1.0.0"
compatibility: claude, copilot, cursor
references:
- title: "System.CommandLine Documentation"
url: "https://learn.microsoft.com/dotnet/standard/commandline"
- title: "System.CommandLine GitHub Repository"
url: "https://github.com/dotnet/command-line-api"
- title: "System.CommandLine NuGet Package"
url: "https://www.nuget.org/packages/System.CommandLine"
---
# Command-Line Cheatsheet
## Overview
System.CommandLine is the official .NET library for building command-line applications with typed argument parsing, automatic help generation, tab completion, and middleware support. It provides a structured way to define commands, options, and arguments that map directly to handler methods, with built-in validation and error reporting.
## NuGet Packages
```bash
dotnet add package System.CommandLine
dotnet add package System.CommandLine.Hosting # Generic Host integration
```
## Minimal CLI Application
```csharp
using System.CommandLine;
var nameOption = new Option<string>(
name: "--name",
description: "Your name")
{ IsRequired = true };
var greetingOption = new Option<string>(
name: "--greeting",
description: "The greeting to use",
getDefaultValue: () => "Hello");
var rootCommand = new RootCommand("A simple greeting CLI tool");
rootCommand.AddOption(nameOption);
rootCommand.AddOption(greetingOption);
rootCommand.SetHandler((string name, string greeting) =>
{
Console.WriteLine($"{greeting}, {name}!");
}, nameOption, greetingOption);
return await rootCommand.InvokeAsync(args);
// Usage: myapp --name Alice --greeting "Good morning"
```
## Commands with Subcommands
```csharp
using System.CommandLine;
var rootCommand = new RootCommand("Project management CLI");
// 'new' command
var newCommand = new Command("new", "Create a new project");
var templateArg = new Argument<string>("template", "Project template name");
var outputOption = new Option<DirectoryInfo>(
"--output", "Output directory") { IsRequired = false };
newCommand.AddArgument(templateArg);
newCommand.AddOption(outputOption);
newCommand.SetHandler((string template, DirectoryInfo? output) =>
{
var dir = output?.FullName ?? Directory.GetCurrentDirectory();
Console.WriteLine($"Creating '{template}' project in {dir}");
}, templateArg, outputOption);
// 'build' command
var buildCommand = new Command("build", "Build the project");
var configOption = new Option<string>(
"--configuration", () => "Debug", "Build configuration");
configOption.AddAlias("-c");
var verbosityOption = new Option<Verbosity>(
"--verbosity", () => Verbosity.Normal, "Output verbosity");
verbosityOption.AddAlias("-v");
buildCommand.AddOption(configOption);
buildCommand.AddOption(verbosityOption);
buildCommand.SetHandler((string config, Verbosity verbosity) =>
{
Console.WriteLine($"Building with configuration={config}, verbosity={verbosity}");
}, configOption, verbosityOption);
// 'test' command with nested subcommands
var testCommand = new Command("test", "Run tests");
var unitCommand = new Command("unit", "Run unit tests");
var integrationCommand = new Command("integration", "Run integration tests");
var filterOption = new Option<string?>("--filter", "Test filter expression");
unitCommand.AddOption(filterOption);
unitCommand.SetHandler((string? filter) =>
{
Console.WriteLine($"Running unit tests{(filter != null ? $" with filter: {filter}" : "")}");
}, filterOption);
integrationCommand.SetHandler(() =>
{
Console.WriteLine("Running integration tests");
});
testCommand.AddCommand(unitCommand);
testCommand.AddCommand(integrationCommand);
rootCommand.AddCommand(newCommand);
rootCommand.AddCommand(buildCommand);
rootCommand.AddCommand(testCommand);
return await rootCommand.InvokeAsync(args);
enum Verbosity { Quiet, Normal, Detailed, Diagnostic }
// Usage:
// myapp new webapp --output ./MyApp
// myapp build -c Release -v Detailed
// myapp test unit --filter "Category=Smoke"
// myapp test integration
```
## Options, Arguments, and Aliases
| Concept | Description | Example |
|---------|-------------|---------|
| `Option<T>` | Named parameter with `--` prefix | `--output`, `-o` |
| `Argument<T>` | Positional parameter (no prefix) | `myapp <file>` |
| `AddAlias` | Short alias for an option | `-c` for `--configuration` |
| `IsRequired` | Makes an option mandatory | `{ IsRequired = true }` |
| `getDefaultValue` | Factory for default values | `() => "Debug"` |
| `FromAmong` | Restricts to allowed values | `FromAmong("Debug", "Release")` |
## Argument Validation
```csharp
using System.CommandLine;
var portOption = new Option<int>("--port", "Server port");
portOption.AddValidator(result =>
{
var port = result.GetValueForOption(portOption);
if (port < 1024 || port > 65535)
{
result.ErrorMessage = "Port must be between 1024 and 65535";
}
});
var fileArgument = new Argument<FileInfo>("file", "Input file");
fileArgument.AddValidator(result =>
{
var file = result.GetValueForArgument(fileArgument);
if (file is not null && !file.Exists)
{
result.ErrorMessage = $"File not found: {file.FullName}";
}
});
// Restrict to specific values
var envOption = new Option<string>("--environment");
envOption.FromAmong("Development", "Staging", "Production");
```
## Global Options
```csharp
var verboseOption = new Option<bool>("--verbose", "Enable verbose logging");
verboseOption.AddAlias("-V");
var rootCommand = new RootCommand("My CLI");
rootCommand.AddGlobalOption(verboseOption); // Available to all subcommands
var serveCommand = new Command("serve", "Start the server");
serveCommand.SetHandler((bool verbose) =>
{
if (verbose) Console.WriteLine("Verbose mode enabled");
Console.WriteLine("Starting server...");
}, verboseOption);
rootCommand.AddCommand(serveCommand);
// Usage: myapp serve --verbose
// Usage: myapp --verbose serve (global options work before or after subcommand)
```
## Hosting Integration
Integrate System.CommandLine with the .NET Generic Host for DI, configuration, and logging.
```csharp
using System.CommandLine;
using System.CommandLine.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
var rootCommand = new RootCommand("CLI with hosting");
var nameOption = new Option<string>("--name", "User name") { IsRequired = true };
rootCommand.AddOption(nameOption);
rootCommand.SetHandler(async (IHost host) =>
{
var greeter = host.Services.GetRequiredService<GreeterService>();
var parseResult = host.Services.GetRequiredService<ParseResult>();
var name = parseResult.GetValueForOption(nameOption)!;
await greeter.GreetAsync(name);
});
var builder = new CommandLineBuilder(rootCommand)
.UseHost(hostBuilder =>
{
hostBuilder.ConfigureServices(services =>
{
services.AddTransient<GreeterService>();
});
hostBuilder.ConfigureLogging(logging =>
{
logging.AddConsole();
logging.SetMinimumLevel(LogLevel.Information);
});
})
.UseDefaults();
return await builder.Build().InvokeAsync(args);
public class GreeterService(ILogger<GreeterService> logger)
{
public Task GreetAsync(string name)
{
logger.LogInformation("Greeting user: {Name}", name);
Console.WriteLine($"Hello, {name}!");
return Task.CompletedTask;
}
}
```
## Middleware
```csharp
var builder = new CommandLineBuilder(rootCommand)
.UseDefaults()
.AddMiddleware(async (context, next) =>
{
var sw = System.Diagnostics.Stopwatch.StartNew();
Console.WriteLine($"Executing: {context.ParseResult.CommandResult.Command.Name}");
await next(context);
sw.Stop();
Console.WriteLine($"Completed in {sw.ElapsedMilliseconds}ms");
});
var parser = builder.Build();
return await parser.InvokeAsync(args);
```
## File and Directory Arguments
```csharp
var inputFile = new Argument<FileInfo>("input", "Input file path");
var outputDir = new Option<DirectoryInfo>(
"--output-dir", () => new DirectoryInfo("."), "Output directory");
var convertCommand = new Command("convert", "Convert a file");
convertCommand.AddArgument(inputFile);
convertCommand.AddOption(outputDir);
convertCommand.SetHandler((FileInfo input, DirectoryInfo outDir) =>
{
if (!input.Exists)
{
Console.Error.WriteLine($"File not found: {input.FullName}");
return;
}
Console.WriteLine($"Converting {input.Name} to {outDir.FullName}");
}, inputFile, outputDir);
```
## Creating a dotnet Tool
```xml
<!-- .csproj file -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<PackAsTool>true</PackAsTool>
<ToolCommandName>mytool</ToolCommandName>
<PackageId>MyOrg.MyTool</PackageId>
<Version>1.0.0</Version>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="System.CommandLine" Version="2.0.0-beta4.*" />
</ItemGroup>
</Project>
```
```bash
# Pack and install locally
dotnet pack
dotnet tool install --global --add-source ./nupkg MyOrg.MyTool
# Usage
mytool build -c Release
mytool test unit --filter "Priority=1"
```
## Best Practices
- Use `RootCommand` with descriptive text as the entry point and organize functionality into `Command` subcommands rather than overloading the root with many options.
- Add both long (`--configuration`) and short (`-c`) aliases for frequently used options to reduce typing in interactive use while keeping discoverability for scripts.
- Use `Option<T>` with strongly-typed generics (`Option<int>`, `Option<FileInfo>`, `Option<Verbosity>`) instead of `Option<string>` with manual parsing to get automatic validation and help text.
- Set `IsRequired = true` on mandatory options and provide `getDefaultValue` factories on optional ones so the help text accurately reflects what is required vs. optional.
- Use `AddValidator` for custom validation rules (port ranges, file existence, format checks) to provide clear error messages before the handler runs.
- Use `FromAmong` to restrict string options to a fixed set of allowed values (e.g., environments, log levels) with automatic validation and tab completion.
- Integrate with `System.CommandLine.Hosting` for applications that need dependency injection, `IConfiguration`, or `ILogger` rather than constructing services manually in handlers.
- Add `AddGlobalOption` for cross-cutting options like `--verbose`, `--output-format`, or `--no-color` that apply to all subcommands without repeating them.
- Set `<PackAsTool>true</PackAsTool>` in the .csproj to distribute the CLI as a `dotnet tool` that users install with `dotnet tool install`.
- Use `CommandLineBuilder.UseDefaults()` to enable automatic help (`--help`), version (`--version`), parse error reporting, and suggest-typo features without manual configuration.
Files in this package (21)
- AGENTS.md 10 KB
- README.md 1 KB
- SKILL.md 11 KB
- metadata.json 1 KB
- rules/_sections.md 2 KB
- rules/_template.md 1 KB
- rules/commandline-cheatsheet-add-addglobaloption-for-cross-cutting-options-like.md 1 KB
- rules/commandline-cheatsheet-add-both-long-configuration-and-short-c-aliases.md 1 KB
- rules/commandline-cheatsheet-integrate-with-system.md 1 KB
- rules/commandline-cheatsheet-provide-clear-help-text.md 1 KB
- rules/commandline-cheatsheet-set-isrequired-true-on-mandatory-options-and-provide.md 1 KB
- rules/commandline-cheatsheet-set-packastool-true-packastool-in-the.md 1 KB
- rules/commandline-cheatsheet-support-both-short-n-and-long-name-options.md 1 KB
- rules/commandline-cheatsheet-support-standard-conventions-help-version.md 1 KB
- rules/commandline-cheatsheet-use-addvalidator-for-custom-validation-rules-port.md 1 KB
- rules/commandline-cheatsheet-use-commandlinebuilder.md 1 KB
- rules/commandline-cheatsheet-use-fromamong-to-restrict-string-options-to-a-fixed-set.md 1 KB
- rules/commandline-cheatsheet-use-option-t-with-strongly-typed-generics.md 1 KB
- rules/commandline-cheatsheet-use-rootcommand-with-descriptive-text-as-the-entry-point.md 1 KB
- rules/commandline-cheatsheet-use-verbs-for-sub-commands.md 1 KB
- rules/commandline-cheatsheet-validate-input-early.md 1 KB
Versions
The database has no other skills named commandline-cheatsheet.
Database snapshot: 13.11.2026 · package version 667c0bce3a35 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100spectre-console
Use when building rich terminal UIs in .NET with Spectre.Console. Covers tables, trees, progress bars, prompts, live rendering, markup formatting, and the Spectre.Console.Cli command framework. USE FOR: rendering tables and grids in the terminal, progress bars and spinners,… - 98cliwrap
Use when executing external command-line processes from .NET with CliWrap. Covers fluent command building, output capturing, piping, streaming, cancellation, and environment variable configuration. USE FOR: executing CLI tools from .NET code, capturing stdout/stderr output,… - 100system-commandline-cli
Use this skill when adding, modifying, or reviewing CLI commands in a .NET project built with System.CommandLine. Triggers include: creating a new CLI command, adding options or arguments, wiring command handlers, registering subcommands, building command groups, or any… - 100commander
Build CLI tools with Commander.js. Use when creating command-line applications, parsing arguments, implementing subcommands, or building developer tools with flags and options. - 95building-python-clis
Builds command-line interfaces for Python libraries using Click or Typer. Includes command groups, argument handling, progress bars, shell completion, and CLI testing with CliRunner. Use when adding CLI functionality to a library or building standalone command-line tools. - 95rs-domain-cli
Use when building CLI tools. Keywords: CLI, command line, terminal, clap, structopt, argument parsing, subcommand, interactive, TUI, ratatui, crossterm, indicatif, progress bar, colored output, shell completion, config file, environment variable