gem-hunter
Language: C#
Library for interacting with command-line interfaces
| Development of this project is entirely funded by the community. Consider donating to support! |
CliWrap is a library for interacting with command-line interfaces. It provides a convenient model for launching processes, redirecting input and output streams, awaiting completion, handling cancellation, and more.
By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:
To learn more about the war and how you can help, click here. Glory to Ukraine! 🇺🇦
dotnet add package CliWrapTip
You can use Binternal to internalize this library if you prefer to avoid taking an external dependency.
System.Diagnostics.ProcessYou can watch one of these videos to learn how to use the library:
Similarly to a shell, CliWrap's base unit of work is a command — an object that encapsulates instructions for running a process.
To build a command, start by calling Cli.Wrap(...) with the executable path, and then use the provided fluent interface to configure arguments, working directory, or other options.
Once the command is configured, you can run it by calling ExecuteAsync():
using CliWrap; var result = await Cli.Wrap("path/to/exe") .WithArguments(["--foo", "bar"]) .WithWorkingDirectory("work/dir/path") .ExecuteAsync(); // Result contains: // -- result.ExitCode (int) // -- result.IsSuccess (bool) // -- result.StartTime (DateTimeOffset) // -- result.ExitTime (DateTimeOffset) // -- result.RunTime (TimeSpan)
The code above spawns a child process with the configured command-line arguments and working directory, and then asynchronously waits for it to exit.
After the task has completed, it resolves to a CommandResult object that contains the process exit code and other relevant information.
Warning
CliWrap will throw an exception if the underlying process returns a non-zero exit code, as it usually indicates an error.
You can override this behavior by disabling result validation using WithValidation(CommandResultValidation.None).
By default, the process's standard input, output and error streams are routed to CliWrap's equivalent of a null device, which represents an empty source and a target that discards all data.
You can change this by calling WithStandardInputPipe(...), WithStandardOutputPipe(...), or WithStandardErrorPipe(...) to configure pipes for the corresponding streams:
using CliWrap; var stdOutBuffer = new StringBuilder(); var stdErrBuffer = new StringBuilder(); var result = await Cli.Wrap("path/to/exe") .WithArguments(["--foo", "bar"]) .WithWorkingDirectory("work/dir/path") // This can be simplified with `ExecuteBufferedAsync()` .WithStandardOutputPipe(PipeTarget.ToStringBuilder(stdOutBuffer)) .WithStandardErrorPipe(PipeTarget.ToStringBuilder(stdErrBuffer)) .ExecuteAsync(); // Access stdout & stderr buffered in-memory as strings var stdOut = stdOutBuffer.ToString(); var stdErr = stdErrBuffer.ToString();
This example command is configured to decode the data written to the standard output and error streams as text, and append it to the corresponding StringBuilder buffers.
Once the execution is complete, these buffers can be inspected to see what the process has printed to the console.
Handling command output is a very common use case, so CliWrap offers a few high-level execution models to make these scenarios simpler.
In particular, the same thing shown above can also be achieved more succinctly with the ExecuteBufferedAsync() extension method:
using CliWrap; using CliWrap.Buffered; // Calling `ExecuteBufferedAsync()` instead of `ExecuteAsync()` // implicitly configures pipes that write to in-memory buffers. var result = await Cli.Wrap("path/to/exe") .WithArguments(["--foo", "bar"]) .WithWorkingDirectory("work/dir/path") .ExecuteBufferedAsync(); // Result contains: // -- result.StandardOutput (string) * // -- result.StandardError (string) * // -- result.ExitCode (int) // -- result.IsSuccess (bool) // -- result.StartTime (DateTimeOffset) // -- result.ExitTime (DateTimeOffset) // -- result.RunTime (TimeSpan)
Warning
Be mindful when using ExecuteBufferedAsync().
Programs can write arbitrary data (including binary) to the output and error streams, and storing it in-memory may be impractical.
For more advanced scenarios, CliWrap also provides other piping options, which are covered in the piping section.
The fluent interface provided by the command object allows you to configure various aspects of its execution. This section covers all available configuration methods and their usage.
Note
Command is an immutable object — all configuration methods listed here create a new instance instead of modifying the existing one.
Sets the command-line arguments passed to the child process.
Default: empty.
Examples:
var cmd = Cli.Wrap("git") // Each element is formatted as a separate argument. // Equivalent to: `git commit -m "my commit"` .WithArguments(["commit", "-m", "my commit"]);
var cmd = Cli.Wrap("git") // Each Add(...) call takes care of formatting automatically. // Equivalent to: `git clone https://github.com/Tyrrrz/CliWrap --depth 20` .WithArguments(args => args .Add("clone") .Add("https://github.com/Tyrrrz/CliWrap") .Add("--depth") .Add(20) );
var forcePush = true; var cmd = Cli.Wrap("git") // Arguments can also be constructed in an imperative fashion. // Equivalent to: `git push --force` .WithArguments(args => { args.Add("push"); if (forcePush) args.Add("--force"); });
Tip
The builder overload allows you to define custom extension methods for reusable argument patterns. Learn more.
var cmd = Cli.Wrap("git") // Avoid using this overload unless you really have to. // Equivalent to: `git commit -m "my commit"` .WithArguments("commit -m \"my commit\"");
Warning
Unless you absolutely have to, avoid setting command-line arguments directly from a string. This method expects all arguments to be correctly escaped and formatted ahead of time — which can be cumbersome to do yourself. Formatting errors may result in unexpected bugs and security vulnerabilities.
Note
There are some obscure scenarios, where you may need to assemble the command-line arguments yourself.
In such cases, you can use the ArgumentsBuilder.Escape(...) method to escape individual arguments manually.
Sets the working directory of the child process.
Default: current working directory, i.e., Directory.GetCurrentDirectory().
Example:
var cmd = Cli.Wrap("git") .WithWorkingDirectory("/home/john/Projects/");
Sets additional environment variables exposed to the child process.
Default: empty.
Examples:
var cmd = Cli.Wrap("git") .WithEnvironmentVariables(env => env .Set("GIT_AUTHOR_NAME", "John") .Set("GIT_AUTHOR_EMAIL", "john@email.com") );
var cmd = Cli.Wrap("git") .WithEnvironmentVariables(new Dictionary<string, string?> { ["GIT_AUTHOR_NAME"] = "John", ["GIT_AUTHOR_EMAIL"] = "john@email.com" });
Note
Environment variables configured using WithEnvironmentVariables(...) are applied on top of those inherited from the parent process.
If you need to remove an inherited variable, set the corresponding value to null.
Sets the system resource management policy for the child process.
Default: default policy.
Examples:
var cmd = Cli.Wrap("git") .WithResourcePolicy(policy => policy .SetPriority(ProcessPriorityClass.High) .SetAffinity(0b1010) .SetMinWorkingSet(1024) .SetMaxWorkingSet(4096) );
var cmd = Cli.Wrap("git") .WithResourcePolicy(new ResourcePolicy( priority: ProcessPriorityClass.High, affinity: 0b1010, minWorkingSet: 1024, maxWorkingSet: 4096 ));
Warning
Resource policy options have varying support across different platforms.
Sets domain, name and password of the user, under whom the child process should be started.
Default: no credentials.
Examples:
var cmd = Cli.Wrap("git") .WithCredentials(creds => creds .SetDomain("some_workspace") .SetUserName("johndoe") .SetPassword("securepassword123") .LoadUserProfile() );
var cmd = Cli.Wrap("git") .WithCredentials(new Credentials( domain: "some_workspace", userName: "johndoe", password: "securepassword123", loadUserProfile: true ));
Warning
Running a process under a different username is supported across all platforms, but other options are only available on Windows.
Sets the strategy for validating the result of an execution.
Accepted values:
CommandResultValidation.None — no validation.CommandResultValidation.ZeroExitCode — ensures zero exit code when the process exits.Default: CommandResultValidation.ZeroExitCode.
Examples:
var cmd = Cli.Wrap("git") .WithValidation(CommandResultValidation.ZeroExitCode);
var cmd = Cli.Wrap("git") .WithValidation(CommandResultValidation.None);
With the result validation disabled, you have several ways to inspect the exit code of the process after it finishes executing:
var result = await Cli.Wrap("git") .WithValidation(CommandResultValidation.None) .ExecuteAsync(); // Check if exit code is zero if (result.IsSuccess) { // ... } // Same thing, but more succint if (result) { // ... } // Check for a specific exit code if (result.ExitCode == 42) { // ... } // Same thing, but more succint if (result == 42) { // ... }
If you want to throw a custom exception when the process exits with a non-zero exit code, don't disable result validation, but instead catch the default CommandExecutionException and re-throw it inside your own exception.
This way you can preserve the information provided by the original exception, while extending it with additional context:
try { await Cli.Wrap("git").ExecuteAsync(); } catch (CommandExecutionException ex) { // Re-throw the original exception to preserve additional information // about the command that failed (exit code, arguments, etc.). throw new MyException("Failed to run the git command-line tool.", ex); }
Sets the pipe source that will be used for the standard input stream of the process.
Default: PipeSource.Null.
Read more about this method in the piping section.
Sets the pipe target that will be used for the standard output stream of the process.
Default: PipeTarget.Null.
Read more about this method in the piping section.
Sets the pipe target that will be used for the standard error stream of the process.
Default: PipeTarget.Null.
Read more about this method in the piping section.
CliWrap provides a very powerful and flexible piping model that allows you to redirect process's streams, transform input and output data, and even chain multiple commands together with minimal effort.
At its core, it's based on two abstractions: PipeSource which provides data for the standard input stream, and PipeTarget which reads data coming from the standard output stream or the standard error stream.
By default, a command's input pipe is set to PipeSource.Null and the output and error pipes are set to PipeTarget.Null.
These objects effectively represent no-op stubs that provide empty input and discard all output respectively.
You can specify your own PipeSource and PipeTarget instances by calling the corresponding configuration methods on the command:
await using var input = File.OpenRead("data.csv"); await using var output = File.Create("sorted.csv"); await Cli.Wrap("sort") .WithStandardInputPipe(PipeSource.FromStream(input)) .WithStandardOutputPipe(PipeTarget.ToStream(output)) .ExecuteAsync();
Alternatively, pipes can also be configured in a slightly terser way using pipe operators:
await using var input = File.OpenRead("data.csv"); await using var output = File.Create("sorted.csv"); await (input | Cli.Wrap("sort") | output).ExecuteAsync();
Both PipeSource and PipeTarget have many factory methods that let you create pipe implementations for different scenarios:
PipeSource:
PipeSource.Null — represents an empty pipe source.PipeSource.FromStream(...) — pipes data from any readable stream.PipeSource.FromFile(...) — pipes data from a file.PipeSource.FromBytes(...) — pipes data from a byte array.PipeSource.FromString(...) — pipes data from a text string.PipeSource.FromCommand(...) — pipes data from the standard output of another command.PipeTarget:
PipeTarget.Null — represents a pipe target that discards all data.PipeTarget.ToStream(...) — pipes data to any writable stream.PipeTarget.ToFile(...) — pipes data to a file.PipeTarget.ToStringBuilder(...) — pipes data as text into a StringBuilder.PipeTarget.ToDelegate(...) — pipes data as text, line-by-line, into an Action<string>, or a Func<string, Task>, or a Func<string, CancellationToken, Task> delegate.PipeTarget.Merge(...) — merges multiple outbound pipes by replicating the same data across all of them.Warning
Using PipeTarget.Null results in the corresponding stream (stdout or stderr) not being opened for the underlying process at all.
In the vast majority of cases, this behavior should be functionally equivalent to piping to a null stream, but without the performance overhead of consuming and discarding unneeded data.
This may be undesirable in certain situations — in which case it's recommended to pipe to a null stream explicitly using PipeTarget.ToStream(Stream.Null).
Below you can see some examples of what you can achieve with the help of CliWrap's piping feature:
var cmd = "SELECT * FROM users;" | Cli.Wrap("sqlite3").WithArguments(["myapp.db"]); await cmd.ExecuteAsync();
StringBuilder:var stdOutBuffer = new StringBuilder(); var cmd = Cli.Wrap("git").WithArguments(["log", "--oneline"]) | stdOutBuffer; await cmd.ExecuteAsync();
using var http = new HttpClient(); await using var input = await http.GetStreamAsync("https://example.com/music.mp3"); var cmd = input | Cli.Wrap("ffmpeg") .WithArguments(["-i", "pipe:0", "output.ogg"]); await cmd.ExecuteAsync();
var cmd = Cli.Wrap("cat").WithArguments(["access.log"]) | Cli.Wrap("grep").WithArguments(["ERROR"]) | Cli.Wrap("sort"); await cmd.ExecuteAsync();
await using var stdOut = Console.OpenStandardOutput(); await using var stdErr = Console.OpenStandardError(); var cmd = Cli.Wrap("docker").WithArguments(["build", "."]) | (stdOut, stdErr); await cmd.ExecuteAsync();
var cmd = Cli.Wrap("ping").WithArguments(["-c", "4", "example.com"]) | Debug.WriteLine; await cmd.ExecuteAsync();
StringBuilder:var errorBuffer = new StringBuilder(); var cmd = Cli.Wrap("curl").WithArguments(["-s", "https://api.example.com/data"]) | ( PipeTarget.ToFile("response.json"), PipeTarget.ToStringBuilder(errorBuffer) ); await cmd.ExecuteAsync();
var cmd = Cli.Wrap("mysqldump").WithArguments(["-u", "root", "mydb"]) | PipeTarget.Merge( PipeTarget.ToDelegate(Console.WriteLine), PipeTarget.ToDelegate( line => logger.LogInformation("Dump: {Line}", line) ), PipeTarget.ToFile("backup.sql") ); await cmd.ExecuteAsync();
var cmd = """ { "name": "Alice", "age": 30 } """ | Cli.Wrap("jq").WithArguments([".name"]) | Cli.Wrap("tee").WithArguments(["formatted.json"]) | (Console.WriteLine, Console.Error.WriteLine); await cmd.ExecuteAsync();
CliWrap provides a few high-level execution models that offer alternative ways to reason about commands. These are essentially just extension methods that work by leveraging the piping feature shown earlier.
This execution model lets you run a process while buffering its standard output and error streams in-memory as text. The buffered data can then be accessed after the command finishes executing.
In order to execute a command with buffering, call the ExecuteBufferedAsync() extension method:
using CliWrap; using CliWrap.Buffered; var result = await Cli.Wrap("python") .WithArguments(["script.py"]) .ExecuteBufferedAsync(); // Result contains: // -- result.StandardOutput (string) * // -- result.StandardError (string) * // -- result.ExitCode (int) // -- result.IsSuccess (bool) // -- result.StartTime (DateTimeOffset) // -- result.ExitTime (DateTimeOffset) // -- result.RunTime (TimeSpan)
The result object returned by this execution model also has a few convenience shorthands. For example, you can use the tuple deconstruction syntax to extract the exit code, standard output, and standard error — all within a single statement:
var (exitCode, stdOut, stdErr) = await Cli.Wrap("python") .WithArguments(["script.py"]) .ExecuteBufferedAsync();
If you are only interested in the standard output part of the result, you can streamline the code even further by using the provided implicit conversion:
string stdOut = await Cli.Wrap("python") .WithArguments(["script.py"]) .ExecuteBufferedAsync();
By default, ExecuteBufferedAsync() assumes that the underlying process uses the default encoding (Encoding.Default) for writing text to the console.
To override this, specify the encoding explicitly by using one of the available overloads:
// Treat both stdout and stderr as UTF8-encoded text streams var result = await Cli.Wrap("python") .WithArguments(["script.py"]) .ExecuteBufferedAsync(Encoding.UTF8); // Treat stdout as ASCII-encoded and stderr as UTF8-encoded var result = await Cli.Wrap("python") .WithArguments(["script.py"]) .ExecuteBufferedAsync(Encoding.ASCII, Encoding.UTF8);
Note
If the underlying process returns a non-zero exit code, ExecuteBufferedAsync() will throw an exception similarly to ExecuteAsync(), but the exception message will also include the standard error data.
Besides executing a command as a task, CliWrap also supports an alternative model, in which the execution is represented as an event stream. This lets you start a process and react to the events it produces in real-time.
Those events are:
StartedCommandEvent — received just once, when the command starts executing (contains the process ID).StandardOutputCommandEvent — received every time the underlying process writes a new line to the output stream (contains the text as a string).StandardErrorCommandEvent — received every time the underlying process writes a new line to the error stream (contains the text as a string).ExitedCommandEvent — received just once, when the command finishes executing (contains the exit code).To execute a command as a pull-based event stream, use the ListenAsync() extension method:
using CliWrap; using CliWrap.EventStream; var cmd = Cli.Wrap("dotnet").WithArguments(["build"]); await foreach (var cmdEvent in cmd.ListenAsync()) { switch (cmdEvent) { case StartedCommandEvent started: _output.WriteLine($"Process started; ID: {started.ProcessId}"); break; case StandardOutputCommandEvent stdOut: _output.WriteLine($"Out> {stdOut.Text}"); break; case StandardErrorCommandEvent stdErr: _output.WriteLine($"Err> {stdErr.Text}"); break; case ExitedCommandEvent exited: _output.WriteLine($"Process exited; Code: {exited.ExitCode}"); break; } }
The ListenAsync() method starts the command and returns an object of type IAsyncEnumerable<CommandEvent>, which you can iterate using the await foreach construct.
When using this execution model, back pressure is facilitated by locking the pipes between each iteration of the loop, preventing unnecessary buffering of data in-memory.
Note
Just like with ExecuteBufferedAsync(), you can specify custom encoding for ListenAsync() using one of its overloads.
Note
Abandoning the iterator (via break, return, or throw) will terminate the underlying process as if forceful cancellation were requested.
Similarly to the pull-based stream, you can also execute a command as a push-based event stream instead:
using System.Reactive; using CliWrap; using CliWrap.EventStream; var cmd = Cli.Wrap("dotnet").WithArguments(["build"]); await cmd.Observe().ForEachAsync(cmdEvent => { switch (cmdEvent) { case StartedCommandEvent started: _output.WriteLine($"Process started; ID: {started.ProcessId}"); break; case StandardOutputCommandEvent stdOut: _output.WriteLine($"Out> {stdOut.Text}"); break; case StandardErrorCommandEvent stdErr: _output.WriteLine($"Err> {stdErr.Text}"); break; case ExitedCommandEvent exited: _output.WriteLine($"Process exited; Code: {exited.ExitCode}"); break; } });
In this case, Observe() returns a cold IObservable<CommandEvent> that represents an observable stream of command events.
You can use the set of extensions provided by Rx.NET to transform, filter, throttle, or otherwise manipulate this stream.
Unlike the pull-based event stream, this execution model does not involve any back pressure, meaning that the data is pushed to the observer at the rate that it becomes available.
Note
Similarly to ExecuteBufferedAsync(), you can specify custom encoding for Observe() using one of its overloads.
Note
Disposing the subscription will terminate the underlying process as if forceful cancellation were requested.
The different execution models shown above are based on the piping model, but those two concepts are not mutually exclusive.
When running a command using one of the built-in execution models, existing pipe configurations are preserved and extended using PipeTarget.Merge(...).
This means that you can, for example, pipe a command to a file and simultaneously execute it as an event stream:
var cmd = Cli.Wrap("dotnet").WithArguments(["test"]) | PipeTarget.ToFile("test-output.log"); // Iterate as an event stream and pipe to a file at the same time // (execution models preserve configured pipes) await foreach (var cmdEvent in cmd.ListenAsync()) { // ... }
Command execution is asynchronous in nature as it involves a completely separate process. In many cases, it may be useful to implement an abortion mechanism to stop the execution before it finishes, either through a manual trigger or a timeout.
To do that, issue the corresponding CancellationToken and include it when calling ExecuteAsync():
using System.Threading; using CliWrap; using var cts = new CancellationTokenSource(); // Cancel after a timeout of 10 seconds cts.CancelAfter(TimeSpan.FromSeconds(10)); var result = await Cli.Wrap("ffmpeg") .WithArguments(["-i", "input.mp4", "output.webm"]) .ExecuteAsync(cts.Token);
In the event of a cancellation request, the underlying process will be killed and ExecuteAsync() will throw an exception of type OperationCanceledException (or its derivative, TaskCanceledException).
You will need to catch this exception in your code to recover from cancellation:
try { await Cli.Wrap("ffmpeg") .WithArguments(["-i", "input.mp4", "output.webm"]) .ExecuteAsync(cts.Token); } catch (OperationCanceledException) { // Command was canceled }
Note
When the command is canceled, ExecuteAsync() will only complete after the kill signal has been fully settled by the operating system and the underlying process has exited.
Besides outright killing the process, you can also request cancellation in a more graceful way by sending an interrupt signal.
To do that, pass an additional cancellation token to ExecuteAsync() that corresponds to that request:
using var forcefulCts = new CancellationTokenSource(); using var gracefulCts = new CancellationTokenSource(); // Cancel forcefully after a timeout of 10 seconds. // This serves as a fallback in case graceful cancellation // takes too long. forcefulCts.CancelAfter(TimeSpan.FromSeconds(10)); // Cancel gracefully after a timeout of 7 seconds. // If the process takes too long to respond to graceful // cancellation, it will get killed by forceful cancellation // 3 seconds later (as configured above). gracefulCts.CancelAfter(TimeSpan.FromSeconds(7)); var result = await Cli.Wrap("ffmpeg") .WithArguments(["-i", "input.mp4", "output.webm"]) .ExecuteAsync(forcefulCts.Token, gracefulCts.Token);
Requesting graceful cancellation in CliWrap is functionally equivalent to pressing Ctrl+C in the console window.
The underlying process may handle this signal to perform last-minute critical work before finally exiting on its own terms.
Graceful cancellation is inherently cooperative, so it's possible that the process may take too long to fulfill the request or choose to ignore it altogether. In the above example, this risk is mitigated by additionally scheduling a delayed forceful cancellation that prevents the command from hanging.
You can also leverage the following pattern to implement a timeout-based fallback without exposing both cancellation tokens to the caller:
public async Task GitPushAsync(CancellationToken cancellationToken = default) { using var forcefulCts = new CancellationTokenSource(); // When the cancellation token is triggered, // schedule forceful cancellation as a fallback. await using var link = cancellationToken.Register(() => forcefulCts.CancelAfter(TimeSpan.FromSeconds(3)) ); await Cli.Wrap("git") .WithArguments(["push"]) // Provided cancellation token is used for graceful cancellation. // Forceful cancellation is triggered 3 seconds later if needed. .ExecuteAsync(forcefulCts.Token, cancellationToken); }
Note
Similarly to ExecuteAsync(), both cancellation mechanisms are also supported by ExecuteBufferedAsync(), ListenAsync(), and Observe().
The task returned by ExecuteAsync() and ExecuteBufferedAsync() is, in fact, not a regular Task<T>, but an instance of CommandTask<T>.
This is a specialized awaitable object that contains additional information about the process associated with the executing command.
Currently, this object includes only one extra property, ProcessId, which exposes the ID of the underlying process:
var task = Cli.Wrap("ffmpeg") .WithArguments(["-i", "input.mp4", "output.webm"]) .ExecuteAsync(); // Get the process ID var processId = task.ProcessId; // Wait for the task to complete await task;
CliWrap is made out of "Cli" for "Command-line Interface" and "Wrap" for "wrapper". It's pronounced as "klee wrap".