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!

Why Choose command-stream?

🆓 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:

📁 File System Commands

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

🔧 Utility Commands

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

⚡ System Commands

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

✨ Key Advantages

🌍 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

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

# 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:

Smart Quoting Behavior

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)

Shell Injection Protection

All interpolated values are automatically secured:

// ✅ 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)

Disabling Auto-Escape (Advanced)

⚠️ 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:

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

Classic Await (Backward Compatible)

import { $ } from 'command-stream';

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

Custom Options with $({ options }) Syntax (NEW!)

import { $ } from 'command-stream';

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

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

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

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

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

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

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

Execution Control (NEW!)

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();

Synchronous Execution

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();

Async Iteration (Real-time Streaming)

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());
  } else if (chunk.type === 'exit') {
    console.log('Process exited with code:', chunk.code);
  }
}

stream() yields { type: 'stdout' | 'stderr', data: Buffer } chunks as output arrives, followed by a final { type: 'exit', code } chunk when the process exits. Always guard on chunk.type before reading chunk.data, since the exit chunk carries code instead of data.

The iterator terminates as soon as the process exits, even if a grandchild keeps the stdout/stderr pipe open (e.g. sh -c 'background-task & echo done'). Any output still buffered is drained within a short grace period (the exitPumpGrace option, default 100ms) before the lingering reads are aborted, so the loop never hangs waiting on a pipe the command itself is no longer using.

Stopping the process from inside the loop

You can stop a long-running command while iterating over it — either by calling kill() on the command, or simply by breaking out of the loop (which kills the process automatically as the iterator is cleaned up):

const cmd = $`some-endless-stream`;

for await (const chunk of cmd.stream()) {
  if (chunk.type === 'stdout') {
    console.log(chunk.data.toString());
    if (seenEnoughOutput(chunk)) {
      cmd.kill(); // stops the process; the loop then ends with an exit chunk
    }
  } else if (chunk.type === 'exit') {
    console.log('stopped with code', chunk.code); // 143 for the SIGTERM from kill()
  }
}

// Or just break — the process is terminated as the loop unwinds:
for await (const chunk of $`some-endless-stream`.stream()) {
  if (chunk.type === 'stdout' && done(chunk)) break;
}

Choosing the stop signal

kill() defaults to SIGTERM, but you can stop with any signal. Pass it explicitly, or configure a default via the killSignal option so that an argument-less kill(), a break, or an AbortSignal all use it:

// Explicit per-call signal:
cmd.kill('SIGINT'); // exit code 130

// Configured default — used by kill(), break, and AbortSignal cancellation:
const cmd = $({ killSignal: 'SIGINT' })`some-endless-stream`;
for await (const chunk of cmd.stream()) {
  if (chunk.type === 'stdout' && done(chunk))
    cmd.kill(); // sends SIGINT
  else if (chunk.type === 'exit') console.log(chunk.code); // 130
}

// AbortSignal style also honors killSignal — awaiting resolves promptly when
// the signal fires (it does not hang) with the configured signal's exit code:
const ac = new AbortController();
const running = $({
  signal: ac.signal,
  killSignal: 'SIGINT',
})`some-endless-stream`;
setTimeout(() => ac.abort(), 1000); // stops with SIGINT
const result = await running;
console.log(result.code); // 130

command-stream still escalates to SIGKILL after delivering the chosen signal so a process that ignores it is guaranteed to terminate; the reported exit code reflects the signal you configured.

EventEmitter Pattern (Event-driven)

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

Mixed Pattern (Best of Both Worlds)

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();

Streaming Interfaces

Advanced streaming interfaces for fine-grained process control:

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

Shell Replacement (.sh → .mjs)

Replace bash scripts with JavaScript while keeping shell semantics:

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

Cross-Platform File Operations (Built-in Commands)

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

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`;

Working Directory (`cd` and the `cwd` option)

The built-in cd command behaves like cd in a POSIX sh/bash script, so shell scripts translate directly. Crucially, a directory change persists across subsequent commands — just like running successive lines in a shell script:

import { $ } from 'command-stream';

// In sh:                         // In command-stream (.mjs):
// cd /some/directory             await $`cd /some/directory`;
// pwd   # -> /some/directory     await $`pwd`; // -> /some/directory

This is the behavior described in issue #50: each cd updates the process working directory, so the next command starts from the new location. All of the following sh idioms work identically:

await $`cd /tmp && pwd`; // chain with && -> /tmp
await $`cd /tmp`;
await $`pwd`; // separate commands -> /tmp (change persists)
await $`cd`; // no argument -> $HOME
await $`cd ~`; // ~ expands to $HOME
await $`cd ~/projects`; // ~/ prefix expands to $HOME/projects
await $`cd ..`; // parent directory
await $`cd -`; // previous directory (prints it, like sh)
await $`cd /tmp && mkdir t && cd t && pwd`; // -> /tmp/t

A successful cd updates the PWD and OLDPWD environment variables (used by cd -), exactly like a real shell. A failed cd prints a sh-style error to stderr, returns a non-zero exit code, and leaves the working directory unchanged:

const r = await $`cd /does/not/exist`;
console.log(r.code); // 1
console.log(r.stderr); // cd: ENOENT: no such file or directory, ...

Subshell isolation with `( … )`

As in sh, a cd inside a subshell ( … ) does not leak to the parent:

process.chdir('/tmp');
await $`(cd /usr && pwd) ; pwd`;
// -> /usr        (inside the subshell)
// -> /tmp        (parent directory is unchanged)

`cd` vs. the `cwd` option

There are two ways to control the working directory; pick whichever maps best to the script you are translating:

// 1) cd command — mutates the process working directory and persists,
//    just like a line in a shell script.
await $`cd /tmp`;
await $`pwd`; // -> /tmp

// 2) cwd option — sets a fixed working directory for a single invocation
//    (or a reusable $({ cwd }) binding) without changing process.cwd().
await $({ cwd: '/tmp' })`pwd`; // -> /tmp, process.cwd() is untouched

Relative cd targets are resolved against the cwd option when one is provided, so $({ cwd: '/tmp' })`cd sub` changes into /tmp/sub.

Note: Virtual commands such as echo do not perform shell variable expansion, so echo $PWD prints the literal string $PWD. Use process.cwd() in JavaScript, the pwd command, or a real binary (e.g. /bin/echo $PWD) when you need the expanded value.

Virtual Commands (Extensible Shell)

Create custom commands that work seamlessly alongside built-ins:

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:

// ❌ 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.

🔗 Advanced Pipeline Support

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

Shell-Style Piping (Traditional)

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:

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:

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:

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

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

// Or use the chainable .quiet() method (like zx) to suppress output per command
const quiet = await $`echo "silent"`.quiet();

// 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

Log File Streaming with Session ID Extraction

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);
    }
  }
}

Progress Monitoring

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

ProcessRunner Class

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

Default Options

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

{
  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
exitPumpGrace: number - Milliseconds to wait for buffered output to drain after the process exits before aborting stdio reads held open by a grandchild (default 100; see Async Iteration)
killSignal: string - Signal used to stop the process when it is killed without an explicit signal — i.e. kill() with no argument, breaking out of a stream() loop, or an external AbortSignal firing (default 'SIGTERM'). An explicit kill(signal) argument always overrides this. The reported exit code follows the conventional 128 + signal mapping (e.g. SIGTERM → 143, SIGINT → 130, SIGKILL → 137)

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

Shell Settings API

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

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');
}

Virtual Commands API

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

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

// 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";
}

Utility Functions API

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:

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.

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!

Built-in Commands

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)

Result Object

{
  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:

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:

How It Works

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

Advanced Signal Behavior

// ✅ 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

Examples

// 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');
}

Signal Handling Behavior

🎯 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

Command Resolution Priority

// 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

When to Use Different Patterns

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();

Performance Considerations

// 🚀 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

Array Argument Handling

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

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"

Why This Happens

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

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

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

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

Recommended Patterns

// 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} ${flags}`;

// Pattern 3: Build array dynamically
const allArgs = ['input.txt'];
if (verbose) allArgs.push('--verbose');
await $`command ${allArgs}`;

See BEST-PRACTICES.md for more detailed guidance.

Testing

# Run comprehensive test suite (518+ tests)
bun test

# Run tests with coverage report
bun test --coverage

# Run specific test categories
npm run test:features    # Feature comparison tests
npm run test:builtin     # Built-in commands tests
npm run test:pipe        # .pipe() method tests
npm run test:sync        # Synchronous execution tests
npm run test:signal      # CTRL+C signal handling tests

Requirements

Bun: >= 1.0.0 (primary runtime)
Node.js: >= 20.0.0 (compatibility support)

Roadmap

🔄 Coming Soon

TypeScript Support: Full .d.ts definitions and type safety
Enhanced Shell Options: set -u (nounset) and set -o pipefail support
More Built-in Commands: Additional cross-platform utilities

💡 Planned Features

Performance Optimizations: Further Bun runtime optimizations
Advanced Error Handling: Enhanced error context and debugging
Plugin System: Extensible architecture for custom integrations

Contributing

We welcome contributions! Since command-stream is public domain software, your contributions will also be released into the public domain.

🚀 Getting Started

git clone https://github.com/link-foundation/command-stream.git
cd command-stream
bun install
bun test  # Run the full test suite

📋 Development Guidelines

All features must have comprehensive tests
Built-in commands should match bash/sh behavior exactly
Maintain cross-platform compatibility (Windows, macOS, Linux)
Follow the existing code style and patterns

🧪 Running Tests

bun test                    # All 518+ tests
bun test tests/pipe.test.mjs # Specific test file
npm run test:builtin        # Built-in commands only

License - Our Biggest Advantage

The Unlicense (Public Domain)

Unlike other shell utilities that require attribution (MIT, Apache 2.0), command-stream is released into the public domain. This means:

✅ No attribution required - Use it without crediting anyone
✅ No license files to include - Simplify your distribution
✅ No restrictions - Modify, sell, embed, whatever you want
✅ No legal concerns - It's as free as code can be
✅ Corporate friendly - No license compliance overhead

This makes command-stream ideal for:

Commercial products where license attribution is inconvenient
Embedded systems where every byte counts
Educational materials that can be freely shared
Internal tools without legal review requirements

"This is free and unencumbered software released into the public domain."

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

command-$tream

Features

Comparison with Other Libraries

Why Choose command-stream?

Built-in Commands (🚀 NEW!)

📁 File System Commands

🔧 Utility Commands

⚡ System Commands

✨ Key Advantages

Installation

Smart Quoting & Security

Smart Quoting Behavior

Shell Injection Protection

Disabling Auto-Escape (Advanced)

Usage Patterns

Classic Await (Backward Compatible)

Custom Options with $({ options }) Syntax (NEW!)

Execution Control (NEW!)

Synchronous Execution

Async Iteration (Real-time Streaming)

Stopping the process from inside the loop

Choosing the stop signal

EventEmitter Pattern (Event-driven)

Mixed Pattern (Best of Both Worlds)

Streaming Interfaces

Shell Replacement (.sh → .mjs)

Cross-Platform File Operations (Built-in Commands)

Working Directory (cd and the cwd option)

Subshell isolation with ( … )

cd vs. the cwd option

Virtual Commands (Extensible Shell)

🔥 Why Virtual Commands Are Revolutionary

🔗 Advanced Pipeline Support

Shell-Style Piping (Traditional)

🚀 Programmatic .pipe() Method (NEW!)

🆚 How We Compare

Default Behavior: Shell-like with Programmatic Control

Real-world Examples

Log File Streaming with Session ID Extraction

Progress Monitoring

API Reference

ProcessRunner Class

Events

Methods

Properties

Default Options

Shell Settings API

Functions

Error Handling Modes

Virtual Commands API

Functions

Advanced Virtual Command Features

Handler Function Signature

Utility Functions API

Functions

quote() - Manual Quoting

raw() - Disable Auto-Escape

Built-in Commands

Supported Options

Result Object

.text() Method (Bun.$ Compatibility)

Signal Handling (CTRL+C Support)

How It Works

Advanced Signal Behavior

Examples

Signal Handling Behavior

Command Resolution Priority

Execution Patterns Deep Dive

When to Use Different Patterns

Performance Considerations

Common Pitfalls

Array Argument Handling

Why This Happens

Recommended Patterns

Working Directory (`cd` and the `cwd` option)

Subshell isolation with `( … )`

`cd` vs. the `cwd` option

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