CliWrap

Overview

CliWrap is a library for interacting with external command-line processes in .NET. It provides a fluent API for building commands, capturing output, piping between processes, streaming stdout/stderr in real time, and handling cancellation and timeouts. CliWrap replaces direct use of System.Diagnostics.Process with a safer, more composable, and async-first API.

NuGet Packages

bash

dotnet add package CliWrap

Basic Command Execution

csharp

using CliWrap;

// Simple execution (fire and forget with exit code check)
var result = await Cli.Wrap("dotnet")
    .WithArguments("--version")
    .ExecuteAsync();

Console.WriteLine($"Exit code: {result.ExitCode}");
Console.WriteLine($"Started: {result.StartTime}");
Console.WriteLine($"Exited: {result.ExitTime}");
Console.WriteLine($"Duration: {result.RunTime}");

Buffered Output (Capturing stdout/stderr)

csharp

using CliWrap;
using CliWrap.Buffered;

var result = await Cli.Wrap("dotnet")
    .WithArguments(["build", "--configuration", "Release"])
    .WithWorkingDirectory("/src/MyProject")
    .ExecuteBufferedAsync();

Console.WriteLine($"STDOUT:\n{result.StandardOutput}");
Console.WriteLine($"STDERR:\n{result.StandardError}");
Console.WriteLine($"Exit code: {result.ExitCode}");

Building Arguments

csharp

using CliWrap;

// Array-based arguments (automatically handles escaping)
var result = await Cli.Wrap("git")
    .WithArguments(["commit", "-m", "Fix: handle spaces in file names"])
    .ExecuteBufferedAsync();

// Builder-based arguments for complex commands
var result2 = await Cli.Wrap("docker")
    .WithArguments(args => args
        .Add("run")
        .Add("--rm")
        .Add("-v").Add("/host/path:/container/path")
        .Add("-e").Add("CONNECTION_STRING=Server=localhost;Database=mydb")
        .Add("--name").Add("my-container")
        .Add("mcr.microsoft.com/dotnet/sdk:8.0"))
    .ExecuteBufferedAsync();

Streaming Output in Real Time

csharp

using CliWrap;
using CliWrap.EventStream;

var cmd = Cli.Wrap("dotnet")
    .WithArguments(["test", "--verbosity", "normal"])
    .WithWorkingDirectory("/src/MyProject");

await foreach (var cmdEvent in cmd.ListenAsync())
{
    switch (cmdEvent)
    {
        case StartedCommandEvent started:
            Console.WriteLine($"Process started; PID: {started.ProcessId}");
            break;
        case StandardOutputCommandEvent stdOut:
            Console.WriteLine($"[OUT] {stdOut.Text}");
            break;
        case StandardErrorCommandEvent stdErr:
            Console.WriteLine($"[ERR] {stdErr.Text}");
            break;
        case ExitedCommandEvent exited:
            Console.WriteLine($"Process exited; Code: {exited.ExitCode}");
            break;
    }
}

Piping stdout/stderr

csharp

using CliWrap;

// Pipe to delegates
await Cli.Wrap("dotnet")
    .WithArguments(["build"])
    .WithStandardOutputPipe(PipeTarget.ToDelegate(line =>
        Console.WriteLine($"[BUILD] {line}")))
    .WithStandardErrorPipe(PipeTarget.ToDelegate(line =>
        Console.Error.WriteLine($"[ERROR] {line}")))
    .ExecuteAsync();

// Pipe to file
await Cli.Wrap("dotnet")
    .WithArguments(["test", "--logger", "trx"])
    .WithStandardOutputPipe(PipeTarget.ToFile("test-output.log"))
    .ExecuteAsync();

// Pipe to StringBuilder
var stdOutBuffer = new StringBuilder();
var stdErrBuffer = new StringBuilder();

await Cli.Wrap("git")
    .WithArguments(["log", "--oneline", "-20"])
    .WithStandardOutputPipe(PipeTarget.ToStringBuilder(stdOutBuffer))
    .WithStandardErrorPipe(PipeTarget.ToStringBuilder(stdErrBuffer))
    .ExecuteAsync();

Console.WriteLine(stdOutBuffer.ToString());

// Pipe to Stream
using var memoryStream = new MemoryStream();
await Cli.Wrap("curl")
    .WithArguments(["-s", "https://api.example.com/data"])
    .WithStandardOutputPipe(PipeTarget.ToStream(memoryStream))
    .ExecuteAsync();

// Pipe to multiple targets simultaneously
await Cli.Wrap("dotnet")
    .WithArguments(["build"])
    .WithStandardOutputPipe(PipeTarget.Merge(
        PipeTarget.ToDelegate(Console.WriteLine),
        PipeTarget.ToFile("build.log")))
    .ExecuteAsync();

Piping Between Processes

csharp

using CliWrap;

// Pipe stdout of one command into stdin of another (like shell pipes)
var result = await (
    Cli.Wrap("dotnet")
        .WithArguments(["tool", "list", "--global"]) |
    Cli.Wrap("findstr")
        .WithArguments(["dotnet-ef"])
).ExecuteBufferedAsync();

Console.WriteLine(result.StandardOutput);

Providing stdin Input

csharp

using CliWrap;

// Pipe string input
var result = await Cli.Wrap("dotnet")
    .WithArguments(["script", "eval"])
    .WithStandardInputPipe(PipeSource.FromString("Console.WriteLine(1 + 2);"))
    .ExecuteBufferedAsync();

// Pipe from file
await Cli.Wrap("python")
    .WithArguments(["script.py"])
    .WithStandardInputPipe(PipeSource.FromFile("input.txt"))
    .ExecuteAsync();

// Pipe from stream
using var inputStream = new MemoryStream("Hello, World!"u8.ToArray());
await Cli.Wrap("cat")
    .WithStandardInputPipe(PipeSource.FromStream(inputStream))
    .ExecuteAsync();

Cancellation and Timeouts

csharp

using CliWrap;

// Cancellation token
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

try
{
    await Cli.Wrap("dotnet")
        .WithArguments(["test"])
        .ExecuteAsync(cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Command was cancelled or timed out");
}

// Graceful shutdown: sends SIGINT first, then SIGKILL after timeout
using var cts2 = new CancellationTokenSource();
cts2.CancelAfter(TimeSpan.FromMinutes(5));

try
{
    await Cli.Wrap("long-running-process")
        .ExecuteAsync(
            forcefulCancellationToken: cts2.Token,
            gracefulCancellationToken: cts2.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Process was terminated");
}

Environment Variables and Configuration

csharp

using CliWrap;

var result = await Cli.Wrap("dotnet")
    .WithArguments(["run"])
    .WithWorkingDirectory("/src/MyApp")
    .WithEnvironmentVariables(env => env
        .Set("ASPNETCORE_ENVIRONMENT", "Staging")
        .Set("ConnectionStrings__Default", "Server=localhost;Database=testdb")
        .Set("DOTNET_CLI_TELEMETRY_OPTOUT", "1"))
    .WithValidation(CommandResultValidation.ZeroExitCode)
    .ExecuteAsync();

Error Handling

csharp

using CliWrap;
using CliWrap.Exceptions;

try
{
    await Cli.Wrap("dotnet")
        .WithArguments(["build"])
        .WithValidation(CommandResultValidation.ZeroExitCode) // Default behavior
        .ExecuteBufferedAsync();
}
catch (CommandExecutionException ex)
{
    Console.Error.WriteLine($"Command failed with exit code: {ex.ExitCode}");
    Console.Error.WriteLine($"Command: {ex.Command}");
}

// Disable validation to handle non-zero exit codes manually
var result = await Cli.Wrap("git")
    .WithArguments(["diff", "--exit-code"])
    .WithValidation(CommandResultValidation.None)
    .ExecuteBufferedAsync();

if (result.ExitCode != 0)
{
    Console.WriteLine("Working directory has changes:");
    Console.WriteLine(result.StandardOutput);
}

Wrapping Common CLI Tools

csharp

public class GitClient
{
    private readonly string _workingDirectory;

    public GitClient(string workingDirectory) =>
        _workingDirectory = workingDirectory;

    private Command BaseCommand => Cli.Wrap("git")
        .WithWorkingDirectory(_workingDirectory)
        .WithValidation(CommandResultValidation.ZeroExitCode);

    public async Task<string> GetCurrentBranchAsync(CancellationToken ct = default)
    {
        var result = await BaseCommand
            .WithArguments(["branch", "--show-current"])
            .ExecuteBufferedAsync(ct);
        return result.StandardOutput.Trim();
    }

    public async Task<string> GetStatusAsync(CancellationToken ct = default)
    {
        var result = await BaseCommand
            .WithArguments(["status", "--porcelain"])
            .ExecuteBufferedAsync(ct);
        return result.StandardOutput;
    }

    public async Task CommitAsync(string message, CancellationToken ct = default)
    {
        await BaseCommand
            .WithArguments(["add", "-A"])
            .ExecuteAsync(ct);

        await BaseCommand
            .WithArguments(["commit", "-m", message])
            .ExecuteAsync(ct);
    }

    public async Task<IReadOnlyList<string>> GetLogAsync(
        int count = 10, CancellationToken ct = default)
    {
        var result = await BaseCommand
            .WithArguments(["log", $"--oneline", $"-{count}"])
            .ExecuteBufferedAsync(ct);

        return result.StandardOutput
            .Split('\n', StringSplitOptions.RemoveEmptyEntries);
    }
}

Best Practices

•Use WithArguments(string[]) (array overload) instead of WithArguments(string) (raw string) to get automatic escaping of spaces, quotes, and special characters in argument values.
•Use ExecuteBufferedAsync only for commands with bounded output; for commands that may produce megabytes of output (e.g., dotnet test --verbosity detailed), use ListenAsync or pipe to a Stream to avoid memory pressure.
•Set WithValidation(CommandResultValidation.ZeroExitCode) explicitly (or rely on the default) to get CommandExecutionException on failure rather than silently ignoring non-zero exit codes.
•Always pass CancellationToken to ExecuteAsync and ExecuteBufferedAsync; use CancellationTokenSource.CancelAfter to enforce timeouts on long-running commands.
•Use WithWorkingDirectory to set the process working directory explicitly rather than relying on the host application's current directory, which may differ between development and deployment.
•Create typed wrapper classes (e.g., GitClient, DockerClient) that expose domain-specific methods using a shared BaseCommand property to centralize working directory, validation, and environment configuration.
•Use PipeTarget.Merge to send output to both a log file and the console simultaneously during build/deploy scripts where you need real-time feedback and a persistent record.
•Handle CommandExecutionException specifically (not just Exception) to extract the exit code and command details for structured error reporting and logging.
•Use the | pipe operator between Command instances (cmdA | cmdB) for shell-like piping instead of capturing intermediate output in memory and feeding it to the next process.
•Set environment variables with WithEnvironmentVariables rather than modifying Environment.SetEnvironmentVariable globally, which affects all threads and is not isolated per command.