https://github.com/alastairlundy/clirunner
CliRunner is a .NET Library for interacting with Command Line Interfaces, CliRunner is a library for interacting with Command Line Interfaces and wrapping around executables.
https://github.com/alastairlundy/clirunner
cli csharp-library dotnet process shell
Last synced: 4 months ago
JSON representation
CliRunner is a .NET Library for interacting with Command Line Interfaces, CliRunner is a library for interacting with Command Line Interfaces and wrapping around executables.
- Host: GitHub
- URL: https://github.com/alastairlundy/clirunner
- Owner: alastairlundy
- License: mpl-2.0
- Created: 2024-09-29T12:57:16.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-01-29T16:21:21.000Z (5 months ago)
- Last Synced: 2025-01-29T17:19:53.504Z (5 months ago)
- Topics: cli, csharp-library, dotnet, process, shell
- Language: C#
- Homepage:
- Size: 479 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Security: SECURITY.md
Awesome Lists containing this project
README
# CliRunner
CliRunner is a library for interacting with Command Line Interfaces and wrapping around executables.
[](https://www.nuget.org/packages/CliRunner/)
[](https://www.nuget.org/packages/CliRunner/)
## 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](https://learn.microsoft.com/en-us/dotnet/standard/library-guidance/sourcelink) support
^1 - [Polyfill](https://github.com/SimonCropp/Polyfill) is a dependency only required for .NET Standard 2.0 and 2.1 users. [Microsoft.Bcl.HashCode](https://www.nuget.org/packages/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](https://github.com/Tyrrrz/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 :white_check_mark: | |
| macOS | Fully Supported :white_check_mark: | |
| Mac Catalyst | Fully Supported :white_check_mark: | |
| Linux | Fully Supported :white_check_mark: | |
| FreeBSD | Fully Supported :white_check_mark: | |
| Android | Untested Platform :warning: | Support for this platform has not been tested but should theoretically work. |
| IOS | Not Supported :x: | Not supported due to ``Process.Start()`` not supporting IOS. ^3 |
| tvOS | Not Supported :x: | Not supported due to ``Process.Start()`` not supporting tvOS ^3 |
| watchOS | Not Supported :x: | Not supported due to ``Process.Start()`` not supporting watchOS ^4 |
| Browser | Not Supported :x: | Not supported due to not being a valid target Platform for executing programs. |
^3 - See the [Process class documentation](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process.start?view=net-9.0#system-diagnostics-process-start) for more info.
^4 - Lack of watchOS support is implied by lack of IOS support since [watchOS is based on IOS](https://en.wikipedia.org/wiki/WatchOS).
**Note:** This library has not been tested on Android or Tizen!
## Installation
* [Nuget](https://nuget.org/packages/) 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.
```csharp
using CliRunner;
using CliRunner.Builders;
using CliRunner.Extensions;
/// Initialize CommandRunner with Dependency Injection.
ServiceCollection services = new ServiceCollection();
services.UseCliRunner();
ServiceProvider sp = services.Build();
ICommandRunner _commandRunner = sp.GetService();
// Build your Command fluently
ICommandBuilder builder = new CommandBuilder("Path/To/Executable")
.WithArguments(["arg1", "arg2"])
.WithWorkingDirectory("/Path/To/Directory");
Command command = builder.ToCommand();
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](https://github.com/Tyrrrz/CliWrap/) for inspiring this project
* [Polyfill](https://github.com/SimonCropp/Polyfill) for simplifying .NET Standard 2.0 & 2.1 support
For more information please see the [THIRD_PARTY_NOTICES file](https://github.com/alastairlundy/CliRunner/blob/main/THIRD_PARTY_NOTICES.txt).