CliWrap —— .NET 最优雅的命令行交互库

CliWrap

在 .NET 开发中，调用外部命令行工具是非常常见的需求——执行 git 操作、调用 ffmpeg 转码视频、运行 docker 命令。

如果你直接使用过 System.Diagnostics.Process，一定深有体会：重定向输出要手动处理、stdout 和 stderr 同时读取容易死锁、取消和超时逻辑写起来一团糟、参数转义稍有不慎就是安全漏洞。

CliWrap 由乌克兰开发者 Tyrrrz（Oleksii Holub）开发，是一款专注于命令行交互的轻量级 .NET 开源库。自 2017 年首次发布以来，已积累近 5000 Star，最新版本 3.10.1 于 2026 年 3 月发布，一直保持活跃迭代。

项目采用 MIT 协议，零外部依赖，支持 .NET Standard 2.0+ 全平台运行（Windows、Linux、macOS）。

功能特性

CliWrap 的设计理念可以概括为六个字：流畅、安全、异步。

流畅的链式 API 以 Command 为核心抽象，通过 Cli.Wrap() 起手，链式配置参数、工作目录、环境变量，最后调用 ExecuteAsync() 执行。Command 对象严格不可变，每次配置返回新实例，天然线程安全，可放心复用：

var result = await Cli.Wrap("git")
    .WithArguments(["commit", "-m", "my commit"])
    .ExecuteAsync();

强大的管道系统这是 CliWrap 最令人惊艳的特性。它提供 PipeSource（输入源）和 PipeTarget（输出目标）两大抽象，输入可来自文件、流、字符串甚至另一个命令的输出；输出可导向文件、StringBuilder、委托，甚至同时分发到多个目标。更酷的是，它重载了 | 管道操作符，让你像写 Shell 一样组合命令：

// 等价于: cat access.log | grep ERROR | sort
await (Cli.Wrap("cat").WithArguments(["access.log"])
    | Cli.Wrap("grep").WithArguments(["ERROR"])
    | Cli.Wrap("sort"))
    .ExecuteAsync();

多种执行模型除了基础的 ExecuteAsync()，还提供三种高级模式满足不同场景：

缓冲执行（ExecuteBufferedAsync）：自动将 stdout/stderr 缓冲为字符串，适合简单场景拉取式事件流（ListenAsync）：返回 IAsyncEnumerable，支持 await foreach 逐行实时处理，自带背压控制推送式事件流（Observe）：返回 IObservable，可搭配 Rx.NET 进行响应式编程优雅的取消机制支持双层取消令牌——先发送 Ctrl+C 信号优雅中断，超时后再强制终止进程，防止任务无限挂起。

安全可靠参数构建器自动转义，从源头杜绝注入漏洞；默认校验退出码，非零自动抛异常；内置死锁防护，不会出现 Process 类常见的读写死锁问题；最新版已支持 AOT 编译。

如何使用

一行命令通过 NuGet 引入：

dotnet add package CliWrap

执行命令并获取输出

using CliWrap.Buffered;

var result = await Cli.Wrap("dotnet")
    .WithArguments(["--version"])
    .ExecuteBufferedAsync();

Console.WriteLine(result.StandardOutput); // e.g. "10.0.100"

实时处理构建日志

using CliWrap.EventStream;

await foreach (var evt in Cli.Wrap("dotnet")
    .WithArguments(["build"]).ListenAsync())
{
    if (evt is StandardOutputCommandEvent stdOut)
        Console.WriteLine(stdOut.Text);
}

带超时的 ffmpeg 转码

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));

await Cli.Wrap("ffmpeg")
    .WithArguments(["-i", "input.mp4", "output.webm"])
    .ExecuteAsync(cts.Token);

适用场景

CliWrap 几乎适用于所有需要调用外部 CLI 工具的 .NET 场景：CI/CD 流水线编排、音视频处理（ffmpeg）、数据库备份（mysqldump）、容器操作（docker/kubectl）、代码生成工具调用等。

如果你还在和 Process 类搏斗，是时候试试 CliWrap 了。正如它名字的含义——用最简洁的方式，把命令行优雅地"包"起来。

出处：https://mp.weixin.qq.com/s/9A4UGAYIQuwr8nYDSGEw1A

=======================================================================================

使用 CliWrap 让C#中的命令行交互

在代码中进行命令行交互是一个很常见的场景, 特别是在一些CI CD 自动化流程中, 在这之前我们会使用 System.Diagnostics.Process API, 现在有一个更灵活的工具 CliWarp, 这是一个在 .NET 平台使用的命令行交互工具库, 通过在C# 中使用 Fluent 的API, 让命令行交互举重若轻。

https://github.com/Tyrrrz/CliWrap

主要特性如下：

基于 System.Diagnostics.Process
简单, 流畅的 API 设计
灵活的支持管道模式
安全异步并且支持 cancellation API
跨平台, 可在 Windows、Linux 和 macOS 使用
支持 .NET Standard 2.0+、.NET Core 3.0+、.NET Framework 4.6.1+

和 shell 是类似的，CliWrap 的基本工作单元是一个 command , 首先会执行 Cli.Wrap(...) 创建 command, 参数是可执行文件的路径, 然后通过 fluent api 配置, 最后调用 ExecuteAsync 运行命令，如下:

using CliWrap;
using CliWrap.Buffered;

var result = await Cli.Wrap("path/to/exe") 
     //....
    .ExecuteBufferedAsync();

配置参数

var cmd = Cli.Wrap("git")
    .WithArguments("commit -m \"my commit\"");

var cmd = Cli.Wrap("git")
    .WithArguments(new[] {"commit", "-m", "my commit"});

var cmd = Cli.Wrap("git")
    .WithArguments(args => args
        .Add("clone")
        .Add("https://github.com/Tyrrrz/CliWrap")
        .Add("--depth")
        .Add(20));

配置工作目录

默认是当前目录, 你也可以指定文件夹的相对路径和绝对路径

var cmd = Cli.Wrap("git")
    .WithWorkingDirectory("c:/projects/my project/");

配置环境变量

var cmd = Cli.Wrap("git")
    .WithEnvironmentVariables(env => env
        .Set("GIT_AUTHOR_NAME", "John")
        .Set("GIT_AUTHOR_EMAIL", "john@email.com"));

超时和取消

using var cts = new CancellationTokenSource(); 
 
cts.CancelAfter(TimeSpan.FromSeconds(10));

var result = await Cli.Wrap("path/to/exe").ExecuteAsync(cts.Token);

基于拉取的事件流

除了执行命令之外，CliWrap 还支持事件流模型, 可以订阅相关的事件回调。

StartedCommandEvent -- 仅接收一次，当命令开始执行时（包含 process ID）
StandardOutputCommandEvent -- 每次底层进程向输出流写入新行时收到（包含文本作为字符串）
StandardErrorCommandEvent -- 每次底层进程向错误流写入新行时收到（包含文本作为字符串）
ExitedCommandEvent -- 仅接收一次，当命令完成执行时（包含 exit code）

using CliWrap;
using CliWrap.EventStream;

var cmd = Cli.Wrap("foo").WithArguments("bar");

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;
    }
}