command-$tream

$treamable commands executor

A modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime.

Features

- 🐚 Shell-like by Default: Commands behave exactly like running in terminal (stdout→stdout, stderr→stderr, stdin→stdin)
- 🎛️ Fully Controllable: Override default behavior with options (mirror, capture, stdin)
- 🚀 Multiple Usage Patterns: Classic await, async iteration, EventEmitter, .pipe() method, and mixed patterns
- 📡 Real-time Streaming: Process command output as it arrives, not after completion
- 🔄 Bun Optimized: Designed for Bun runtime with Node.js compatibility
- ⚡ Performance: Memory-efficient streaming prevents large buffer accumulation
- 🎯 Backward Compatible: Existing await $ syntax continues to work + Bun.$ .text() method
- 🛡️ Type Safe: Full TypeScript support (coming soon)
- 🔧 Built-in Commands: 18 essential commands work identically across platforms

Comparison with Other Libraries

| Feature | command-stream | execa | cross-spawn | Bun.$ | ShellJS | zx |
| ------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 📦 NPM Package |  |  |  | N/A (Built-in) |  |  |
| ⭐ GitHub Stars | ⭐ 2 (Please ⭐ us!) | ⭐ 7,264 | ⭐ 1,149 | ⭐ 80,169 (Full Runtime) | ⭐ 14,375 | ⭐ 44,569 |
| 📊 Monthly Downloads | 893 (New project!) | 381M | 409M | N/A (Built-in) | 35M | 4.2M |
| 📈 Total Downloads | Growing | 6B+ | 5.4B | N/A (Built-in) | 596M | 37M |
| Runtime Support | ✅ Bun + Node.js | ✅ Node.js | ✅ Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js |
| Template Literals | ✅ ` $cmd | ✅ $cmd | ❌ Function calls | ✅ $cmd | ❌ Function calls | ✅ $cmd |
| Real-time Streaming | ✅ Live output | 🟡 Limited | ❌ Buffer only | ❌ Buffer only | ❌ Buffer only | ❌ Buffer only |
| Synchronous Execution | ✅ .sync() with events | ✅ execaSync | ✅ spawnSync | ❌ No | ✅ Sync by default | ❌ No |
| Async Iteration | ✅ for await (chunk of $.stream()) | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
| EventEmitter Pattern | ✅ .on('data', ...) | 🟡 Limited events | 🟡 Child process events | ❌ No | ❌ No | ❌ No |
| Mixed Patterns | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
| Bun.$ Compatibility | ✅ .text() method support | ❌ No | ❌ No | ✅ Native API | ❌ No | ❌ No |
| Shell Injection Protection | ✅ Smart auto-quoting | ✅ Safe by default | ✅ Safe by default | ✅ Built-in | 🟡 Manual escaping | ✅ Safe by default |
| Cross-platform | ✅ macOS/Linux/Windows | ✅ Yes | ✅ Specialized cross-platform | ✅ Yes | ✅ Yes | ✅ Yes |
| Performance | ⚡ Fast (Bun optimized) | 🐌 Moderate | ⚡ Fast | ⚡ Very fast | 🐌 Moderate | 🐌 Slow |
| Memory Efficiency | ✅ Streaming prevents buildup | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory |
| Error Handling | ✅ Configurable (set -e/set +e, non-zero OK by default) | ✅ Throws on error | ❌ Basic (exit codes) | ✅ Throws on error | ✅ Configurable | ✅ Throws on error |
| Shell Settings | ✅ set -e/set +e equivalent | ❌ No | ❌ No | ❌ No | 🟡 Limited (set()) | ❌ No |
| Stdout Support | ✅ Real-time streaming + events | ✅ Node.js streams + interleaved | ✅ Inherited/buffered | ✅ Shell redirection + buffered | ✅ Direct output | ✅ Readable streams + .pipe.stdout |
| Stderr Support | ✅ Real-time streaming + events | ✅ Streams + interleaved output | ✅ Inherited/buffered | ✅ Redirection + .quiet() access | ✅ Error output | ✅ Readable streams + .pipe.stderr |
| Stdin Support | ✅ string/Buffer/inherit/ignore | ✅ Input/output streams | ✅ Full stdio support | ✅ Pipe operations | 🟡 Basic | ✅ Basic stdin |
| Built-in Commands | ✅ 18 commands: cat, ls, mkdir, rm, mv, cp, touch, basename, dirname, seq, yes + all Bun.$ commands | ❌ Uses system | ❌ Uses system | ✅ echo, cd, etc. | ✅ 20+ commands: cat, ls, mkdir, rm, mv, cp, etc. | ❌ Uses system |
| Virtual Commands Engine | ✅ Revolutionary: Register JavaScript functions as shell commands with full pipeline support | ❌ No custom commands | ❌ No custom commands | ❌ No extensibility | ❌ No custom commands | ❌ No custom commands |
| Pipeline/Piping Support | ✅ Advanced: System + Built-ins + Virtual + Mixed + .pipe() method | ✅ Programmatic .pipe() + multi-destination | ❌ No piping | ✅ Standard shell piping | ✅ Shell piping + .to() method | ✅ Shell piping + .pipe() method |
| Bundle Size | 📦 ~20KB gzipped | 📦 ~400KB+ (packagephobia) | 📦 ~2KB gzipped | 🎯 0KB (built-in) | 📦 ~15KB gzipped | 📦 ~50KB+ (estimated) |
| Signal Handling | ✅ Advanced SIGINT/SIGTERM forwarding with cleanup | 🟡 Basic | ✅ Excellent cross-platform | 🟡 Basic | 🟡 Basic | 🟡 Basic |
| Process Management | ✅ Robust child process lifecycle with proper termination | ✅ Good | ✅ Excellent spawn wrapper | ❌ Basic | 🟡 Limited | 🟡 Limited |
| Debug Tracing | ✅ Comprehensive VERBOSE logging for CI/debugging | 🟡 Limited | ❌ No | ❌ No | 🟡 Basic | ❌ No |
| Test Coverage | ✅ 518+ tests, 1165+ assertions | ✅ Excellent | ✅ Good | 🟡 Good coverage | ✅ Good | 🟡 Good |
| CI Reliability | ✅ Platform-specific handling (macOS/Ubuntu) | ✅ Good | ✅ Excellent | 🟡 Basic | ✅ Good | 🟡 Basic |
| Documentation | ✅ Comprehensive examples + guides | ✅ Excellent | 🟡 Basic | ✅ Good | ✅ Good | 🟡 Limited |
| TypeScript | 🔄 Coming soon | ✅ Full support | ✅ Built-in | ✅ Built-in | 🟡 Community types | ✅ Full support |
| License | ✅ Unlicense (Public Domain) | 🟡 MIT | 🟡 MIT | 🟡 MIT (+ LGPL dependencies) | 🟡 BSD-3-Clause | 🟡 Apache 2.0 |

📊 Popularity & Adoption:

- ⭐ GitHub Stars: Bun: 80,169 • zx: 44,569 • ShellJS: 14,375 • execa: 7,264 • cross-spawn: 1,149 • command-stream: 2 ⭐ us!
- 📈 Total Downloads: execa: 6B+ • cross-spawn: 5.4B • ShellJS: 596M • zx: 37M • command-stream: Growing
- 📊 Monthly Downloads: cross-spawn: 409M • execa: 381M • ShellJS: 35M • zx: 4.2M • command-stream: 893 (growing!)

⭐ Help Us Grow! If command-stream's revolutionary virtual commands and advanced streaming capabilities help your project, please star us on GitHub to help the project grow!

$3

- 🆓 Truly Free: Unlicense (Public Domain) - No restrictions, no attribution required, use however you want
- 🚀 Revolutionary Virtual Commands: World's first fully customizable virtual commands engine - register JavaScript functions as shell commands!
- 🔗 Advanced Pipeline System: Only library where virtual commands work seamlessly in pipelines with built-ins and system commands
- 🔧 Built-in Commands: 18 essential commands work identically across all platforms - no system dependencies!
- 📡 Real-time Processing: Only library with true streaming and async iteration
- 🔄 Flexible Patterns: Multiple usage patterns (await, events, iteration, mixed)
- 🐚 Shell Replacement: Dynamic error handling with set -e/set +e equivalents for .sh file replacement
- ⚡ Bun Optimized: Designed for Bun with Node.js fallback compatibility
- 💾 Memory Efficient: Streaming prevents large buffer accumulation
- 🛡️ Production Ready: 518+ tests, 1165+ assertions with comprehensive coverage including CI reliability
- 🎯 Advanced Signal Handling: Robust SIGINT/SIGTERM forwarding with proper child process cleanup
- 🔍 Debug-Friendly: Comprehensive VERBOSE tracing for CI debugging and troubleshooting

Built-in Commands (🚀 NEW!)

command-stream now includes 18 built-in commands that work identically to their bash/sh counterparts, providing true cross-platform shell scripting without system dependencies:

$3

- cat - Read and display file contents
- ls - List directory contents (supports -l, -a, -A)
- mkdir - Create directories (supports -p recursive)
- rm - Remove files/directories (supports -r, -f)
- mv - Move/rename files and directories
- cp - Copy files/directories (supports -r recursive)
- touch - Create files or update timestamps

$3

- basename - Extract filename from path
- dirname - Extract directory from path
- seq - Generate number sequences
- yes - Output string repeatedly (streaming)

$3

- cd - Change directory
- pwd - Print working directory
- echo - Print arguments (supports -n)
- sleep - Wait for specified time
- true/false - Success/failure commands
- which - Locate commands
- exit - Exit with code
- env - Print environment variables
- test - File condition testing

$3

- 🌍 Cross-Platform: Works identically on Windows, macOS, and Linux
- 🚀 Performance: No system calls - pure JavaScript execution
- 🔄 Pipeline Support: All commands work in pipelines and virtual command chains
- ⚙️ Option Aware: Commands respect cwd, env, and other options
- 🛡️ Safe by Default: Proper error handling and safety checks (e.g., rm requires -r for directories)
- 📝 Bash Compatible: Error messages and behavior match bash/sh exactly

`javascript
import { $ } from 'command-stream';

// All these work without any system dependencies!
await $mkdir -p project/src;
await $touch project/src/index.js;
await $echo "console.log('Hello!');" > project/src/index.js;
await $ls -la project/src;
await $cat project/src/index.js;
await $cp -r project project-backup;
await $rm -r project-backup;

// Mix built-ins with pipelines and virtual commands
await $seq 1 5 | cat > numbers.txt;
await $basename /path/to/file.txt .txt; // → "file"
`

Installation

`bash


Using npm

npm install command-stream

Using bun

bun add command-stream
`

Smart Quoting & Security

Command-stream provides intelligent auto-quoting to protect against shell injection while avoiding unnecessary quotes for safe strings:

$3

`javascript
import { $ } from 'command-stream';

// Safe strings are NOT quoted (performance optimization)
await $echo ${name}; // name = "hello" → echo hello
await $${cmd} --version; // cmd = "/usr/bin/node" → /usr/bin/node --version

// Dangerous strings are automatically quoted for safety
await $echo ${userInput}; // userInput = "test; rm -rf /" → echo 'test; rm -rf /'
await $echo ${pathWithSpaces}; // pathWithSpaces = "/my path/file" → echo '/my path/file'

// Special characters that trigger auto-quoting:
// Spaces, $, ;, |, &, >, <, , *, ?, [, ], {, }, (, ), !, #, and others

// User-provided quotes are preserved
const quotedPath = "'/path with spaces/file'";
await $cat ${quotedPath}; // → cat '/path with spaces/file' (no double-quoting!)

const doubleQuoted = '"/path with spaces/file"';
await $cat ${doubleQuoted}; // → cat '"/path with spaces/file"' (preserves intent)
``

$3

All interpolated values are automatically secured:

`javascript
// ✅ SAFE - All these injection attempts are neutralized
const dangerous = "'; rm -rf /; echo '";
await $echo ${dangerous}; // → echo ''\'' rm -rf /; echo '\'''

const cmdSubstitution = '$(whoami)';
await $echo ${cmdSubstitution}; // → echo '$(whoami)' (literal text, not executed)

const varExpansion = '$HOME';
await $echo ${varExpansion}; // → echo '$HOME' (literal text, not expanded)

// ✅ SAFE - Even complex injection attempts
const complex = 'cat /etc/passwd';
await $echo ${complex}; // → echo 'cat /etc/passwd' (literal text)
`

$3

⚠️ WARNING: Use with extreme caution! Only use raw() with trusted input to prevent shell injection attacks.

For advanced use cases where you need to use command strings directly without auto-escaping, use the raw() function:

`javascript
import { $, raw } from 'command-stream';

// ⚠️ DANGEROUS - Bypasses all safety checks
const userCommand = 'echo "hello" && ls -la';
await $${raw(userCommand)}; // → Executes: echo "hello" && ls -la

// ✅ Safe use case: Trusted command templates
const trustedCommand = 'git log --oneline --graph --all';
await $${raw(trustedCommand)};

// ✅ Combining raw with safe interpolation
const branch = 'main'; // User input - will be auto-quoted
await $${raw('git log --oneline')} ${branch};
// → git log --oneline 'main' (raw part unescaped, branch safely quoted)

// 🎯 Use case: Pre-built command strings from configuration
const config = {
backupCommand: 'tar -czf backup.tar.gz --exclude="*.log" .',
cleanCommand: 'find . -name "*.tmp" -delete',
};
await $${raw(config.backupCommand)};

// ⚠️ NEVER use raw() with user input
const userInput = req.body.command; // ❌ DANGEROUS!
await $${raw(userInput)}; // ❌ Shell injection vulnerability!

// ✅ Instead, use normal interpolation for user input
await $echo ${userInput}; // ✅ Safe - auto-escaped
`

When to use raw():

- ✅ Trusted command templates from your codebase
- ✅ Configuration files you control
- ✅ Hardcoded command strings
- ✅ Complex shell operators that need to be preserved

When NOT to use raw():

- ❌ User input (form fields, API parameters, CLI arguments)
- ❌ External data (database, API responses, files)
- ❌ Any untrusted source
- ❌ When you're unsure - use normal interpolation instead

Usage Patterns

$3

`javascript
import { $ } from 'command-stream';

const result = await $ls -la;
console.log(result.stdout);
console.log(result.code); // exit code
`

$3

`javascript
import { $ } from 'command-stream';

// Create a $ with custom options
const $silent = $({ mirror: false, capture: true });
const result = await $silentecho "quiet operation";

// Options for stdin handling
const $withInput = $({ stdin: 'input data\n' });
await $withInputcat; // Pipes the input to cat

// Custom environment variables
const $withEnv = $({ env: { ...process.env, MY_VAR: 'value' } });
await $withEnvprintenv MY_VAR; // Prints: value

// Custom working directory
const $inTmp = $({ cwd: '/tmp' });
await $inTmppwd; // Prints: /tmp

// Interactive mode for TTY commands (requires TTY environment)
const $interactive = $({ interactive: true });
await $interactivevim myfile.txt; // Full TTY access for editor
await $interactiveless README.md; // Proper pager interaction

// Combine multiple options
const $custom = $({
stdin: 'test data',
mirror: false,
capture: true,
cwd: '/tmp',
});
await $customcat > output.txt; // Writes to /tmp/output.txt silently

// Reusable configurations
const $prod = $({ env: { NODE_ENV: 'production' }, capture: true });
await $prodnpm start;
await $prodnpm test;
`

$3

`javascript
import { $ } from 'command-stream';

// Commands don't auto-start when created
const cmd = $echo "hello";

// Three ways to start execution:

// 1. Explicit start with options
cmd.start(); // Default async mode
cmd.start({ mode: 'async' }); // Explicitly async
cmd.start({ mode: 'sync' }); // Synchronous execution

// 2. Convenience methods
cmd.async(); // Same as start({ mode: 'async' })
cmd.sync(); // Same as start({ mode: 'sync' })

// 3. Auto-start by awaiting (always async)
await cmd; // Auto-starts in async mode

// Event handlers can be attached before starting
const process = $long-command
.on('data', (chunk) => console.log('Received:', chunk))
.on('end', (result) => console.log('Done!'));

// Start whenever you're ready
process.start();
`

$3

`javascript
import { $ } from 'command-stream';

// Use .sync() for blocking execution
const result = $echo "hello".sync();
console.log(result.stdout); // "hello\n"

// Events still work but are batched after completion
$echo "world".on('end', (result) => console.log('Done:', result)).sync();
`

$3

`javascript
import { $ } from 'command-stream';

for await (const chunk of $long-running-command.stream()) {
if (chunk.type === 'stdout') {
console.log('Real-time output:', chunk.data.toString());
}
}
`

$3

`javascript
import { $ } from 'command-stream';

// Attach event handlers then start execution
$command
.on('data', (chunk) => {
if (chunk.type === 'stdout') {
console.log('Stdout:', chunk.data.toString());
}
})
.on('stderr', (chunk) => console.log('Stderr:', chunk))
.on('end', (result) => console.log('Done:', result))
.on('exit', (code) => console.log('Exit code:', code))
.start(); // Explicitly start the command

// Or auto-start by awaiting
const cmd = $another-command.on('data', (chunk) => console.log(chunk));
await cmd; // Auto-starts in async mode
`

$3

`javascript
import { $ } from 'command-stream';

// Async mode - events fire in real-time
const process = $streaming-command;
process.on('data', (chunk) => {
processRealTimeData(chunk);
});
const result = await process;
console.log('Final output:', result.stdout);

// Sync mode - events fire after completion (batched)
const syncCmd = $another-command;
syncCmd.on('end', (result) => {
console.log('Completed with:', result.stdout);
});
const syncResult = syncCmd.sync();
`

$3

Advanced streaming interfaces for fine-grained process control:

`javascript
import { $ } from 'command-stream';

// 🎯 STDIN CONTROL: Send data to interactive commands (real-time)
const grepCmd = $grep "important";
const stdin = await grepCmd.streams.stdin; // Available immediately

stdin.write('ignore this line\n');
stdin.write('important message\n');
stdin.write('skip this too\n');
stdin.end();

const result = await grepCmd;
console.log(result.stdout); // "important message\n"

// 🔧 BINARY DATA: Access raw buffers (after command finishes)
const cmd = $echo "Hello World";
const buffer = await cmd.buffers.stdout; // Complete snapshot
console.log(buffer.length); // 12

// 📝 TEXT DATA: Access as strings (after command finishes)
const textCmd = $echo "Hello World";
const text = await textCmd.strings.stdout; // Complete snapshot
console.log(text.trim()); // "Hello World"

// ⚡ PROCESS CONTROL: Kill commands that ignore stdin
const pingCmd = $ping google.com;

// Some commands ignore stdin input
const pingStdin = await pingCmd.streams.stdin;
if (pingStdin) {
pingStdin.write('q\n'); // ping ignores this
}

// Use kill() for forceful termination
setTimeout(() => pingCmd.kill(), 2000);
const pingResult = await pingCmd;
console.log('Ping stopped with code:', pingResult.code); // 143 (SIGTERM)

// 🔄 MIXED STDOUT/STDERR: Handle both streams (complete snapshots)
const mixedCmd = $sh -c 'echo "out" && echo "err" >&2';
const [stdout, stderr] = await Promise.all([
mixedCmd.strings.stdout, // Available after finish
mixedCmd.strings.stderr, // Available after finish
]);
console.log('Out:', stdout.trim()); // "out"
console.log('Err:', stderr.trim()); // "err"

// 🏃‍♂️ AUTO-START: Streams auto-start processes when accessed
const cmd = $echo "test";
console.log('Started?', cmd.started); // false

const output = await cmd.streams.stdout; // Auto-starts, immediate access
console.log('Started?', cmd.started); // true

// 🔙 BACKWARD COMPATIBLE: Traditional await still works
const traditional = await $echo "still works";
console.log(traditional.stdout); // "still works\n"
`

Key Features:

- command.streams.stdin/stdout/stderr - Direct access to Node.js streams
- command.buffers.stdin/stdout/stderr - Binary data as Buffer objects
- command.strings.stdin/stdout/stderr - Text data as strings
- command.kill() - Forceful process termination
- Auto-start behavior: Process starts only when accessing stream properties
- Perfect for: Interactive commands (grep, sort, bc), data processing, real-time control
- Network commands (ping, wget) ignore stdin → Use kill() method instead

🚀 Streams vs Buffers/Strings:

- streams.* - Available immediately when command starts, for real-time interaction
- buffers. & strings. - Complete snapshots available only after command finishes

$3

Replace bash scripts with JavaScript while keeping shell semantics:

`javascript
import { $, shell, set, unset } from 'command-stream';

// set -e equivalent: exit on any error
shell.errexit(true);

await $mkdir -p build;
await $npm run build;

// set +e equivalent: allow errors (like bash)
shell.errexit(false);
const cleanup = await $rm -rf temp; // Won't throw if fails

// set -e again for critical operations
shell.errexit(true);
await $cp -r build/* deploy/;

// Other bash-like settings
shell.verbose(true); // set -v: print commands
shell.xtrace(true); // set -x: trace execution

// Or use the bash-style API
set('e'); // set -e
unset('e'); // set +e
set('x'); // set -x
set('verbose'); // Long form also supported
`

$3

Replace system-dependent operations with built-in commands that work identically everywhere:

`javascript
import { $ } from 'command-stream';

// File system operations work on Windows, macOS, and Linux identically
await $mkdir -p project/src project/tests;
await $touch project/src/index.js project/tests/test.js;

// List files with details
const files = await $ls -la project/src;
console.log(files.stdout);

// Copy and move operations
await $cp project/src/index.js project/src/backup.js;
await $mv project/src/backup.js project/backup.js;

// File content operations
await $echo "export default 'Hello World';" > project/src/index.js;
const content = await $cat project/src/index.js;
console.log(content.stdout);

// Path operations
const filename = await $basename project/src/index.js .js; // → "index"
const directory = await $dirname project/src/index.js; // → "project/src"

// Generate sequences and process them
await $seq 1 10 | cat > numbers.txt;
const numbers = await $cat numbers.txt;

// Cleanup
await $rm -r project numbers.txt;
`

$3

Create custom commands that work seamlessly alongside built-ins:

`javascript
import { $, register, unregister, listCommands } from 'command-stream';

// Register a custom command
register('greet', async ({ args, stdin }) => {
const name = args[0] || 'World';
return { stdout: Hello, ${name}!\n, code: 0 };
});

// Use it like any other command
await $greet Alice; // → "Hello, Alice!"
await $echo "Bob" | greet; // → "Hello, Bob!"

// Streaming virtual commands with async generators
register('countdown', async function* ({ args }) {
const start = parseInt(args[0] || 5);
for (let i = start; i >= 0; i--) {
yield ${i}\n;
await new Promise((r) => setTimeout(r, 1000));
}
});

// Use in pipelines with built-ins
await $countdown 3 | cat > countdown.txt;

// Virtual commands work in all patterns
for await (const chunk of $countdown 3.stream()) {
console.log('Countdown:', chunk.data.toString().trim());
}

// Management functions
console.log(listCommands()); // List all registered commands
unregister('greet'); // Remove custom commands
`

#### 🔥 Why Virtual Commands Are Revolutionary

No other shell library offers this level of extensibility:

- 🚫 Bun.$: Fixed set of built-in commands, no extensibility API
- 🚫 execa: Transform/pipeline system, but no custom commands
- 🚫 zx: JavaScript functions only, no shell command integration

command-stream breaks the barrier between JavaScript functions and shell commands:

`javascript
// ❌ Other libraries: Choose JavaScript OR shell
await execa('node', ['script.js']); // execa: separate processes
await $node script.js; // zx: shell commands only

// ✅ command-stream: JavaScript functions AS shell commands
register('deploy', async ({ args }) => {
const env = args[0] || 'staging';
await deployToEnvironment(env);
return { stdout: Deployed to ${env}!\n, code: 0 };
});

await $deploy production; // JavaScript function as shell command!
await $deploy staging | tee log.txt; // Works in pipelines!
`

Unique capabilities:

- Seamless Integration: Virtual commands work exactly like built-ins
- Pipeline Support: Full stdin/stdout passing between virtual and system commands
- Streaming: Async generators for real-time output
- Dynamic Registration: Add/remove commands at runtime
- Option Awareness: Virtual commands respect cwd, env, etc.

$3

command-stream offers the most advanced piping system in the JavaScript ecosystem:

#### Shell-Style Piping (Traditional)

`javascript
import { $, register } from 'command-stream';

// ✅ Standard shell piping (like all libraries)
await $echo "hello world" | wc -w; // → "2"

// ✅ Built-in to built-in piping
await $seq 1 5 | cat > numbers.txt;

// ✅ System to built-in piping
await $git log --oneline | head -n 5;

// 🚀 UNIQUE: Virtual command piping
register('uppercase', async ({ args, stdin }) => {
return { stdout: stdin.toUpperCase(), code: 0 };
});

register('reverse', async ({ args, stdin }) => {
return { stdout: stdin.split('').reverse().join(''), code: 0 };
});

// ✅ Built-in to virtual piping
await $echo "hello" | uppercase; // → "HELLO"

// ✅ Virtual to virtual piping
await $echo "hello" | uppercase | reverse; // → "OLLEH"

// ✅ Mixed pipelines (system + built-in + virtual)
await $git log --oneline | head -n 3 | uppercase | cat > LOG.txt;

// ✅ Complex multi-stage pipelines
await $find . -name "*.js" | head -n 10 | basename | sort | uniq;
`

#### 🚀 Programmatic .pipe() Method (NEW!)

World's first shell library with full .pipe() method support for virtual commands:

`javascript
import { $, register } from 'command-stream';

// ✅ Basic programmatic piping
const result = await $echo "hello".pipe($echo "World: $(cat)");

// 🌟 Virtual command chaining
register('add-prefix', async ({ args, stdin }) => {
const prefix = args[0] || 'PREFIX:';
return { stdout: ${prefix} ${stdin.trim()}\n, code: 0 };
});

register('add-suffix', async ({ args, stdin }) => {
const suffix = args[0] || 'SUFFIX';
return { stdout: ${stdin.trim()} ${suffix}\n, code: 0 };
});

// ✅ Chain virtual commands with .pipe()
const result = await $echo "Hello"
.pipe($add-prefix "[PROCESSED]")
.pipe($add-suffix "!!!");
// → "[PROCESSED] Hello !!!"

// ✅ Mix with built-in commands
const fileData = await $cat large-file.txt
.pipe($head -n 100)
.pipe($add-prefix "Line:");

// ✅ Error handling in pipelines
try {
const result = await $cat nonexistent.txt.pipe($add-prefix "Data:");
} catch (error) {
// Source error propagates - destination never executes
console.log('File not found, pipeline stopped');
}

// ✅ Complex data processing
register('json-parse', async ({ args, stdin }) => {
try {
const data = JSON.parse(stdin);
return { stdout: JSON.stringify(data, null, 2), code: 0 };
} catch (error) {
return { stdout: '', stderr: JSON Error: ${error.message}, code: 1 };
}
});

register('extract-field', async ({ args, stdin }) => {
const field = args[0];
try {
const data = JSON.parse(stdin);
const value = data[field] || 'null';
return { stdout: ${value}\n, code: 0 };
} catch (error) {
return { stdout: '', stderr: Extract Error: ${error.message}, code: 1 };
}
});

// Real-world API processing pipeline
const userName = await $curl -s https://api.github.com/users/octocat
.pipe($json-parse)
.pipe($extract-field name);
// → "The Octocat"

// Cleanup
unregister('add-prefix');
unregister('add-suffix');
unregister('json-parse');
unregister('extract-field');
`

#### 🆚 How We Compare

| Library | Pipeline Types | Custom Commands in Pipes | .pipe() Method | Real-time Streaming |
| ------------------ | --------------------------------------- | ------------------------ | ----------------------------------- | ------------------- |
| command-stream | ✅ System + Built-ins + Virtual + Mixed | ✅ Full support | ✅ Full virtual command support | ✅ Yes |
| Bun.$ | ✅ System + Built-ins | ❌ No custom commands | ❌ No .pipe() method | ❌ No |
| execa | ✅ Programmatic .pipe() | ❌ No shell integration | ✅ Basic process piping | 🟡 Limited |
| zx | ✅ Shell piping + .pipe() | ❌ No custom commands | ✅ Stream piping only | ❌ No |

🎯 Unique Advantages:

- Virtual commands work seamlessly in both shell pipes AND .pipe() method - no other library can do this
- Mixed pipeline types - combine system, built-in, and virtual commands freely in both syntaxes
- Real-time streaming through virtual command pipelines
- Full stdin/stdout passing between all command types
- Dual piping syntax - use shell | OR programmatic .pipe() interchangeably

Default Behavior: Shell-like with Programmatic Control

command-stream behaves exactly like running commands in your shell by default:

`javascript
import { $ } from 'command-stream';

// This command will:
// 1. Print "Hello" to your terminal (stdout→stdout)
// 2. Print "Error!" to your terminal (stderr→stderr)
// 3. Capture both outputs for programmatic access
const result = await $sh -c "echo 'Hello'; echo 'Error!' >&2";

console.log('Captured stdout:', result.stdout); // "Hello\n"
console.log('Captured stderr:', result.stderr); // "Error!\n"
console.log('Exit code:', result.code); // 0
`

Key Default Options:

- mirror: true - Live output to terminal (like shell)
- capture: true - Capture output for later use (unlike shell)
- stdin: 'inherit' - Inherit stdin from parent process

Fully Controllable:

`javascript
import { $, create, sh } from 'command-stream';

// Disable terminal output but still capture
const result = await sh('echo "silent"', { mirror: false });

// Custom stdin input
const custom = await sh('cat', { stdin: 'custom input' });

// Create custom $ with different defaults
const quiet$ = create({ mirror: false });
await quiet$echo "silent"; // Won't print to terminal

// Disable both mirroring and capturing for performance
await sh('make build', { mirror: false, capture: false });
`

This gives you the best of both worlds: shell-like behavior by default, but with full programmatic control and real-time streaming capabilities.

Real-world Examples

$3

`javascript
import { $ } from 'command-stream';
import { appendFileSync, writeFileSync } from 'fs';

let sessionId = null;
let logFile = null;

for await (const chunk of $your-streaming-command.stream()) {
if (chunk.type === 'stdout') {
const data = chunk.data.toString();

// Extract session ID from output
if (!sessionId && data.includes('session_id')) {
try {
const parsed = JSON.parse(data);
sessionId = parsed.session_id;
logFile = ${sessionId}.log;
console.log(Session ID: ${sessionId});
} catch (e) {
// Handle JSON parse errors
}
}

// Write to log file in real-time
if (logFile) {
appendFileSync(logFile, data);
}
}
}
`

$3

`javascript
import { $ } from 'command-stream';

let progress = 0;

$download-large-file
.on('stdout', (chunk) => {
const output = chunk.toString();
if (output.includes('Progress:')) {
progress = parseProgress(output);
updateProgressBar(progress);
}
})
.on('end', (result) => {
console.log('Download completed!');
});
`

API Reference

$3

The enhanced $ function returns a ProcessRunner instance that extends EventEmitter.

#### Events

- data: Emitted for each chunk with {type: 'stdout'|'stderr', data: Buffer}
- stdout: Emitted for stdout chunks (Buffer)
- stderr: Emitted for stderr chunks (Buffer)
- end: Emitted when process completes with final result object
- exit: Emitted with exit code

#### Methods

- start(options): Explicitly start command execution
- options.mode: 'async' (default) or 'sync' - execution mode
- async(): Shortcut for start({ mode: 'async' }) - start async execution
- sync(): Shortcut for start({ mode: 'sync' }) - execute synchronously (blocks until completion)
- stream(): Returns an async iterator for real-time chunk processing
- pipe(destination): Programmatically pipe output to another command (returns new ProcessRunner)
- then(), catch(), finally(): Promise interface for await support (auto-starts in async mode)

#### Properties

- stdout: Direct access to child process stdout stream
- stderr: Direct access to child process stderr stream
- stdin: Direct access to child process stdin stream

$3

By default, command-stream behaves like running commands in the shell:

`javascript
{
mirror: true, // Live output to terminal (stdout→stdout, stderr→stderr)
capture: true, // Capture output for programmatic access
stdin: 'inherit', // Inherit stdin from parent process
interactive: false // Explicitly request TTY forwarding for interactive commands
}
`

Option Details:

- mirror: boolean - Whether to pipe output to terminal in real-time
- capture: boolean - Whether to capture output in result object
- stdin: 'inherit' | 'ignore' | string | Buffer - How to handle stdin
- interactive: boolean - Enable TTY forwarding for interactive commands (requires stdin: 'inherit' and TTY environment)
- cwd: string - Working directory for command
- env: object - Environment variables

Override defaults:

- Use $({ options }) syntax for one-off configurations with template literals
- Use sh(command, options) for one-off overrides with string commands
- Use create(defaultOptions) to create custom $ with different defaults

$3

Control shell behavior like bash set/unset commands:

#### Functions

- shell.errexit(boolean): Enable/disable exit-on-error (like set ±e)
- shell.verbose(boolean): Enable/disable command printing (like set ±v)
- shell.xtrace(boolean): Enable/disable execution tracing (like set ±x)
- set(option): Enable shell option ('e', 'v', 'x', or long names)
- unset(option): Disable shell option
- shell.settings(): Get current settings object

#### Error Handling Modes

`javascript
import { $, shell } from 'command-stream';

// ✅ Default behavior: Commands don't throw on non-zero exit
const result = await $ls nonexistent-file; // Won't throw
console.log(result.code); // → 2 (non-zero, but no exception)

// ✅ Enable errexit: Commands throw on non-zero exit
shell.errexit(true);
try {
await $ls nonexistent-file; // Throws error
} catch (error) {
console.log('Command failed:', error.code); // → 2
}

// ✅ Disable errexit: Back to non-throwing behavior
shell.errexit(false);
await $ls nonexistent-file; // Won't throw, returns result with code 2

// ✅ One-time override without changing global settings
try {
const result = await $ls nonexistent-file;
if (result.code !== 0) {
throw new Error(Command failed with code ${result.code});
}
} catch (error) {
console.log('Manual error handling');
}
`

$3

Control and extend the command system with custom JavaScript functions:

#### Functions

- register(name, handler): Register a virtual command
- name: Command name (string)
- handler: Function or async generator (args, stdin, options) => result
- unregister(name): Remove a virtual command
- listCommands(): Get array of all registered command names
- enableVirtualCommands(): Enable virtual command processing
- disableVirtualCommands(): Disable virtual commands (use system commands only)

#### Advanced Virtual Command Features

`javascript
import { $, register } from 'command-stream';

// ✅ Cancellation support with AbortController
register('cancellable', async function* ({ args, stdin, abortSignal }) {
for (let i = 0; i < 10; i++) {
if (abortSignal?.aborted) {
break; // Proper cancellation handling
}
yield Count: ${i}\n;
await new Promise((resolve) => setTimeout(resolve, 1000));
}
});

// ✅ Access to all process options
// All original options (built-in + custom) are available in the 'options' object
// Common options like cwd, env are also available at top level for convenience
// Runtime additions: isCancelled function, abortSignal
register(
'debug-info',
async ({ args, stdin, cwd, env, options, isCancelled }) => {
return {
stdout: JSON.stringify(
{
args,
cwd, // Available at top level for convenience
env: Object.keys(env || {}), // Available at top level for convenience
stdinLength: stdin?.length || 0,
allOptions: options, // All original options (built-in + custom)
mirror: options.mirror, // Built-in option from options object
capture: options.capture, // Built-in option from options object
customOption: options.customOption || 'not provided', // Custom option
isCancelledAvailable: typeof isCancelled === 'function',
},
null,
2
),
code: 0,
};
}
);

// ✅ Error handling and non-zero exit codes
register('maybe-fail', async ({ args }) => {
if (Math.random() > 0.5) {
return {
stdout: 'Success!\n',
code: 0,
};
} else {
return {
stdout: '',
stderr: 'Random failure occurred\n',
code: 1,
};
}
});

// ✅ Example: User options flow through to virtual commands
register('show-options', async ({ args, stdin, options, cwd }) => {
return {
stdout: Custom: ${options.customValue || 'none'}, CWD: ${cwd || options.cwd || 'default'}\n,
code: 0,
};
});

// Usage example showing options passed to virtual command:
const result = await $({
customValue: 'hello world',
cwd: '/tmp',
})show-options;
console.log(result.stdout); // Output: Custom: hello world, CWD: /tmp
`

#### Handler Function Signature

`javascript
// Regular async function
async function handler({ args, stdin, abortSignal, cwd, env, options, isCancelled }) {
// All original options available in 'options': options.mirror, options.capture, options.customValue, etc.
// Common options like cwd, env also available at top level for convenience
return {
code: 0, // Exit code (number)
stdout: "output", // Standard output (string)
stderr: "", // Standard error (string)
};
}

// Async generator for streaming
async function streamingHandler({ args, stdin, abortSignal, cwd, env, options, isCancelled }) {
// Access both built-in and custom options from 'options' object
if (options.customFlag) {
yield "custom behavior\n";
}
yield "chunk1\n";
yield "chunk2\n";
}
`

$3

Control how values are interpolated into commands:

#### Functions

- quote(value): Manually quote a value using the same smart quoting logic as auto-interpolation
- raw(value): ⚠️ Dangerous! Bypass auto-escaping to use command strings directly (see Disabling Auto-Escape)

#### quote() - Manual Quoting

Apply the same smart quoting logic manually:

`javascript
import { $, quote } from 'command-stream';

const path = '/path with spaces/file.txt';
const quoted = quote(path);
console.log(quoted); // → '/path with spaces/file.txt'

// Use case: Pre-process values before interpolation
const args = ['hello world', 'test'].map(quote);
// → ["'hello world'", 'test']
`

#### raw() - Disable Auto-Escape

⚠️ WARNING: Only use with trusted input! See Disabling Auto-Escape section for detailed documentation and security considerations.

`javascript
import { $, raw } from 'command-stream';

// Bypass auto-escaping for trusted command strings
const trustedCommand = 'echo "hello" && ls -la';
await $${raw(trustedCommand)};
// → Executes: echo "hello" && ls -la (without escaping)

// ⚠️ NEVER use with untrusted input - shell injection risk!
`

$3

18 cross-platform commands that work identically everywhere:

File System: cat, ls, mkdir, rm, mv, cp, touch
Utilities: basename, dirname, seq, yes
System: cd, pwd, echo, sleep, true, false, which, exit, env, test

All built-in commands support:

- Standard flags (e.g., ls -la, mkdir -p, rm -rf)
- Pipeline operations
- Option awareness (cwd, env, etc.)
- Bash-compatible error messages and exit codes

#### Supported Options

- 'e' / 'errexit': Exit on command failure
- 'v' / 'verbose': Print commands before execution
- 'x' / 'xtrace': Trace command execution with + prefix
- 'u' / 'nounset': Error on undefined variables (planned)
- 'pipefail': Pipe failure detection (planned)

$3

`javascript
{
code: number, // Exit code
stdout: string, // Complete stdout output
stderr: string, // Complete stderr output
stdin: string, // Input sent to process
child: ChildProcess, // Original child process object
async text() // Bun.$ compatibility method - returns stdout as string
}
`

#### .text() Method (Bun.$ Compatibility)

For compatibility with Bun.$, all result objects include an async .text() method:

`javascript
import { $ } from 'command-stream';

// Both sync and async execution support .text()
const result1 = await $echo "hello world";
const text1 = await result1.text(); // "hello world\n"

const result2 = $echo "sync example".sync();
const text2 = await result2.text(); // "sync example\n"

// .text() is equivalent to accessing .stdout
expect(await result.text()).toBe(result.stdout);

// Works with built-in commands
const result3 = await $seq 1 3;
const text3 = await result3.text(); // "1\n2\n3\n"

// Works with .pipe() method
const result4 = await $echo "pipe test".pipe($cat);
const text4 = await result4.text(); // "pipe test\n"
`

Signal Handling (CTRL+C Support)

The library provides advanced CTRL+C handling that properly manages signals across different scenarios:

$3

1. Smart Signal Forwarding: CTRL+C is forwarded only when child processes are active
2. User Handler Preservation: When no children are running, your custom SIGINT handlers work normally
3. Process Groups: Child processes use detached spawning for proper signal isolation
4. TTY Mode Support: Raw TTY mode is properly managed and restored on interruption
5. Graceful Termination: Uses SIGTERM → SIGKILL escalation for robust process cleanup
6. Exit Code Standards: Proper signal exit codes (130 for SIGINT, 143 for SIGTERM)

$3

`javascript
// ✅ Smart signal handling - only interferes when necessary
import { $ } from 'command-stream';

// Case 1: No children active - your handlers work normally
process.on('SIGINT', () => {
console.log('My custom handler runs!');
process.exit(42); // Custom exit code
});
// Press CTRL+C → Your handler runs, exits with code 42

// Case 2: Children active - automatic forwarding
await $ping 8.8.8.8; // Press CTRL+C → Forwards to ping, exits with code 130

// Case 3: Multiple processes - all interrupted
await Promise.all([$sleep 100, $ping google.com]); // Press CTRL+C → All processes terminated, exits with code 130
`

$3

`javascript
// Long-running command that can be interrupted with CTRL+C
try {
await $ping 8.8.8.8; // Press CTRL+C to stop
} catch (error) {
console.log('Command interrupted:', error.code); // Exit code 130 (SIGINT)
}

// Multiple concurrent processes - CTRL+C stops all
try {
await Promise.all([
$sleep 100,
$ping google.com,
$tail -f /var/log/system.log,
]);
} catch (error) {
// All processes are terminated when you press CTRL+C
}

// Works with streaming patterns too
try {
for await (const chunk of $ping 8.8.8.8.stream()) {
console.log(chunk);
// Press CTRL+C to break the loop and stop the process
}
} catch (error) {
console.log('Streaming interrupted');
}
`

$3

- 🎯 Smart Detection: Only forwards CTRL+C when child processes are active
- 🛡️ Non-Interference: Preserves user SIGINT handlers when no children running
- ⚡ Interactive Commands: Use interactive: true option for commands like vim, less, top to enable proper TTY forwarding and signal handling
- 🔄 Process Groups: Detached spawning ensures proper signal isolation
- 🧹 TTY Cleanup: Raw terminal mode properly restored on interruption
- 📊 Standard Exit Codes:
- 130 - SIGINT interruption (CTRL+C)
- 143 - SIGTERM termination (programmatic kill)
- 137 - SIGKILL force termination

$3

`javascript
// Understanding how commands are resolved:

// 1. Virtual Commands (highest priority)
register('echo', () => ({ stdout: 'virtual!\n', code: 0 }));
await $echo test; // → "virtual!"

// 2. Built-in Commands (if no virtual match)
unregister('echo');
await $echo test; // → Uses built-in echo

// 3. System Commands (if no built-in/virtual match)
await $unknown-command; // → Uses system PATH lookup

// 4. Virtual Bypass (special case)
await $({ stdin: 'data' })sleep 1; // Bypasses virtual sleep, uses system sleep
`

Execution Patterns Deep Dive

$3

`javascript
import { $ } from 'command-stream';

// ✅ Use await for simple command execution
const result = await $ls -la;

// ✅ Use .sync() when you need blocking execution with events
const syncCmd = $build-script
.on('stdout', (chunk) => updateProgress(chunk))
.sync(); // Events fire after completion

// ✅ Use .start() for non-blocking execution with real-time events
const asyncCmd = $long-running-server
.on('stdout', (chunk) => logOutput(chunk))
.start(); // Events fire in real-time

// ✅ Use .stream() for processing large outputs efficiently
for await (const chunk of $generate-big-file.stream()) {
processChunkInRealTime(chunk);
} // Memory efficient - processes chunks as they arrive

// ✅ Use EventEmitter pattern for complex workflows
$deployment-script
.on('stdout', (chunk) => {
if (chunk.toString().includes('ERROR')) {
handleError(chunk);
}
})
.on('stderr', (chunk) => logError(chunk))
.on('end', (result) => {
if (result.code === 0) {
notifySuccess();
}
})
.start();
`

$3

`javascript
// 🚀 Memory Efficient: For large outputs, use streaming
for await (const chunk of $cat huge-file.log.stream()) {
processChunk(chunk); // Processes incrementally
}

// 🐌 Memory Inefficient: Buffers entire output in memory
const result = await $cat huge-file.log;
processFile(result.stdout); // Loads everything into memory

// ⚡ Fastest: Sync execution for small, quick commands
const quickResult = $pwd.sync();

// 🔄 Best for UX: Async with events for long-running commands
$npm install.on('stdout', showProgress).start();
`

Common Pitfalls

$3

When passing multiple arguments, pass the array directly - never use .join(' ') before interpolation:

`javascript
import { $ } from 'command-stream';

// WRONG - entire string becomes ONE argument
const args = ['file.txt', '--public', '--verbose'];
await $command ${args.join(' ')};
// Shell receives: command 'file.txt --public --verbose' (1 argument!)
// Error: File does not exist: "file.txt --public --verbose"

// CORRECT - each element becomes separate argument
await $command ${args};
// Shell receives: command file.txt --public --verbose (3 arguments)
`

This is a common mistake that causes errors like:

`
Error: File does not exist: "/path/to/file.txt --flag --option"
`

$3

The $ template tag handles arrays specially - each element is quoted separately:

`javascript
if (Array.isArray(value)) {
return value.map(quote).join(' '); // Each element quoted individually
}
`

But when you call .join(' ') first:

1. The array becomes a string: "file.txt --public --verbose"
2. Template receives a string, not an array
3. The entire string gets quoted as one argument
4. Command receives one argument containing spaces

$3

`javascript
// Pattern 1: Direct array passing
const args = ['file.txt', '--verbose'];
await $command ${args};

// Pattern 2: Separate interpolations
const file = 'file.txt';
const flags = ['--verbose', '--force'];
await $command ${file} ${f