CliInvoke

CliInvoke is a .NET library for running and interacting with external command-line processes. It is built for .NET developers who need to launch an executable, redirect its standard streams, capture its output, and reason about its lifetime — without hand-rolling System.Diagnostics.Process for every project.

What CliInvoke is

Every .NET codebase that shells out to another tool eventually needs the same things: a way to describe the command, a way to start it, a way to capture its output, a way to dispose of its handles, and a way to test the code that does all of that. System.Diagnostics.Process provides the primitives; the boilerplate — pipe setup, output buffering, exit-code handling, disposal, thread-safety, cross-platform path lookup — is left to you. CliInvoke provides the layer on top.

The library targets .NET 10, runs on Windows, macOS, Linux, and BSD, and ships with first-class dependency-integration helpers (AddCliInvoke, namespace CliInvoke.Extensions) in the CliInvoke package.

What it offers

CliInvoke exposes three invocation patterns that cover the spectrum from scripting to long-running process control:

  • CliRun — a static façade for one-line command execution. The right entry point when you just need to run a command and read its output.
  • IProcessInvoker — an interface for DI-centric applications. Takes a ProcessConfiguration and returns a typed result, with full support for test doubles and per-call configuration.
  • IExternalProcess — a power-user API for granular lifecycle control. Splits start, capture, and kill into separate calls so you can interact with the process while it runs.

Underneath those patterns sit the capabilities that make the library practical to use day-to-day:

  • Configuration builders and models — fluent builders assemble immutable ProcessConfiguration and ProcessExitConfiguration models with sensible defaults. See the Configuration guide for the full reference.
  • Resource disposal — three Resource-Owning Types own every unmanaged handle and SecureString buffer; the Resource Disposal guide documents the disposal contract for each one.
  • Cross-platform support — Windows, macOS, Linux, and BSD with consistent behaviour; see Supported Operating Systems.
  • Dependency-injection extensions — AddCliInvoke() registers the invoker, factory, and file-path resolver with the container of your choice. See Getting Started.
  • Specializations — first-class wrappers for running commands through PowerShell or CMD on Windows via CliInvoke.Specializations.

If you are unsure which pattern fits your scenario, the Choosing your Invocation Pattern guide walks through the decision tree and the trade-offs of each option.

Where to go next

Different readers arrive here with different needs. Pick the path that matches yours and follow it in order.

If you are new to CliInvoke

Start with a runnable example, then read the pattern-decision guide.

  1. Quickstart — install the package and run your first CliRun command in under five minutes.
  2. Choosing your Invocation Pattern — the decision tree for picking between CliRun, IProcessInvoker, and IExternalProcess.
  3. Configuration — every knob on ProcessConfiguration and ProcessExitConfiguration.

If you are building a testable app with DI

You work in a codebase that uses dependency injection and you need to unit-test code that shells out to processes.

  1. Getting Started — register IProcessInvoker with your DI container.
  2. Choosing your Invocation Pattern — confirm IProcessInvoker is the right pattern for your scenario.
  3. Configuration — the ProcessConfiguration model, the builder lifecycle, and the default-value reference appendix.

If you need full lifecycle control

You need to interact with the process while it runs — pipe input, monitor output, send signals, or replace components for advanced scenarios.

  1. Choosing your Invocation Pattern — when and how to use the IExternalProcess factory and lifecycle API.
  2. Architecture — the internal data-flow and the Process Invocation Pipeline so you can reason about where a customisation belongs.
  3. Resource Disposal — the disposal contract for the three Resource-Owning Types, including IExternalProcess.

If you have a specific task

If you know what you need to accomplish but not which page it lives on, jump straight to the relevant guide.

I want to … Go to
Debug a leak, hang, or wrong exit code Troubleshooting
Tune how a process starts or exits Configuration
Understand the internal data-flow Architecture
Pick between CliRun, IProcessInvoker, and IExternalProcess Choosing your Invocation Pattern
Dispose the Resource-Owning Types correctly Resource Disposal
Install and set up the library Getting Started · Quickstart
Look up a specific API API Reference

For a flat index of every page, see the Documentation hub.