CliWrap
CliWrap is a library that makes it easier to interact with command line interfaces. It provides a convenient wrapper around the target executable, allowing you to pass execution parameters and read the resulting output. The library can also handle errors reported by the underlying process, allows command cancellation and has both synchronous and asynchronous APIs.
Download
- NuGet:
dotnet add package CliWrap
- Continuous integration
Features
- Full abstraction over
System.Diagnostics.Process
- Execute commands in a synchronous, asynchronous, fire-and-forget manner
- Pass in command line arguments, standard input and environment variables
- Get process exit code, standard output and standard error as the result
- Abort the execution early using
System.Threading.CancellationToken
- Set up callbacks that trigger when a process writes to standard output or error
- Custom encoding settings for standard input, output and error
- Fluent interface
- Targets .NET Framework 4.5+ and .NET Standard 2.0+
- No external dependencies
Usage
Execute a command
You can configure and execute CLI processes in a fluent manner. Replace ExecuteAsync
with Execute
if you want a blocking operation instead.
var result = await Cli.Wrap("cli.exe")
.SetArguments("Hello world!")
.ExecuteAsync();
var exitCode = result.ExitCode;
var stdOut = result.StandardOutput;
var stdErr = result.StandardError;
var startTime = result.StartTime;
var exitTime = result.ExitTime;
var runTime = result.RunTime;
Argument list encoding
You can automatically encode command line arguments by passing them as a list.
var result = await Cli.Wrap("cli.exe")
.SetArguments(new[] {"--option", "some value"})
.ExecuteAsync();
Standard input
You can pass stdin either as a string or a binary stream.
var result = await Cli.Wrap("cli.exe")
.SetStandardInput("Hello world from stdin!")
.ExecuteAsync();
Environment variables
You can configure environment variables that will only be visible to the child process.
var result = await Cli.Wrap("cli.exe")
.SetEnvironmentVariable("var1", "value1")
.SetEnvironmentVariable("var2", "value2")
.ExecuteAsync();
Cancel execution
You can cancel execution at any point using CancellationToken
, which will also kill the child process.
using (var cts = new CancellationTokenSource())
{
cts.CancelAfter(TimeSpan.FromSeconds(5)); // e.g. timeout of 5 seconds
var result = await Cli.Wrap("cli.exe")
.SetCancellationToken(cts.Token)
.ExecuteAsync();
}
Callbacks for stdout and stderr
You can wire your own callbacks that will trigger on every line in stdout or stderr.
var result = await Cli.Wrap("cli.exe")
.SetStandardOutputCallback(l => Console.WriteLine($"StdOut> {l}")) // triggered on every line in stdout
.SetStandardErrorCallback(l => Console.WriteLine($"StdErr> {l}")) // triggered on every line in stderr
.ExecuteAsync();
Error handling
You can configure whether non-zero exit code or non-empty stderr should throw an exception.
var result = await Cli.Wrap("cli.exe")
.EnableExitCodeValidation(true) // throw exception on non-zero exit code (on by default)
.EnableStandardErrorValidation(true) // throw exception on non-empty stderr (off by default)
.ExecuteAsync();
Libraries used
Donate
If you really like my projects and want to support me, consider donating to me on Patreon or BuyMeACoffee. All donations are optional and are greatly appreciated.