Parallelshell

Parallelshell is a cross-platform command-line utility for executing multiple shell commands in parallel with automatic process cleanup, proper exit code propagation, and graceful termination. It provides better reliability and control than traditional shell job control mechanisms.

Package Information

• Package Name: parallelshell
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g parallelshell or npm install --save-dev parallelshell
• Binary Entry Point: ./index.js (executable script)
• Main Module: index.js

Core Imports

Parallelshell is a CLI binary, not a programmatic API. It's accessed via command line execution:

# Direct execution (global install)
parallelshell "command1" "command2" "command3"

# Via npx (local install)
npx parallelshell "npm run server" "npm run client"

# In npm scripts
"scripts": {
  "dev": "parallelshell \"npm run api\" \"npm run ui\""
}

Basic Usage

# Run multiple development servers
parallelshell "npm run api-server" "npm run webpack-dev-server" "npm run sass-watch"

# Run tests in parallel
parallelshell "npm run test:unit" "npm run test:integration" "npm run lint"

# With options
parallelshell --verbose --wait "long-running-task" "another-task"

Capabilities

Command Execution

Executes multiple shell commands simultaneously with cross-platform compatibility.

parallelshell [options] <command1> <command2> ... <commandN>

CLI Signature:

• parallelshell: Main executable command
• [options]: Optional flags (-h, -v, -w and their long forms)
• <command1> <command2> ... <commandN>: Shell commands to execute in parallel (quoted strings)

Arguments:

• command1, command2, ...commandN (string): Shell commands to execute in parallel (must be quoted on Windows)

Command Options

Help Option

Displays usage information and exits.

parallelshell -h
parallelshell --help

Output:

-h, --help         output usage information
-v, --verbose      verbose logging
-w, --wait         will not close sibling processes on error

Verbose Logging

Enables detailed logging of process status and lifecycle events.

parallelshell -v [commands...]
parallelshell --verbose [commands...]

Behavior:

• Reports when processes end successfully: "<command> ended successfully"
• Reports exit codes for failed processes: "<command> failed with exit code <code>"
• Shows status of all running processes periodically with "### Status ###" header
• Displays process state: running, errored, or finished
• Shows process termination messages during cleanup: "<command> will now be closed"

Wait Mode

Prevents automatic termination of sibling processes when one process fails.

parallelshell -w [commands...]
parallelshell --wait [commands...]

Behavior:

• By default, if any process exits with non-zero code, all other processes are terminated
• With --wait, other processes continue running even if siblings fail
• Still propagates the first non-zero exit code as the final exit code

Process Management Features

Automatic Process Cleanup

Default Behavior:

• When any child process exits with non-zero code, all other processes are immediately terminated
• Ensures fail-fast behavior for development workflows
• Can be disabled with --wait option

Signal Handling

SIGINT (Ctrl+C) Handling:

• Gracefully terminates all running child processes
• Sends SIGINT to each child process
• Waits for all processes to exit before terminating itself
• Provides clean shutdown behavior
• Process cleanup sequence: removes event listeners, kills processes, waits for all to close

Process Creation Details:

• Uses child_process.spawn() with shell command execution
• Child processes inherit parent's environment variables (process.env)
• Working directory set to current process directory
• Output streams piped to parent (stdout/stderr shared, stdin piped)

Exit Code Propagation

Exit Code Behavior:

• Returns exit code 0 if all processes complete successfully
• Returns the exit code of the first process that fails
• Maintains proper exit semantics for CI/CD and script chaining

Cross-Platform Compatibility

Windows:

• Uses cmd /c for command execution
• Requires double quotes around commands to avoid argument parser confusion
• Commands executed directly without exec prefix

Unix/Linux/macOS:

• Uses sh -c with exec prefix for command execution
• Commands are prefixed with exec to ensure proper process replacement
• Supports standard shell quoting and escaping

Node.js Version Compatibility:

• Node.js < 8.0.0: Uses legacy process.cwd behavior
• Node.js >= 8.0.0: Uses modern process.cwd() method for working directory handling

Output Handling

Unified Output Streams

Standard Output/Error:

• All child processes share the parent's stdout and stderr
• Output from multiple processes is interleaved naturally
• No output buffering or separation - all output appears immediately
• Preserves color and formatting from child processes

Advanced Usage Patterns

Development Workflows

# Start development environment
parallelshell "npm run api" "npm run ui" "npm run docs"

# With verbose logging for debugging
parallelshell --verbose "npm start" "npm run watch:css" "npm run watch:js"

CI/CD Integration

# Fail fast (default behavior)
parallelshell "npm run test" "npm run lint" "npm run type-check"

# Continue on failure to collect all results
parallelshell --wait "npm run test" "npm run lint" "npm run security-audit"

Windows Compatibility

# Windows requires double quotes
parallelshell "npm run server" "npm run client"

# Unix/Linux can use single or double quotes
parallelshell 'npm run server' 'npm run client'

Error Handling

Process Failure Scenarios

Single Process Failure (Default):

1. One child process exits with non-zero code
2. All other processes receive SIGINT and are terminated
3. Parallelshell exits with the failed process's exit code

Process Failure with --wait:

1. One child process exits with non-zero code
2. Other processes continue running normally
3. Parallelshell waits for all processes to complete
4. Exits with the first failure's exit code

Common Exit Codes

• 0: All processes completed successfully
• 1+: Exit code from the first process that failed
• SIGINT: User interrupted with Ctrl+C (clean shutdown)

Installation and Setup

Global Installation

npm install -g parallelshell

Use directly from command line:

parallelshell "echo hello" "echo world"

Local Installation

npm install --save-dev parallelshell

Use in npm scripts:

{
  "scripts": {
    "dev": "parallelshell \"npm run api\" \"npm run ui\"",
    "test:all": "parallelshell \"npm run test:unit\" \"npm run test:e2e\""
  }
}

Use with npx:

npx parallelshell "command1" "command2"

Comparison with Alternatives

vs. Shell Background Jobs (&)

Parallelshell advantages:

• Cross-platform (works on Windows)
• Automatic cleanup when processes fail
• Waits for all processes to complete
• Proper exit code handling
• Unified output handling
• Graceful Ctrl+C behavior

vs. GNU Parallel

Parallelshell advantages:

• npm package (easier integration with Node.js projects)
• Simpler interface for basic parallel execution
• Better integration with npm scripts and development workflows

GNU Parallel advantages:

• More advanced features and options
• Better for complex data processing workflows