dysh 0.1.0

dysh

Dynamic shell command execution for .NET — invoke shell commands as if they were native C# methods.

dysh is a C# library that leverages the .NET Dynamic Language Runtime (DLR) to let you execute shell commands with a fluent, natural syntax — inspired by Python's sh library. It is the spiritual successor to manojlds/cmd, rebuilt for modern .NET with async-first design and cross-platform shell abstraction.

dynamic shell = Shell.Create();

// Run a command
CommandResult result = await shell.git("status");

// Subcommands
CommandResult log = await shell.git.log(n: 10, oneline: true);

// Stream output in real time
await foreach (var line in shell.docker.logs(f: true, "my-container"))
    Console.WriteLine(line);

Features

• DLR-powered syntax — any shell command becomes a C# method call via dynamic
• Async-first — all executions return Task<CommandResult> or IAsyncEnumerable<string>
• Cross-platform shell abstraction — auto-detects the appropriate shell (bash, pwsh, cmd.exe)
• Subcommand chaining — shell.git.log() maps naturally to git log
• Named argument mapping — single-char named args map to -f, multi-char to --flag
• Structured results — exit code, stdout, stderr, and elapsed time in one object
• CancellationToken support — full async cancellation throughout
• Scoped execution — set working directory and environment variables per instance

Installation

dotnet add package dysh

Getting Started

Basic usage

using Dysh;

dynamic shell = Shell.Create();

CommandResult result = await shell.git("status");

if (result.Success)
    Console.WriteLine(result.StandardOutput);
else
    Console.WriteLine(result.StandardError);

Subcommands

// Equivalent to: git log --oneline -n 10
CommandResult log = await shell.git.log(n: 10, oneline: true);

Argument mapping

// Positional args → passed as-is
await shell.ls("/home/user");

// Single-char named arg → -v
await shell.tar(x: true, z: true, f: "archive.tar.gz");
// → tar -x -z -f archive.tar.gz

// Multi-char named arg → --output
await shell.ffmpeg(input: "video.mp4", output: "out.mp4");
// → ffmpeg --input video.mp4 --output out.mp4

Streaming output

// Stream stdout line by line as it's produced
await foreach (var line in shell.ping("8.8.8.8", c: 4))
    Console.WriteLine(line);

Scoped shell with options

dynamic scoped = Shell.Create(options => options
    .WithWorkingDirectory("/var/app")
    .WithEnvironmentVariable("NODE_ENV", "production")
    .WithShell(ShellKind.Bash));

await scoped.npm("install");
await scoped.npm.run("build");

Error handling

// Check manually
var result = await shell.git("push");
if (!result.Success)
    Console.Error.WriteLine($"Exit {result.ExitCode}: {result.StandardError}");

// Or throw on failure
await shell.git("push").EnsureSuccess();

Shell Support

The default Native adapter resolves to bash on Linux/macOS and cmd.exe on Windows. You can always override this explicitly via ShellOptions.

How it works

dysh implements DynamicObject and overrides TryInvokeMember and TryGetMember to intercept method calls at runtime via the DLR. Each call is translated into a CommandDescriptor — a structured representation of the executable, subcommands, arguments, and environment — which is then handed off to an IShellAdapter for execution via System.Diagnostics.Process.

dynamic shell.git.log(n: 10)
        │
        ▼
  TryGetMember("git")       → SubcommandProxy("git")
        │
        ▼
  TryInvokeMember("log")    → CommandDescriptor { Executable="git", Subcommand="log", Args=["-n","10"] }
        │
        ▼
  IShellAdapter.ExecuteAsync(descriptor)
        │
        ▼
  ProcessRunner             → System.Diagnostics.Process
        │
        ▼
  CommandResult { ExitCode, StandardOutput, StandardError, Elapsed }

Acknowledgements

dysh is the spiritual successor to manojlds/cmd and draws inspiration from Python's sh. The original cmd library was a creative showcase of the C# DLR — dysh aims to carry that spirit forward as a maintained, production-grade library.

License

MIT © dysh contributors