TimeWarp.Cli 0.6.0-beta4

<img src="https://raw.githubusercontent.com/TimeWarpEngineering/timewarpengineering.github.io/refs/heads/master/images/LogoNoMarginNoShadow.svg" alt="logo" height="120" style="float: right" />

TimeWarp.Cli

TimeWarp.Cli is a fluent API wrapper around CliWrap for elegant C# scripting. The library makes shell command execution feel natural and concise in C#, providing a simple static Run() method with async operations and graceful error handling.

Designed specifically for scripting scenarios, TimeWarp.Cli emphasizes simplicity and reliability, allowing developers to write shell-like command sequences with the power and safety of C#'s type system.

Give a Star! ⭐

If you find this project useful, please give it a star. Thanks!

Quick Start

#!/usr/bin/dotnet run
#:package TimeWarp.Cli

using TimeWarp.Cli;

// Get command output as string
var date = await Run("date").GetStringAsync();
Console.WriteLine($"Current date: {date}");

// Process output line by line
var files = await Run("find", ".", "-name", "*.cs").GetLinesAsync();
foreach (var file in files)
{
    Console.WriteLine($"Found: {file}");
}

// Execute without capturing output
await Run("echo", "Hello World").ExecuteAsync();

// Chain commands with pipelines
var filteredFiles = await Run("find", ".", "-name", "*.cs")
    .Pipe("grep", "async")
    .GetLinesAsync();

// Use caching for expensive operations
var files = Run("find", "/large/dir", "-name", "*.log").Cached();
var errors = await files.Pipe("grep", "ERROR").GetLinesAsync();
var warnings = await files.Pipe("grep", "WARN").GetLinesAsync();
// Only one expensive find operation executed!

Installation

dotnet add package TimeWarp.Cli

Or reference in your C# script:

#:package TimeWarp.Cli

Check out the latest NuGet package: TimeWarp.Cli

Key Features

• Simple Static API: Global Run() method for immediate access
• Fluent Interface: Chain operations naturally with .Pipe(), .Cached(), etc.
• Async-First Design: All operations support modern async/await patterns
• Graceful Error Handling: Failed commands return empty results instead of throwing exceptions
• Pipeline Support: Chain commands with Unix-like pipe semantics
• Opt-in Caching: Cache expensive command results with .Cached() method
• Configuration Options: Working directory, environment variables, and more
• Cancellation Support: Full CancellationToken support for timeouts and manual cancellation
• Cross-Platform: Works on Windows, Linux, and macOS

Architecture

TimeWarp.Cli is built on several key architectural principles:

• Static Entry Point: Minimal ceremony with global Run() method
• Immutable Design: Thread-safe, readonly objects throughout
• Integration Testing: Real command validation over mocking
• Graceful Failure Philosophy: Predictable behavior in error scenarios
• Opt-in Complexity: Advanced features available when needed

See our Architectural Decision Records for detailed design rationale.

Documentation

• CLAUDE.md - Complete API reference and usage guide
• CommandExtensions.md - Static API documentation
• CommandResult.md - Fluent interface documentation
• Architectural Decisions - Design rationale and decisions

Example Scripts

See Spikes/CsScripts/ for example scripts demonstrating TimeWarp.Cli usage patterns.

Unlicense

This project is licensed under the Unlicense.

Contributing

Your contributions are welcome! Before starting any work, please open a discussion.

See our Kanban board for current development tasks and priorities.

Contact

If you have an issue and don't receive a timely response, feel free to reach out on our Discord server.