Parallelshell

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