1. Home
2. Docs
3. Getting Started

Getting Started

New to CliInvoke? Start with CliRun. It is the recommended default entry point — zero boilerplate, no dependency injection required. Use IProcessInvoker when you need DI or middleware, and IExternalProcess when you need process-level control. See DESIGN_PATTERNS.md for a Which pattern should I use? decision tree.

Installing CliInvoke

The main way to install CliInvoke is using nuget directly or through your IDE or Code Editor of choice.

Versions

Stable Versions

Where possible you should always use a stable version of CliInvoke and update to the latest minor CliInvoke update within the Major.Minor.Build scheme.

Pre-release Versions

Versions starting with 0. or ending with -alpha., -beta., or -rc. are pre-release versions and may not be as stable or bug-free as stable releases.

When configuring Nuget setup in your .csproj file, staying within a major version of CliInvoke is recommended.

Setting up CliInvoke

Dependency Injection

There are 2 main ways of setting up CliInvoke with dependency injection: manually, and using CliInvoke's AddCliInvoke configuration extension method (namespace CliInvoke.Extensions), which ships in the CliInvoke package.

Using AddCliInvoke

For this approach you'll need the CliInvoke nuget package.

If your project doesn't already use Dependency Injection, you can set it up as follows:

using Microsoft.Extensions.DependencyInjection;

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Extensions;

namespace MyApp;

class Program
{
    internal static ServiceProvider ServiceProvider;

    static void Main(string[] args)
    {
        // Create the service collection
        var services = new ServiceCollection();

        // Register your other dependencies here

        // AddCliInvoke registers IProcessInvoker, IExternalProcessFactory,
        // IProcessConfigurationBuilder, and related services.
        services.AddCliInvoke();

        // Build the service provider
        ServiceProvider = services.BuildServiceProvider();

        // Your other code goes here
    }
}

You can also configure the middleware pipeline when registering:

services.AddCliInvoke(builder => builder.UseMiddleware<LoggingMiddleware>());

If you use the CliInvoke.Specializations package's UsePowerShell()/UseCmd() middleware, also call AddCliInvokeSpecializations() (same namespace) with the same ServiceLifetime so those middleware types resolve from the container.

Manual Setup

This example manually registers IProcessInvoker and the other core CliInvoke services as Singletons.

Most developers using CliInvoke in their applications should use the AddCliInvoke method instead of manually configuring Dependency Injection unless there is a good reason to avoid it.

using Microsoft.Extensions.DependencyInjection;

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

namespace MyApp;

class Program
{
    internal static ServiceProvider ServiceProvider;

    static void Main(string[] args)
    {
        // Create the service collection
        var services = new ServiceCollection();

        // Register your other dependencies here

        services.AddSingleton<IFilePathResolver, FilePathResolver>();
        services.AddSingleton<IProcessConfigurationBuilder, ProcessConfigurationBuilder>();
        services.AddSingleton<IExternalProcessFactory, ExternalProcessFactory>();
        services.AddSingleton<IProcessInvoker, ProcessInvoker>();
        services.AddSingleton<IShellDetector, ShellDetector>();

        // Build the service provider
        ServiceProvider = services.BuildServiceProvider();

        // Your other code goes here
    }
}

Custom Middleware

You can write your own middleware that runs as part of the IProcessInvoker pipeline. Middleware implements IProcessMiddleware (in CliInvoke.Core.Middleware) and receives an InvocationContext plus the next delegate:

using CliInvoke.Core.Middleware;

public class LoggingMiddleware : IProcessMiddleware
{
    public Task InvokeAsync(InvocationContext context, Func<InvocationContext, Task> next)
    {
        // inspect or modify context.Configuration here
        return next(context);
    }
}

Register it with AddCliInvoke as shown above.

Example Usage

Here are some simple examples of using CliInvoke. For more detailed examples, see the wiki page.

Basic run

using CliInvoke;
using CliInvoke.Core;

ProcessConfiguration configuration = new ProcessConfiguration("dotnet", "--version");
ProcessResult result = await CliRun.RunAsync(configuration, ProcessExitConfiguration.CreateGraceful());
Console.WriteLine($"Exit code: {result.ExitCode}");

Capture output

using CliInvoke;
using CliInvoke.Core;

ProcessConfiguration configuration = new ProcessConfiguration("dotnet", "--version");
BufferedProcessResult result = await CliRun.RunBufferedAsync(configuration, ProcessExitConfiguration.CreateGraceful());
Console.WriteLine(result.StandardOutput);

Using Dependency Injection

using Microsoft.Extensions.DependencyInjection;

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Extensions;

ServiceCollection services = new();
services.AddCliInvoke();
ServiceProvider provider = services.BuildServiceProvider();
IProcessInvoker invoker = provider.GetRequiredService<IProcessInvoker>();

ProcessConfiguration config = new("dotnet", "--version");
BufferedProcessResult result = await invoker.ExecuteBufferedAsync(config, ProcessExitConfiguration.CreateGraceful());
Console.WriteLine(result.StandardOutput);

Bypassing middleware with IExternalProcess

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

IExternalProcessFactory factory = provider.GetRequiredService<IExternalProcessFactory>();
ProcessConfiguration config = new ProcessConfiguration("dotnet", "--version");
using IExternalProcess process = factory.CreateExternalProcess(config);
await process.StartAsync(CancellationToken.None);
ProcessResult result = await process.WaitForExitOrTimeoutAsync(CancellationToken.None);

Fire-and-forget

using CliInvoke;

int processId = CliRun.FireAndForget("dotnet", "build");

Specializations (PowerShell / Cmd)

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Specializations.Configurations;

using PowershellProcessConfiguration config = new PowershellProcessConfiguration("-Command Get-Process");
BufferedProcessResult result = await CliRun.RunBufferedAsync(config, ProcessExitConfiguration.CreateGraceful());

You can also route invocations through PowerShell or Cmd using the UsePowerShell() / UseCmd() middleware extensions. To wrap only some invocations (for example, only .ps1 files) while others run directly, see Wrapping only some invocations in a shell in the middleware guide.