CliInvoke 2.1.2

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
• CliInvoke Examples
• Contributing to CliInvoke
• Used By
• Roadmap
• License
• Acknowledgements

Features

• Clear separation of concerns between Process Configuration Builders, Process Configuration Models, and Invokers.
• Supports .NET Standard 2.0, .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‑permissive) 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

Getting started

Install the packages you need (example: implementation + DI extensions):

dotnet add package CliInvoke
dotnet add package CliInvoke.Extensions

Minimal Program.cs (console app) — registers services, builds a simple process configuration, and runs it buffered:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Core.Factories;

class Program
{
    static async Task Main()
    {
        var services = new ServiceCollection();
        services.AddCliInvoke(); // from CliInvoke.Extensions
        var provider = services.BuildServiceProvider();

        var factory = provider.GetRequiredService<IProcessConfigurationFactory>();
        var invoker = provider.GetRequiredService<IProcessConfigurationInvoker>();

        // Create a simple configuration (adjust path/args for your OS)
        var config = factory.Create("dotnet", "--info");

        // Run and get buffered output
        BufferedProcessResult result = await invoker.ExecuteBufferedAsync(config, CancellationToken.None);

        Console.WriteLine($"ExitCode: {result.ExitCode}");
        Console.WriteLine("Stdout:");
        Console.WriteLine(result.StandardOutput);
        Console.WriteLine("Stderr:");
        Console.WriteLine(result.StandardError);
    }
}

Notes

• Replace "dotnet --info" with the executable and arguments you need for your platform.
• For non‑buffered/streaming scenarios, use ExecuteAsync/ExecuteBufferedAsync variants and builder options to redirect streams instead of buffering everything in memory.

Examples

Simple ProcessConfiguration creation with Factory Pattern

This approach uses the IProcessConfigurationFactory interface factory to create a ProcessConfiguration. It requires fewer parameters and sets up more defaults for you.

It can be provided with a Action<IProcessConfigurationBuilder> configure optional parameter where greater control is desired.

Non-Buffered Execution Example

This example gets a non buffered ProcessResult that contains basic process exit code, Id, and other information.

using CliInvoke.Core.Factories;
using CliInvoke.Core;
using AlastairLundy.CliIinvoke;

using Microsoft.Extensions.DependencyInjection;

// Dependency Injection setup code omitted for clarity

// Get services 
IProcessConfigurationFactory processConfigFactory = serviceProvider.GetRequiredService<IProcessConfigurationFactory>();
IProcessConfigurationInvoker _invoker_ = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

// Simply create the process configuration.
ProcessConfiguration configuration = processConfigFactory.Create("path/to/exe", "arguments");

// Run the process configuration and get the results.
ProcessResult result = await _invoker.ExecuteAsync(configuration, CancellationToken.None);

Buffered Execution Example

This example gets a BufferedProcessResult which contains redirected Standard Output and Standard Error as strings.

using CliInvoke.Core.Factories;
using CliInvoke.Core;

using Microsoft.Extensions.DependencyInjection;

// Dependency Injection setup code omitted for clarity

// Get services 
IProcessConfigurationFactory processConfigFactory = serviceProvider.GetRequiredService<IProcessConfigurationFactory>();
IProcessConfigurationInvoker _invoker_ = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

// Simply create the process configuration.
ProcessConfiguration configuration = processConfigFactory.Create("path/to/exe", "arguments");

// Run the process configuration and get the results.
BufferedProcessResult result = await _invoker.ExecuteBufferedAsync(configuration, CancellationToken.None);

Advanced Configuration with Builders

The following examples show how to configure and build a ProcessConfiguration depending on whether Buffering the output is desired.

Non-Buffered Execution Example

This example gets a non buffered ProcessResult that contains basic process exit code, id, and other information.

using CliInvoke;
using CliInvoke.Core;

using CliInvoke.Builders;
using CliInvoke.Core.Builders;

using Microsoft.Extensions.DependencyInjection;

  //Namespace and class code ommitted for clarity 

  // ServiceProvider and Dependency Injection setup code oomittedfor clarity
  
  IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();

  // Fluently configure your Command.
  IProcessConfigurationBuilder builder = new ProcessConfigurationBuilder("Path/To/Executable")
                            .SetArguments(["arg1", "arg2"])
                            .SetWorkingDirectory("/Path/To/Directory");
  
  // Build it as a ProcessConfiguration object when you're ready to use it.
  ProcessConfiguration config = builder.Build();
  
  // Execute the process through ProcessInvoker and get the results.
ProcessResult result = await _processConfigInvoker.ExecuteAsync(config);

Buffered Execution Example

This example gets a BufferedProcessResult which contains redirected StandardOutput and StandardError as strings.

using CliInvoke;
using CliInvoke.Builders;

using CliInvoke.Core;
using CliInvoke.Core.Builders;

using Microsoft.Extensions.DependencyInjection;


  //Namespace and class code ommitted for clarity 

  // ServiceProvider and Dependency Injection setup code ommitted for clarity
  
  IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();

  // Fluently configure your Command.
  IProcessConfigurationBuilder builder = new ProcessConfigurationBuilder("Path/To/Executable")
                            .SetArguments(["arg1", "arg2"])
                            .SetWorkingDirectory("/Path/To/Directory")
                            .RedirectStandardOutput(true)
                           .RedirectStandardError(true);
  
  // Build it as a ProcessConfiguration object when you're ready to use it.
  ProcessConfiguration config = builder.Build();
  
  // Execute the process through ProcessInvoker and get the results.
BufferedProcessResult result = await _processInvoker.ExecuteBufferedAsync(config);

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 an initial set of features are available in version 1, 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

License

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

If you use CliInvoke in your project please make an exact copy of the contents of CliInvoke's LICENSE.txt file available either in your third party licenses TXT file or as a separate TXT file in the project's repository.

CliInvoke Assets

CliInvoke's Icon is proprietary with all rights reserved to me (Alastair Lundy).

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

Acknowledgements

Projects

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

• CliWrap for inspiring this project
• Polyfill for simplifying .NET Standard 2.0 support

For more information, please see the THIRD_PARTY_NOTICES file.