ProcessX 2.0.0
dotnet add package ProcessX --version 2.0.0
NuGet\Install-Package ProcessX -Version 2.0.0
<PackageReference Include="ProcessX" Version="2.0.0" />
<PackageVersion Include="ProcessX" Version="2.0.0" />
<PackageReference Include="ProcessX" />
paket add ProcessX --version 2.0.0
#r "nuget: ProcessX, 2.0.0"
#:package ProcessX@2.0.0
#addin nuget:?package=ProcessX&version=2.0.0
#tool nuget:?package=ProcessX&version=2.0.0
ProcessX
ProcessX v2 lets you write shell scripts in C#, like google/zx. v2 requires .NET 11 and adds easy-to-use features on top of the high-performance .NET 11 Process API. It works especially well with file-based apps.
#!/usr/bin/env dotnet
#:package ProcessX@2.*
using ProcessX;
using static ProcessX.Zx;
// `await string` runs it through the shell and returns stdout
await "dotnet --list-sdks | sort";
// receive stdout as a string, and pass it to the next command with run($"...")
var branch = await "git branch --show-current";
await run($"git push origin {branch}");
// execute in parallel
var (dotnet, git, msg) = await (
run("dotnet --version"),
run("git --version"),
sh("echo foo")
);
Save it as build.cs and run it with dotnet run build.cs (or chmod +x build.cs && ./build.cs).
Getting Started
ProcessX requires .NET 11 or later.
In a file-based app, add the package with a directive:
#:package ProcessX@2.*
In a project, install it from NuGet:
dotnet add package ProcessX
Then import the API, using ProcessX; and using static ProcessX.Zx;.
using ProcessX;
using static ProcessX.Zx;
Awaiting a command runs the process and gives you its output. There are three ways to write a command: await "...", await run($"...") and await sh($"...").
await run($"..."): start a process without a shell
run splits the literal text on whitespace and passes each interpolation hole as it is. A value never needs quoting or escaping because it never meets a shell.
using ProcessX;
using static ProcessX.Zx;
var dir = "foo/foo bar";
await run($"mkdir {dir}"); // mkdir "foo/foo bar" (one argument)
var author = "A B";
await run($"git log --author={author}"); // a hole joins the text around it: "--author=A B"
string[] files = ["a b.txt", "c.txt"];
await run($"rm {files}"); // a sequence expands to one argument per element
var release = true;
await run($"dotnet build {(release ? ["-c", "Release"] : [])}"); // optional arguments
string? filter = null;
await run($"dotnet test {filter}"); // null adds nothing ("" would add an empty argument)
await run($"git commit -m 'fixed text'"); // quotes group literal text; backslash is an ordinary character
await run("dotnet --version"); // a plain string is split the same way
Numbers and other IFormattable values are formatted with the invariant culture.
There is no shell, so a glob such as *.txt is not expanded. Expand it in C# and pass the sequence:
await run($"rm {Directory.GetFiles(".", "*.txt")}");
For the same reason run can only start an executable. A command that the shell provides needs sh (or await "..."), and the error message says so when that is the case:
- Shell built-ins. On Windows that includes
echo,dir,type,copyandset, sorun($"echo hello")works on Linux and macOS but not on Windows. - Batch files on Windows. Many tools are one:
npmisnpm.cmd,codeiscode.cmd,azisaz.cmd.
await "...", await sh($"..."): run through the shell
await "..." runs a constant script through the shell and returns stdout as a string.
sh($"...") runs through the shell too, and like run it takes values in {}. The text is the script, and each interpolation hole is a value that is quoted for the shell, so it stays one argument and can not be read as script.
using ProcessX;
using static ProcessX.Zx;
await "cat package.json | grep name";
var branch = await "git branch --show-current";
var path = "my file.txt & del *";
await sh($"type {path} | findstr TODO"); // cmd.exe gets: type "my file.txt & del *" | findstr TODO
var author = "A B";
await sh($"git log --author={author} | sort"); // a hole joins the text around it, as in run
string[] packages = ["left-pad", "is-odd"];
await sh($"npm install {packages}"); // a sequence is one quoted value per element
string? filter = null;
await sh($"dotnet test {filter} | sort"); // null adds nothing
var redirect = "> sdks.txt";
await sh($"dotnet --list-sdks {redirect:raw}"); // :raw inserts the value as script text, unquoted
How a value is quoted depends on the shell:
| Shell | A value is written as | |
|---|---|---|
| bash, sh and custom shells | 'value', a quote inside as '\'' |
Any value. |
| pwsh | 'value', a quote inside doubled |
Any value. |
| cmd.exe | "value" |
cmd.exe has no way to quote every character: a value that contains ", % or a line break throws ArgumentException. Use run, or another shell. |
A string that is not an interpolated string reaches the shell as it is, in sh and in await "...". Both only accept a compile-time constant there; anything else is an error (PX001, PX003):
await $"git checkout {branch}"; // error PX001: await can not quote the value
await sh("git checkout " + branch); // error PX003: a script built at runtime
await sh($"git checkout {branch} && make"); // OK, branch is quoted
await run($"git checkout {branch}"); // OK, no shell
The shell is cmd.exe on Windows and bash (/bin/sh if there is no bash) on others. Change it with Zx.shell:
shell = Shell.Pwsh; // Shell.Cmd, Shell.Bash, Shell.Sh, Shell.Pwsh
shell = new Shell("/bin/zsh", "-c"); // or any command that takes the script as the last argument
The built-in shells are set up so that a failure inside the script is not lost, as google/zx does:
| Shell | Added to the script | Effect |
|---|---|---|
Shell.Bash (and the default on Linux/macOS) |
set -euo pipefail; in front |
A failing command, a failing command inside a pipe (a \| b), or an unset variable fails the script. |
Shell.Sh |
set -eu; in front |
A failing command or an unset variable fails the script. |
Shell.Pwsh |
$ErrorActionPreference = 'Stop'; in front, ; exit $LASTEXITCODE after |
A cmdlet error stops the script, and the exit code of a native command is passed on. |
Shell.Cmd |
nothing | cmd.exe has no such option: a & b and a \| b report only the last command. |
A shell created with new Shell(...) adds nothing unless you say so:
shell = new Shell("/bin/zsh", "-c") { Prefix = "set -euo pipefail; " };
shell = new Shell("bash", "-c"); // plain bash, without the prefix
A custom shell quotes values like bash unless told otherwise:
shell = new Shell("powershell.exe", "-Command") { Quoting = ShellQuoting.PowerShell };
Stdout
By default, the output of a process is also written to the console: its stdout to stdout, and its stderr to stderr.
// this prints the version twice: once by the command itself, once by log
var version = await "dotnet --version";
log(version, ConsoleColor.Green);
To turn that off for every command, set quiet = true.
// Zx.quiet, default is false
quiet = true;
var version = await "dotnet --version";
log(version, ConsoleColor.Green);
To turn it off for a single command, call .Quiet(). .Quiet(false) does the opposite: it writes the output of one command while quiet is true.
var version = await run("dotnet --version").Quiet();
log(version, ConsoleColor.Green);
Result and errors
Awaiting a command returns CommandResult.
var result = await run($"dotnet --list-sdks");
int exitCode = result.ExitCode;
string stdout = result.StdOut; // lines joined by Environment.NewLine, no trailing newline
string stderr = result.StdErr;
IReadOnlyList<string> lines = result.Lines; // stdout line by line
string text = await run($"dotnet --version"); // converts to string (stdout) implicitly
var (output, error) = await run($"dotnet --info"); // deconstructs to (stdout, stderr)
A non-zero exit code throws ProcessErrorException. Output on stderr alone is not an error.
try
{
await run($"dotnet --foo");
}
catch (ProcessErrorException ex)
{
// int ex.ExitCode, IReadOnlyList<string> ex.ErrorOutput, string ex.CommandLine, CommandResult ex.Result
log(ex.Message, ConsoleColor.Red);
}
// or handle the exit code yourself
var result = await run($"robocopy {src} {dst}").NoThrow();
if (result.ExitCode >= 8) { /* ... */ }
Options
run and sh return a Command. It does not start until it is awaited, so options can be chained before that. Awaiting the same Command again runs it again.
await run($"dotnet test").Timeout(TimeSpan.FromMinutes(5));
| Method | |
|---|---|
NoThrow() |
Do not throw on a non-zero exit code. |
Quiet(), Quiet(false) |
Do not echo the output of this command to the console. It overrides Zx.quiet, so Quiet(false) echoes one command when everything else is quiet. |
Inherit() |
Do not capture: the process writes to the console directly, so colors, progress bars and prompts work. The result only has an exit code. |
Timeout(TimeSpan), Timeout(int seconds) |
Stop the process and throw TimeoutException. |
WithCancellation(CancellationToken) |
Stop the process and throw OperationCanceledException. |
GracePeriod(TimeSpan), GracePeriod(int seconds) |
How long a process that was asked to stop may take before it is killed (see Stopping a process). Default is 3 seconds. |
Cwd(string) |
Working directory of this command. |
SetEnv(string name, string? value) |
Environment variable of this command (null removes it). |
Input(string), Input(byte[]), Input(Stream) |
Write the text, the bytes or the stream to stdin of the process. |
WithEncoding(Encoding) |
Encoding of stdout/stderr, and of the text given to Input. |
ExecuteAsync(CancellationToken) |
Start it and return Task<CommandResult>. |
ToBytesAsync(CancellationToken) |
Start it and return stdout as byte[] (see Binary output). |
ToStreamAsync(Stream, CancellationToken) |
Start it and copy stdout to the stream. |
Processes do not outlive the script: a stopped command is killed with its whole process tree (a shell command is shell -> real process), and on Windows and Linux children are killed when the script itself exits or is killed.
Stopping a process
A timeout, a cancellation, or leaving an await foreach stops the process. await returns only after the process has really exited.
Where the process can be asked to stop, it is asked first and gets the grace period to finish by itself; then the process tree is killed.
terminateToken (Zx.terminateToken) is a CancellationToken built into ProcessX that handles Ctrl + C (SIGINT), Ctrl + Break (SIGQUIT) and SIGTERM.
| Situation | What happens |
|---|---|
Ctrl + C, with terminateToken |
The system has already delivered the signal to the process. ProcessX waits for the grace period, then kills. |
Timeout or cancellation of a run command, on Linux/macOS |
SIGTERM is sent. ProcessX waits for the grace period, then kills. |
| Timeout or cancellation on Windows | Killed immediately: Windows can not signal a single process. |
Timeout or cancellation of a shell command (sh, await "...") |
Killed immediately: a signaled shell would exit and leave its children running. |
// `docker compose up` stops its containers on Ctrl + C; give it time to do that
terminateTimeout = TimeSpan.FromSeconds(40);
await run($"docker compose up").WithCancellation(terminateToken).GracePeriod(30);
// never wait
await run($"dotnet watch").WithCancellation(token).GracePeriod(0);
Standard input
stdin is inherited, so a command can read from the console. Input replaces it with a text, bytes (byte[] or ReadOnlyMemory<byte>) or a stream; the text is written as it is and never appears in the command line, which makes it the way to pass a secret:
await run($"docker login -u {user} --password-stdin").Input(password);
await run($"kubectl apply -f -").Input(yaml);
await run($"git apply").Input(File.OpenRead("fix.patch"));
Pipe
| connects stdout of a command to stdin of the next one with an OS pipe. No shell is involved, so holes are still safe.
var pattern = "fix:";
var result = await (run($"git log --oneline") | run($"grep {pattern}") | run($"wc -l"));
Options of the last command apply to the pipeline. The pipeline fails when any command in it fails, and ExitCode is the last non-zero one.
Parallel
Await a tuple or a sequence to run commands at once.
var (build, lint) = await (run($"dotnet build"), sh("npm run lint"));
CommandResult[] results = await files.Select(x => run($"gzip {x}"));
// constant scripts
await new[]
{
"echo 1",
"echo 2",
"echo 3",
};
Streaming
await foreach reads stdout line by line while the process is running. Leaving the loop stops the process.
await foreach (var line in run($"docker logs -f {container}"))
{
if (line.Contains("ready")) break;
}
Binary output
Awaiting a command reads stdout as text, line by line. For a command that writes binary data, use ToBytesAsync to get stdout byte for byte, or ToStreamAsync to copy it somewhere without holding it in memory.
byte[] tar = await run($"git archive HEAD").ToBytesAsync();
await using (var file = File.Create("logo.png"))
{
await run($"curl -sL {url}").ToStreamAsync(file);
}
Everything else works the same: options, Input, pipes, and ProcessErrorException on a non-zero exit code. stderr is still read as text. ToStreamAsync returns a CommandResult with the exit code and stderr.
Command is also an IAsyncEnumerable<string>, so System.Linq works on the lines: string[] lines = await run($"...").ToArrayAsync();.
Zx
ProcessX.Zx has settings and utility functions, intended to be used via using static ProcessX.Zx;.
// Zx.quiet, do not echo stdout/stderr of commands to the console. default is false (output is echoed).
quiet = true;
// Zx.shell, the shell of `await "..."` and sh(...).
shell = Shell.Bash;
// Zx.cd(string path), change the current directory of the script (and so of commands).
cd("../../");
// Zx.which(string commandName), find a command in PATH. returns null when not found.
if (which("git") == null) throw new Exception("git is required");
// Zx.terminateToken, CancellationToken that is canceled by Ctrl + C (SIGINT), Ctrl + Break (SIGQUIT) and SIGTERM,
// so that the script can clean up, like `trap` in a shell script.
try
{
await run($"docker compose up").WithCancellation(terminateToken);
}
finally
{
await run($"docker compose down");
}
// Zx.terminateTimeout, how long the script may keep running after terminateToken is canceled. default is 5 seconds.
terminateTimeout = TimeSpan.FromSeconds(30);
// Zx.log(object? value, ConsoleColor? color) and Zx.color(ConsoleColor color)
log("red log.", ConsoleColor.Red);
using (color(ConsoleColor.Blue))
{
log("blue log");
await run($"dotnet --version"); // the output of a command is blue too
}
// Zx.question(string question), read a line from stdin.
var bear = await question("What kind of bear is best?");
// Zx.sleep(int seconds|TimeSpan timeSpan), wrapper of Task.Delay.
await sleep(5);
Without terminateToken, Ctrl + C simply ends the script and its commands. Reading terminateToken takes over the signal: the script is no longer ended immediately, the token is canceled instead, and if the script is still running after terminateTimeout the process exits with code 130. The grace period of the commands being stopped is part of that time, so raise terminateTimeout along with a long GracePeriod.
Commands inherit the environment of the script, so use the BCL for anything that applies to every command: Environment.SetEnvironmentVariable("NODE_ENV", "production"). SetEnv and Cwd are for a single command.
If you want more colors, like Chalk in JavaScript, the Cysharp/Kokuban styler for .NET console apps will help, or you can use Spectre.Console for richer styling. For command line arguments, ConsoleAppFramework works in a file-based app as well.
Analyzer
The package includes an analyzer.
| ID | Severity | |
|---|---|---|
| PX001 | Error | await on a string that is not a compile-time constant. The script goes to the shell without escaping; use run($"...") or sh($"...") to pass values. |
| PX002 | Warning | await "cd path" or sh("cd path") only changes the directory of the shell process that runs it. Use cd("path"). (cd path && command is fine.) |
| PX003 | Error | A string that is not a compile-time constant passed to sh(...). Use sh($"...{value}...") so that values are quoted, or {value:raw} to insert script text on purpose. |
using ProcessX; makes string awaitable, and that has a side effect: the compiler reports CS4014 ("this call is not awaited") for any discarded call that returns a string, such as Console.ReadLine();. The analyzer suppresses CS4014 for string and string[]. It still reports a Command that was not awaited, which is useful because a Command does nothing until it is awaited.
Without using ProcessX; strings are not awaitable at all, and using static ProcessX.Zx; alone is enough for run, sh, their options and await foreach. It is not a full replacement, though: awaiting a tuple or a sequence of commands also needs using ProcessX;, and types such as Shell and ProcessErrorException then have to be written with the namespace.
Migration from v1
For .NET Standard 2.0 and the old API, use v1. Here is the guide from v1 to v2.
- The namespace is
ProcessXinstead ofZxandCysharp.Diagnostics: replaceusing Zx;withusing ProcessX;andusing static Zx.Env;withusing static ProcessX.Zx;. - The static class
Cysharp.Diagnostics.ProcessX(StartAsync,GetDualAsyncEnumerable,StartReadBinaryAsync) is removed. Use the .NET 11ProcessAPI, or stay on v1. ProcessErrorExceptionmoved to theProcessXnamespace.AcceptableExitCodesis replaced byNoThrow().await "..."only accepts constants, andawait "cd path"no longer changes the directory; usecd(path).verboseis replaced byquietwith the opposite meaning:verbose = falsebecomesquiet = true.useShellis removed:runnever uses a shell,await "..."andshalways do.shellis aShellinstead of a string.workingDirectoryandenvVarsare removed: usecd(path)andEnvironment.SetEnvironmentVariable, orCwd/SetEnvfor a single command.fetch,fetchTextandfetchBytesare removed: useHttpClient.run($"...")passes holes as arguments instead of quoting them into a shell command line, and returns aCommandinstead ofTask<string>.
| v1 | v2 |
|---|---|
run2($"..."), process2("...") |
var (stdout, stderr) = await run($"...") |
runl($"..."), processl("...") |
(await run($"...")).Lines |
process("...") |
sh("...") for a constant, sh($"...") with values |
withTimeout($"...", 10) |
run($"...").Timeout(10) |
withCancellation($"...", token) |
run($"...").WithCancellation(token) |
ignore(run($"...")) |
run($"...").NoThrow() |
escape($"...") |
not needed |
License
This library is under the MIT License.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- No dependencies.
NuGet packages (4)
Showing the top 4 NuGet packages that depend on ProcessX:
| Package | Downloads |
|---|---|
|
EasyObject
EasyObject Library |
|
|
jcs
Package Description |
|
|
AcmeshWrapper
A modern .NET library providing a type-safe, async wrapper around acme.sh for ACME certificate management. Simplifies obtaining, renewing, and managing SSL/TLS certificates from Let's Encrypt and other ACME-compliant certificate authorities. |
|
|
CCd.Nets.NATS
Package Description |
GitHub repositories (5)
Showing the top 5 popular GitHub repositories that depend on ProcessX:
| Repository | Stars |
|---|---|
|
Tyrrrz/CliWrap
Library for interacting with command-line interfaces
|
|
|
sn4k3/NetSonar
Network pings and other utilities
|
|
|
nats-io/nats.net
Async .NET client for NATS: pub/sub, request/reply, JetStream, KV, Object Store, Services
|
|
|
Cysharp/AlterNats
An alternative high performance NATS client for .NET.
|
|
|
Cysharp/CompilerBrain
CLI Coding Agent not for Vibe-coding, for C# Expert.
|
| Version | Downloads | Last Updated |
|---|---|---|
| 2.0.0 | 89 | 11/19/2026 |
| 1.5.6 | 218,282 | 1/15/2025 |
| 1.5.5 | 149,957 | 10/18/2022 |
| 1.5.4 | 88,490 | 1/11/2022 |
| 1.5.3 | 16,220 | 10/8/2021 |
| 1.5.2 | 2,813 | 9/17/2021 |
| 1.5.1 | 1,986 | 9/17/2021 |
| 1.5.0 | 2,193 | 8/27/2021 |
| 1.4.5 | 2,067 | 8/23/2021 |
| 1.4.4 | 1,995 | 8/23/2021 |
| 1.4.3 | 1,969 | 8/22/2021 |
| 1.4.2 | 1,990 | 8/20/2021 |
| 1.4.1 | 1,962 | 8/20/2021 |
| 1.4.0 | 1,983 | 8/19/2021 |
| 1.3.0 | 13,384 | 10/16/2020 |
| 1.2.0 | 5,270 | 1/30/2020 |
| 1.1.1 | 2,118 | 1/30/2020 |
| 1.1.0 | 2,224 | 1/30/2020 |
| 1.0.2 | 2,183 | 1/29/2020 |
| 1.0.1 | 2,169 | 1/29/2020 |