CliInvoke 3.0.0-alpha.6

CliInvoke

<img src="https://github.com/alastairlundy/CliInvoke/blob/main/.assets/icon.png" width="192" height="192" alt="CliInvoke Logo">

CliInvoke is a .NET library for interacting with Command Line Interfaces and wrapping around executables.

Launch processes, redirect standard input and output streams, await process completion, and much more.

Table of Contents

• Features
• Comparison vs Alternatives
• Installing CliInvoke
  • Supported Platforms
• Examples
• Resource Disposal
• Documentation
• Contributing to CliInvoke
• Used By
• Roadmap
• License
• Acknowledgements

Features

• Clear separation of concerns between Process Configuration Builders, Process Configuration Models, and Invokers.
• Supports .NET 8 and newer TFMs and has few dependencies.
• Has Dependency Injection extensions to make using it a breeze.
• Support for specific specializations such as running executables or commands via Windows PowerShell or CMD on Windows ¹
• SourceLink support

¹ Specializations library distributed separately.

Comparison vs Alternatives

Notes:

• *Indicates not explicitly advertised for all listed OSes but may work in practice; check each project's docs.
• The CliWrap repository includes a test project that references a source‑available (non‑open source) library; that library is used for tests and is not distributed with the runtime package. The repo also contains an informal "Terms of Use" statement — review repository files if legal certainty is required.

Installing CliInvoke

CliInvoke is available on the NuGet Gallery but call be also installed via the dotnet SDK CLI.

The package(s) to install depends on your use case:

• For use in a .NET library – Install the abstractions package, your developer users can install the Implementation and Dependency Injection packages.
• For use in a .NET app – Install the implementation package and the Dependency Injection Extensions Package

Links to packages

CliInvoke.Core Nuget CliInvoke Nuget CliInvoke.Extensions Nuget CliInvoke.Specializations Nuget

Supported Platforms

CliInvoke supports Windows, macOS, Linux, FreeBSD, Android, and potentially some other operating systems.

For more details see the list of supported platforms

Design Patterns & When to Use Them

CliInvoke provides three distinct design patterns for invoking processes. See PATTERNS.md for comprehensive documentation on each pattern.

• CliRun – Beginner-friendly/quickstart entrypoint. Use for basic scripting, CI/CD tasks, or simple command execution. Zero boilerplate, optional arguments with sensible defaults.
• IProcessInvoker – DI-centric pattern and support for end-to-end process management. Use when building applications that need testability, dependency injection integration, or custom process configuration per invocation.
• IExternalProcess & IExternalProcessFactory – Process-like API with DI support, rich capability, stable and predictable behaviour. Use when you need granular lifecycle control, manual start/stop sequences, or power-user scenarios similar to System.Diagnostics.Process.

Examples

Beginner Friendly / Quickstart

For simple use cases, the CliRun helper provides a straightforward API to execute commands with minimal boilerplate:

using CliInvoke;
using CliInvoke.Core;

// Execute a command and get the result
ProcessResult result = await CliRun.RunAsync("dotnet", "--version");
Console.WriteLine($"Exit Code: {result.ExitCode}");

For capturing output, use RunBufferedAsync:

using CliInvoke;
using CliInvoke.Core;

// Execute and capture stdout/stderr
BufferedProcessResult result = await CliRun.RunBufferedAsync("dotnet", "--info");
Console.WriteLine(result.StandardOutput);
Console.WriteLine(result.StandardError);

CliRun is ideal for scripting, quick prototypes, and basic command execution where you don't need dependency injection or advanced configuration.

For detailed documentation on all available patterns and when to use them, see PATTERNS.md.

Advanced Configuration

For fine-grained control over process execution — custom timeouts, cancellation strategies, buffered vs. non-buffered output, and builder-based configuration — see the Configuration Guide and the Choosing your Invocation Pattern guide in the documentation portal.

Resource Disposal

For the full disposal reference — ownership rules, disposal patterns, and a checklist — see the Resource Disposal Guide.

Documentation

Full documentation is available in the CliInvoke Developer Portal. Pick the path that fits you:

Other guides: Troubleshooting · Migration Guides · Building from Source

How to Build CliInvoke's code

Please see building-cliinvoke.md for how to build CliInvoke from source.

How to Contribute to CliInvoke

Please see the CONTRIBUTING.md file for code and localization contributions.

If you want to file a bug report or suggest a potential feature to add, please check out the GitHub issues page to see if a similar or identical issue is already open. If there isn't already a relevant issue filed, please file one here and follow the respective guidance from the appropriate issue template.

Used By

CliInvoke is used by these projects:

• WCountLib.Providers.wc – Implements WCountLib.Abstractions using the Unix wc command.

Want your project added to this list? Open an issue

CliInvoke's Roadmap

CliInvoke aims to make working with Commands and external processes easier.

Whilst there is a modest set of features are available today, there is room for more features and for modifications of existing features in future updates.

Future updates may focus on one or more of the following:

• Improved ease of use
• Improved stability
• New features
• Enhancing existing features

New vs Old Package and Namespace

CliInvoke changed it's Nuget package Id and namespace starting from the re-release of 2.0.0 (tagged as 2.0.0-v2) and has since been published directly under the CliInvoke package ID prefix and namespace.

The previous packages Ids are marked as deprecated and will not receive future updates.

License

CliInvoke is licensed under the MPL 2.0 license. You can learn more about it here

Should your project incorporate CliInvoke, ensure that the full text of CliInvoke's LICENSE.txt is either incorporated into your third-party licenses TXT file or provided as a distinct TXT file within your project's repository.

CliInvoke Assets

CliInvoke's Icon is owned by and has all rights reserved to me (Alastair Lundy).

If you fork CliInvoke and re-distribute it, please replace the icon unless you have prior written approval from me.

Star History

<a href="https://www.star-history.com/?repos=alastairlundy%2Fcliinvoke&type=date&logscale=&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=alastairlundy/cliinvoke&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=alastairlundy/cliinvoke&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=alastairlundy/cliinvoke&type=date&legend=top-left" /> </picture> </a>

Acknowledgements

Projects

This project would like to thank the following projects for their work:

• CliWrap for inspiring this project
• Polyfill for simplifying older TFM support

For more information, please see the THIRD_PARTY_NOTICES file.