CliRunner 1.0.0-alpha.2

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
This is a prerelease version of CliRunner.
There is a newer prerelease version of this package available.
See the version list below for details. 
dotnet add package CliRunner --version 1.0.0-alpha.2                

                    
                

            
NuGet\Install-Package CliRunner -Version 1.0.0-alpha.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="CliRunner" Version="1.0.0-alpha.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add CliRunner --version 1.0.0-alpha.2                

                    
                

            
#r "nuget: CliRunner, 1.0.0-alpha.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install CliRunner as a Cake Addin
#addin nuget:?package=CliRunner&version=1.0.0-alpha.2&prerelease

// Install CliRunner as a Cake Tool
#tool nuget:?package=CliRunner&version=1.0.0-alpha.2&prerelease

CliRunner

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

NuGet NuGet

Features

  • Promotes the single responsibility principle and separation of concerns
  • For .NET 8 and newer TFMs CliRunner has few dependencies.
  • Compatible with .NET Standard 2.0 and 2.1 ^1
  • Dependency Injection extensions to make using it easier.
  • Support for specific specializations such as running executables or commands via Windows Powershell or CMD on Windows ^2
  • SourceLink support

^1 - Polyfill is a dependency only required for .NET Standard 2.0 and 2.1 users. Microsoft.Bcl.HashCode is a dependency only required for .NET Standard 2.0 users.

^2 - The Specialization library is distributed separately.

Why use CliRunner over CliWrap?

  • Greater separation of concerns with the Command class - Command Building, Command Running, andCommand Pipe handling are moved to separate classes.
  • Supports Dependency Injection
  • Classes and code follow the Single Responsibility Principle
  • No hidden or additional licensing terms are required beyond the source code license.
  • No imported C code - This library is entirely written in C#.
  • No lock in regarding Piping support - Use .NET's StreamWriter and StreamReader classes as inputs and outputs respectively.
  • Uses .NET's built in Process type.

Supported Platforms

This can be added to any .NET Standard 2.0, .NET Standard 2.1, .NET 8, or .NET 9 supported project.

Operating System Support Status Notes
Windows Fully Supported ✅
macOS Fully Supported ✅
Mac Catalyst Fully Supported ✅
Linux Fully Supported ✅
FreeBSD Fully Supported ✅
Android Untested Platform ⚠️ Support for this platform has not been tested but should theoretically work.
IOS Not Supported ❌ Not supported due to Process.Start() not supporting IOS. ^3
tvOS Not Supported ❌ Not supported due to Process.Start() not supporting tvOS ^3
watchOS Not Supported ❌ Not supported due to Process.Start() not supporting watchOS ^4
Browser Not Supported ❌ Not supported due to not being a valid target Platform for executing programs.

^3 - See the Process class documentation for more info.

^4 - Lack of watchOS support is implied by lack of IOS support since watchOS is based on IOS.

Note: This library has not been tested on Android or Tizen!

Installation

  • Nuget or dotnet add package CliRunner

Usage

CliRunner enables use of a fluent builder style of syntax to easily configure and run Commands.

The following example shows how to configure and build a Command that returns a BufferedCommandResult which contains redirected StandardOutput and StandardError.

using CliRunner;
using CliRunner.Builders.Abstractions;
using CliRunner.Builders;

  /// Initialize CommandRunner with Dependency Injection.
  ServiceCollection services = new ServiceCollection();
  services.UseCliRunner();

  ServiceProvider sp = services.Build();
  ICommandRunner _commandRunner = sp.GetService<ICommandRunner>();

  // Build your Command fluently 
  ICommandBuilder builder = new CommandBuilder("Path/To/Executable")
                            .WithArguments(["arg1", "arg2"])
                            .WithWorkingDirectory("/Path/To/Directory");
  
  Command command = builder.Build();
  
var result = await _commandRunner.ExecuteBufferedAsync(command);

License

CliRunner is licensed under the MPL 2.0 license. If you modify any of CliRunner's files then the modified files must be licensed under the MPL 2.0 .

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

Acknowledgements

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

  • CliWrap for inspiring this project
  • Polyfill for simplifying .NET Standard 2.0 & 2.1 support
  • Microsoft.Bcl.HashCode for providing a backport of the HashCode class and static methods to .NET Standard 2.0

For more information please see the THIRD_PARTY_NOTICES file.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on CliRunner:

Package Downloads
PlatformKit

Cross-platform Operating System Detection, Operating System Version Detection, Apple Silicon Mac Detection, programmatic .NET Runtime ID Generation, and more. For a full list of features please visit: https://github.com/alastairlundy/PlatformKit/blob/main/docs/FeatureComparisonByPlatform.md
CliRunner.Specializations

CliRunner Specializations is a library for providing Specializations of CliRunner's Commands.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-alpha.3 0 2/10/2025
1.0.0-alpha.2 35 2/9/2025
1.0.0-alpha.1 13 2/6/2025

## Changes since 1.0.0 Alpha 1

### Breaking Changes
* Moved ``ICommandBuilder`` to the ``CliRunner.Builders.Abstractions`` namespace (and corresponding folder) from ``CliRunner.Abstractions`` namespace.
* Renamed ``ICommandBuilder`` and ``CommandBuilder``  ``WithCredentials`` builder method to ``WithCredential``
* Renamed ``Credentials`` property name to ``Credential`` in relevant classes
* Changed ``ArgumentsBuilder`` methods to return ``IArgumentsBuilder`` instead of ``ArgumentsBuilder``
* Changed ``EnvironmentVariablesBuilder`` methods to return ``IEnvironmentVariablesBuilder`` instead of ``EnvironmentVariablesBuilder``
* Removed ``WithArgumentValidation`` method from  ``ArgumentsBuilder`` - Argument Validation must now be set when instantiating the ``ArgumentsBuilder``.
* Renamed ``Escape`` static ``ArgumentsBuilder`` method to ``EscapeSpecialChars``
* Removed builder interfaces from dependency injection extension method since it's setup is unnecessary.

### Non-breaking Changes
* Added ``IArgumentsBuilder`` interface that ``ArgumentsBuilder`` now inherits from - No new methods have been added to ``ArgumentsBuilder``.
* Added ``IEnvironmentVariablesBuilder`` interface that ``EnvironmentVariablesBuilder`` now inherits from - No new methods have been added to ``EnvironmentVariablesBuilder``
* Simplified OS Polyfill usage code
* Added ``AddUserCredential`` ProcessStartInfo and Process extension methods - This is now used within ``ProcessCreator`` to pass a UserCredential to the process start info if it is not null
* Renamed parameters in ``ArgumentsBuilder`` regarding escaping special characters

### Bug Fixes
* Fixed an issue where a ``UserCredential`` wasn't loaded by ``ProcessCreator`` if ``LoadUserProfile`` was set to false.
* Fixed an issue where Argument Validation logic wasn't passed as a parameter in returned new ``ArgumentsBuilder`` instances in builder methods.