If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tyrrrz/CliWrap shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6d ago
• 4 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tyrrrz/CliWrap repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tyrrrz/CliWrap.

What it runs against: a local clone of Tyrrrz/CliWrap — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tyrrrz/CliWrap | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch prime exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tyrrrz/CliWrap. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tyrrrz/CliWrap.git
#   cd CliWrap
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tyrrrz/CliWrap and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tyrrrz/CliWrap(\\.git)?\\b" \\
  && ok "origin remote is Tyrrrz/CliWrap" \\
  || miss "origin remote is not Tyrrrz/CliWrap (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify prime >/dev/null 2>&1 \\
  && ok "default branch prime exists" \\
  || miss "default branch prime no longer exists"

# 4. Critical files exist
test -f "CliWrap/Command.cs" \\
  && ok "CliWrap/Command.cs" \\
  || miss "missing critical file: CliWrap/Command.cs"
test -f "CliWrap/Command.Execution.cs" \\
  && ok "CliWrap/Command.Execution.cs" \\
  || miss "missing critical file: CliWrap/Command.Execution.cs"
test -f "CliWrap/CommandTask.cs" \\
  && ok "CliWrap/CommandTask.cs" \\
  || miss "missing critical file: CliWrap/CommandTask.cs"
test -f "CliWrap/PipeSource.cs" \\
  && ok "CliWrap/PipeSource.cs" \\
  || miss "missing critical file: CliWrap/PipeSource.cs"
test -f "CliWrap/PipeTarget.cs" \\
  && ok "CliWrap/PipeTarget.cs" \\
  || miss "missing critical file: CliWrap/PipeTarget.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tyrrrz/CliWrap"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

CliWrap is a .NET Standard library that provides a fluent, async-first abstraction over System.Diagnostics.Process for spawning and interacting with command-line applications. It handles process launching, stdin/stdout/stderr redirection, piping between streams, cancellation with interrupt signals, and provides safety against deadlock scenarios—all with strict immutability and zero external dependencies. Clean separation of concerns: Core library lives in CliWrap/ (not shown in file list but inferred), benchmarks in CliWrap.Benchmarks/, unit tests in CliWrap.Tests/, a dummy CLI tool in CliWrap.Tests.Dummy/ for testing execution, and CliWrap.Signaler/ for platform-specific process signaling. Tests are organized by feature (BufferingSpecs.cs, PipingSpecs.cs, EventStreamSpecs.cs) not by layer.

.NET developers (C# primarily) who need to programmatically execute CLI tools, shell commands, or external processes from within their applications. Common use cases: DevOps automation tools, build system wrappers, testing frameworks that spawn subprocesses, or any application that needs reliable inter-process communication.

Production-ready and actively maintained. The repository shows a mature CI/CD setup (GitHub Actions main.yml), comprehensive test suite (CliWrap.Tests with specs for buffering, piping, cancellation, environment, credentials), and targets multiple frameworks (.NET Standard 2.0+, Framework 4.6.2+). The project uses semantic versioning on NuGet and includes benchmarking infrastructure, indicating stability-focused development.

Low risk for most use cases. Single maintainer (Tyrrrz) is a known .NET OSS contributor, but repo has strong test coverage and no external dependencies to break. The main risk is platform-specific process handling edge cases on Windows/Linux/macOS—mitigated by tests across all three platforms. No visible breaking changes in active development based on structure.

The repo is on the 'prime' branch indicating a major version. Recent activity includes benchmarking work (multiple benchmark suites for piping, buffering, event streams), test coverage expansion (specs for credentials, line breaks, path resolution), and likely refinement of the event stream API based on EventStreamSpecs.cs presence. GitHub Actions workflow suggests continuous integration is active.

git clone https://github.com/Tyrrrz/CliWrap.git
cd CliWrap
dotnet build
dotnet test

For running benchmarks: dotnet run --project CliWrap.Benchmarks

Daily commands: This is a library, not an application. To use it: dotnet add package CliWrap in a consuming project. To develop locally: dotnet build to compile, dotnet test to run the test suite. Benchmarks run via dotnet run --project CliWrap.Benchmarks -- [benchmark-name].

• CliWrap/Command.cs — Core Command class that serves as the primary API entry point for configuring and executing CLI operations
• CliWrap/Command.Execution.cs — Execution logic implementation that handles process spawning, stream management, and result collection
• CliWrap/CommandTask.cs — Async task wrapper that manages command execution lifecycle and cancellation semantics
• CliWrap/PipeSource.cs — Abstraction for input piping sources; critical for understanding data flow into processes
• CliWrap/PipeTarget.cs — Abstraction for output piping targets; essential for capturing and redirecting process output
• CliWrap/Command.PipeOperators.cs — Fluent operator overloads (| and >) that define the library's distinctive piping syntax
• CliWrap/Buffered/BufferedCommandExtensions.cs — High-level convenience methods for buffering entire stdout/stderr output in memory

Create a new test helper command

1. Add a new command class in CliWrap.Tests.Dummy/Commands/ inheriting from ICommand (CliWrap.Tests.Dummy/Commands/DefaultCommand.cs)
2. Implement Execute method to handle command logic and output handling (CliWrap.Tests.Dummy/Commands/Shared/OutputTargetExtensions.cs)
3. Register the command in the Program.cs command router (CliWrap.Tests.Dummy/Program.cs)

Add a new pipe source or target type

1. Create static factory methods in PipeSource or PipeTarget for your new input/output type (CliWrap/PipeSource.cs)
2. Implement internal providers that implement the Pipe*Provider interfaces (CliWrap/PipeTarget.cs)
3. Add corresponding test spec in CliWrap.Tests to verify piping behavior (CliWrap.Tests/PipingSpecs.cs)

Add a new builder or fluent configuration option

1. Extend the Command class with a new With* method to accept configuration (CliWrap/Command.cs)
2. Store the configuration in ICommandConfiguration and implement in Command.Execution.cs (CliWrap/ICommandConfiguration.cs)
3. Apply the configuration in Command.Execution.cs before process spawning (CliWrap/Command.Execution.cs)
4. Write integration tests in CliWrap.Tests/ConfigurationSpecs.cs (CliWrap.Tests/ConfigurationSpecs.cs)

Add a new event stream feature

1. Define new event types inheriting from CommandEvent (CliWrap/EventStream/CommandEvent.cs)
2. Create extension methods in PullEventStreamCommandExtensions or PushEventStreamCommandExtensions (CliWrap/EventStream/PullEventStreamCommandExtensions.cs)
3. Wire event emission into Command.Execution.cs stream processing loop (CliWrap/Command.Execution.cs)
4. Add test cases in CliWrap.Tests/EventStreamSpecs.cs (CliWrap.Tests/EventStreamSpecs.cs)

• .NET / C# — Cross-platform CLI automation requires strong async/await support and managed process APIs; .NET provides superior abstraction over OS process handling compared to alternatives
• IAsyncEnumerable (C# 8+) — Enables memory-efficient streaming of process events without buffering entire output; allows consumer to iterate results as they arrive
• P/Invoke to Windows APIs — Provides low-level access to process signaling and credentials on Windows; necessary for graceful termination and elevated execution
• Builder pattern — Complex command configuration with many optional parameters requires fluent, readable syntax; builders avoid constructor overload explosion
• Stream abstractions (PipeSource/PipeTarget) — Decouples process I/O from specific buffer implementations; enables flexible composition (file → memory → process → file chains)

• Immutable CommandResult over stateful result objects

  • Why: Enables safe concurrent result handling and thread-safe result sharing without locks
  • Consequence: Results cannot be modified post-execution; must recreate Command to retry with different configuration

• Fluent operator overloads (| and >) instead of method chaining only

  • Why: Mirrors Unix shell pipe syntax; provides intuitively familiar API for CLI developers
  • Consequence: Operator precedence can be unexpected for unfamiliar users; requires parentheses in some cases

• Buffering as extension method (BufferedCommandExtensions) not core API

  • Why: Keeps core API minimal and streaming-first; buffering is a convenience layer for simple cases
  • Consequence: Users must opt-in to buffering; default behavior streams output, requiring manual collection for some use cases

• Process termination via SIGTERM on Unix, TerminateProcess on

  • Why: undefined
  • Consequence: undefined

Process lifecycle edge cases: On Windows, CTRL+C behavior differs from SIGTERM on Unix—CliWrap abstracts this but tests should run on target platform. Deadlock prevention: The library uses separate threads for reading stdout/stderr simultaneously to avoid the classic deadlock when child process fills a pipe; verify this in piping tests. Encoding assumptions: Tests in CliWrap.Tests.Dummy use UTF-8; if testing with non-UTF-8 locales, GenerateTextCommand may fail. Test.Dummy CLI path: CliWrap.Tests likely expects Test.Dummy to be built and available in a specific output directory—run dotnet build completely before running tests. No obvious hidden .env or configuration files.

• Process Piping & Stream Redirection — The core feature of CliWrap—understanding how stdin/stdout/stderr are redirected, merged, or piped between processes is essential to using the library correctly and avoiding deadlocks
• Graceful Process Cancellation via Signals — CliWrap's cancellation model uses OS-level interrupt signals (SIGTERM, CTRL+C) rather than hard kills—understanding signal handling is crucial for resource cleanup
• Async/Await Deadlock Prevention in I/O — CliWrap uses non-blocking stream reading on separate threads to prevent the classic deadlock where a child process fills stdout/stderr buffers; this pattern is non-obvious and affects API design
• Immutable Fluent Builder Pattern — CliWrap uses strict immutability and fluent configuration to prevent accidental state mutations across async calls—understanding this pattern is essential for using the API safely
• Platform-Specific Process APIs via P/Invoke — CliWrap.Signaler uses native P/Invoke calls to access Windows-specific and POSIX-specific process control mechanisms—knowledge of this pattern helps troubleshoot platform bugs
• Event-Driven Output Streaming (Push vs Pull) — CliWrap offers both PushEventStream (callback-based) and PullEventStream (iterator-based) for consuming subprocess output—choosing between them affects memory usage and code structure
• Encoding & Text Normalization Across Platforms — Line break handling differs between Windows (\r\n) and Unix (\n); CliWrap provides normalization utilities tested in LineBreakSpecs.cs that are easy to miss

• Tyrrrz/Cogito — Same author's experimental library for general .NET utilities; represents the ecosystem of reusable OSS patterns
• dotnet/corefx — Microsoft's System.Diagnostics.Process source code that CliWrap wraps—essential for understanding the low-level abstractions
• MvvmGen/CliWrap.Wpf — Third-party WPF integration library for CliWrap; example of how the library is extended for UI frameworks
• PowerShell/PowerShell — Alternative CLI automation in .NET ecosystem; CliWrap is for executing external processes, PowerShell is an executable itself often called via CliWrap
• Serilog/Serilog — Logging library often used alongside CliWrap to capture and structure subprocess output streams

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for CliWrap.Signaler cross-platform signal handling

CliWrap.Signaler/Native/NativeMethods.cs exists but there are no corresponding test files in CliWrap.Tests for signal handling across Windows/Linux/macOS. This is critical for a library that wraps CLI interactions, as signal handling (SIGTERM, SIGKILL, etc.) is a core feature. Current test coverage likely doesn't exercise the native interop code paths.

• [ ] Create CliWrap.Tests/SignalerSpecs.cs to test signal delivery on Linux/macOS
• [ ] Create CliWrap.Tests/SignalerWindowsSpecs.cs to test process termination on Windows
• [ ] Add test cases for graceful shutdown (SIGTERM) vs forced termination (SIGKILL)
• [ ] Verify NativeMethods.cs is being called correctly via the test results
• [ ] Add platform-conditional test execution using [OSPlatform] attributes

Add integration tests for credential handling (CredentialsBuilder/Credentials.cs)

CliWrap/Credentials.cs and CliWrap/Builders/CredentialsBuilder.cs exist, and CliWrap.Tests/CredentialsSpecs.cs exists but is minimal. The CliWrap.Tests.Dummy project lacks credential-specific test commands. Without proper test coverage, credential passing (user impersonation) on Windows and Unix could have security/functionality gaps.

• [ ] Add a CredentialsCommand.cs to CliWrap.Tests.Dummy that runs and outputs current process user identity
• [ ] Extend CredentialsSpecs.cs with tests verifying process executes under correct user identity
• [ ] Add test cases for Windows-specific credential scenarios (domain\user format validation)
• [ ] Add test cases for Unix-specific credential scenarios (UID/GID verification)
• [ ] Test error handling when invalid credentials are provided

Add benchmarks and tests for ResourcePolicyBuilder edge cases

CliWrap/Builders/ResourcePolicyBuilder.cs exists but there are no corresponding benchmarks in CliWrap.Benchmarks and CliWrap.Tests/ResourcePolicySpecs.cs appears minimal. Resource policies (timeouts, memory limits, CPU limits) are critical for production use. The existing benchmark suite (BufferingBenchmarks.cs, PipeToStreamBenchmarks.cs, etc.) doesn't cover resource constraint scenarios.

• [ ] Create CliWrap.Benchmarks/ResourcePolicyBenchmarks.cs measuring overhead of resource limit enforcement
• [ ] Add test case in ResourcePolicySpecs.cs for timeout enforcement (command should be killed after N milliseconds)
• [ ] Add test case verifying resource limits don't prevent normal fast-executing commands
• [ ] Add test case for cancellation token interaction with resource policies (which takes precedence)
• [ ] Add test for resource policy behavior when piping large streams (verify limits still apply)

• Add cross-platform integration tests for process timeouts in CancellationSpecs.cs—the repo tests cancellation but missing explicit timeout validation across Windows/Linux/macOS
• Expand CredentialsSpecs.cs with tests for running CLI tools as different OS users (RunAs on Windows, sudo context on Linux)—infrastructure exists but feature coverage is thin
• Document the event stream API with runnable examples in a new docs/event-streaming.md or examples/ folder—EventStreamSpecs.cs exists but no user-facing guide for PushEventStream vs PullEventStream tradeoffs

CliWrap is a library for CLI interaction with a generally sound security posture. The main concern is the presence of a strong name key file (key.snk) in the repository, which should be immediately moved to a secure location outside version control. Secondary concerns include ensuring proper validation of inputs to native method calls, command argument validation to prevent command injection, and providing clear security guidance to library consumers regarding credential and environment variable handling. The library's core functionality of process execution requires users to follow security best practices when constructing commands.

• Medium · Strong Name Key File in Repository — CliWrap/key.snk. The file 'CliWrap/key.snk' (Strong Name Key) is present in the repository. Strong name keys are used for assembly signing and should be treated as secrets. If this is a private key, its exposure could allow unauthorized code signing. Fix: Move the key.snk file to a secure location outside the repository. Use environment variables or secure key management systems for CI/CD pipelines. Add key.snk to .gitignore immediately.
• Low · Native Method Calls Require Validation — CliWrap/Native/NativeMethods.cs, CliWrap.Signaler/Native/NativeMethods.cs. The codebase contains Native method calls in 'CliWrap/Native/NativeMethods.cs' and 'CliWrap.Signaler/Native/NativeMethods.cs'. P/Invoke calls to unmanaged code can be a security risk if not properly validated, especially regarding process handling and system signals. Fix: Ensure all P/Invoke declarations use proper marshaling attributes. Validate all parameters passed to native methods. Implement input validation before calling native APIs. Document security assumptions for each native call.
• Low · Process Execution Without Explicit Security Context — CliWrap/Command.Execution.cs, CliWrap/Utils/ProcessEx.cs, CliWrap/Builders/ArgumentsBuilder.cs. The library executes arbitrary command-line interfaces through 'CliWrap/Utils/ProcessEx.cs' and 'CliWrap/Command.Execution.cs'. If user input is directly used to construct commands without validation, it could lead to command injection attacks. Fix: Implement strict input validation for command arguments. Use parameterized command execution where possible. Document security best practices for consumers. Consider adding warnings in documentation about command injection risks.
• Low · Credentials Stored in Configuration — CliWrap/Credentials.cs, CliWrap/Builders/CredentialsBuilder.cs. The 'CliWrap/Credentials.cs' and 'CliWrap/Builders/CredentialsBuilder.cs' files handle credentials for subprocess execution. While the library itself may handle these safely, consumers need clear guidance on secure credential handling. Fix: Ensure documentation clearly states that credentials should never be hardcoded. Recommend using environment variables or secure credential stores. Consider adding warnings in code/documentation about credential exposure risks.
• Low · Environment Variables Configuration — CliWrap/Builders/EnvironmentVariablesBuilder.cs. The 'CliWrap/Builders/EnvironmentVariablesBuilder.cs' allows setting arbitrary environment variables for subprocess execution. This could inadvertently expose sensitive data if not handled carefully by consumers. Fix: Document best practices for handling environment variables securely. Add warnings about sensitive data exposure. Consider implementing filtering for known sensitive variable names.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.