Winix.Wargs 0.3.0

wargs

Read items from stdin and execute a command for each one. Cross-platform xargs replacement with sane defaults.

Line-delimited by default, {} placeholder substitution, parallel execution, batching, dry-run, confirm, and structured output.

xargs replacement (and works on Linux/macOS too).

Install

Scoop (Windows)

scoop bucket add winix https://github.com/Yortw/winix
scoop install winix/wargs

Winget (Windows, stable releases)

winget install Winix.Wargs

.NET Tool (cross-platform)

dotnet tool install -g Winix.Wargs

Direct Download

Download native binaries from GitHub Releases.

Usage

<input> | wargs [options] [--] <command> [args...]

Items are read from stdin (one per line by default) and each item is passed to the command. If the command contains {}, each item replaces the placeholder; otherwise items are appended as trailing arguments.

Examples

# Simple foreach — ssh to each server
cat servers.txt | wargs ssh {} "uptime"

# Parallel — format 4 files at a time
find . -name "*.cs" | wargs -P4 dotnet format {}

# Batch — pass 10 URLs per curl invocation
cat urls.txt | wargs -n10 curl

# Dry run — see what would be executed
find . -name "*.log" | wargs --dry-run rm

# Confirm — prompt before each deletion
find . -name "*.bak" | wargs -p rm

# JSON summary to stderr
git ls-files "*.cs" | wargs --json dotnet format {}

# Null-delimited input (find -print0)
find . -name "*.tmp" -print0 | wargs -0 rm

# Default echo — no command means print items
seq 5 | wargs

# Verbose — print each command before running
cat hosts.txt | wargs -v ping -c1 {}

# Fail fast — stop on first error
cat servers.txt | wargs --fail-fast ssh {} "systemctl restart app"

# Keep order — parallel but output in input order
cat urls.txt | wargs -P4 -k curl -s {}

# NDJSON — streaming per-job results to stderr
cat servers.txt | wargs --ndjson ssh {} "uptime"

# Windows — dir /b gives bare filenames, one per line
dir /b *.log | wargs del {}

How It Works

1. Read items from stdin (line-delimited, null-delimited, custom delimiter, or POSIX whitespace)
2. Build command invocations by substituting {} or appending items, with optional batching (-n)
3. Execute jobs sequentially or in parallel (-P), with configurable output buffering
4. Report results as human text, JSON summary, or streaming NDJSON

Options

Differences from xargs

Exit Codes

Restrictions

• --confirm (-p) and --verbose (-v) cannot be combined with --json or --ndjson. Confirm prompts and verbose plaintext lines write to stderr — the same channel as structured envelopes — and would interleave plaintext among JSON output. Wargs rejects these combinations at parse time with usage_error (exit 125).
• --ndjson and --line-buffered cannot be combined. Line-buffered children inherit stdio directly, which conflicts with NDJSON's stderr line discipline.
• --keep-order and --line-buffered cannot be combined. Order preservation requires per-job buffering.

Shell Builtins

Commands like echo, del, type, and ver are shell builtins on Windows — they don't exist as standalone .exe files. By default, wargs automatically retries failed commands via the platform shell (cmd /c on Windows, sh -c on Unix), so builtins work transparently:

dir /b *.log | wargs echo {}

Use --no-shell-fallback to disable this and require all commands to be standalone executables.

Colour

• Automatic: colour when outputting to a terminal, plain when piped
• --color forces colour on (overrides NO_COLOR)
• --no-color forces colour off
• Respects the NO_COLOR environment variable (no-color.org)

Part of Winix

wargs is part of the Winix CLI toolkit.