0
# Parallelshell
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: parallelshell
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -g parallelshell` or `npm install --save-dev parallelshell`
10
- **Binary Entry Point**: `./index.js` (executable script)
11
- **Main Module**: `index.js`
12

13
## Core Imports
14

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

17
```bash
18
# Direct execution (global install)
19
parallelshell "command1" "command2" "command3"
20

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

24
# In npm scripts
25
"scripts": {
26
  "dev": "parallelshell \"npm run api\" \"npm run ui\""
27
}
28
```
29

30
## Basic Usage
31

32
```bash
33
# Run multiple development servers
34
parallelshell "npm run api-server" "npm run webpack-dev-server" "npm run sass-watch"
35

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

39
# With options
40
parallelshell --verbose --wait "long-running-task" "another-task"
41
```
42

43
## Capabilities
44

45
### Command Execution
46

47
Executes multiple shell commands simultaneously with cross-platform compatibility.
48

49
```bash { .api }
50
parallelshell [options] <command1> <command2> ... <commandN>
51
```
52

53
**CLI Signature:**
54
- `parallelshell`: Main executable command
55
- `[options]`: Optional flags (-h, -v, -w and their long forms)
56
- `<command1> <command2> ... <commandN>`: Shell commands to execute in parallel (quoted strings)
57

58
**Arguments:**
59
- `command1, command2, ...commandN` (string): Shell commands to execute in parallel (must be quoted on Windows)
60

61
### Command Options
62

63
#### Help Option
64

65
Displays usage information and exits.
66

67
```bash { .api }
68
parallelshell -h
69
parallelshell --help
70
```
71

72
**Output:**
73
```
74
-h, --help         output usage information
75
-v, --verbose      verbose logging
76
-w, --wait         will not close sibling processes on error
77
```
78

79
#### Verbose Logging
80

81
Enables detailed logging of process status and lifecycle events.
82

83
```bash { .api }
84
parallelshell -v [commands...]
85
parallelshell --verbose [commands...]
86
```
87

88
**Behavior:**
89
- Reports when processes end successfully: "`<command>` ended successfully"
90
- Reports exit codes for failed processes: "`<command>` failed with exit code <code>"
91
- Shows status of all running processes periodically with "### Status ###" header
92
- Displays process state: running, errored, or finished
93
- Shows process termination messages during cleanup: "`<command>` will now be closed"
94

95
#### Wait Mode
96

97
Prevents automatic termination of sibling processes when one process fails.
98

99
```bash { .api }
100
parallelshell -w [commands...]
101
parallelshell --wait [commands...]
102
```
103

104
**Behavior:**
105
- By default, if any process exits with non-zero code, all other processes are terminated
106
- With `--wait`, other processes continue running even if siblings fail
107
- Still propagates the first non-zero exit code as the final exit code
108

109
### Process Management Features
110

111
#### Automatic Process Cleanup
112

113
**Default Behavior:**
114
- When any child process exits with non-zero code, all other processes are immediately terminated
115
- Ensures fail-fast behavior for development workflows
116
- Can be disabled with `--wait` option
117

118
#### Signal Handling
119

120
**SIGINT (Ctrl+C) Handling:**
121
- Gracefully terminates all running child processes
122
- Sends SIGINT to each child process
123
- Waits for all processes to exit before terminating itself
124
- Provides clean shutdown behavior
125
- Process cleanup sequence: removes event listeners, kills processes, waits for all to close
126

127
**Process Creation Details:**
128
- Uses `child_process.spawn()` with shell command execution
129
- Child processes inherit parent's environment variables (`process.env`)
130
- Working directory set to current process directory
131
- Output streams piped to parent (stdout/stderr shared, stdin piped)
132

133
#### Exit Code Propagation
134

135
**Exit Code Behavior:**
136
- Returns exit code 0 if all processes complete successfully
137
- Returns the exit code of the first process that fails
138
- Maintains proper exit semantics for CI/CD and script chaining
139

140
#### Cross-Platform Compatibility
141

142
**Windows:**
143
- Uses `cmd /c` for command execution
144
- Requires double quotes around commands to avoid argument parser confusion
145
- Commands executed directly without exec prefix
146

147
**Unix/Linux/macOS:**
148
- Uses `sh -c` with `exec` prefix for command execution
149
- Commands are prefixed with `exec` to ensure proper process replacement
150
- Supports standard shell quoting and escaping
151

152
**Node.js Version Compatibility:**
153
- Node.js < 8.0.0: Uses legacy `process.cwd` behavior
154
- Node.js >= 8.0.0: Uses modern `process.cwd()` method for working directory handling
155

156
### Output Handling
157

158
#### Unified Output Streams
159

160
**Standard Output/Error:**
161
- All child processes share the parent's stdout and stderr
162
- Output from multiple processes is interleaved naturally
163
- No output buffering or separation - all output appears immediately
164
- Preserves color and formatting from child processes
165

166
## Advanced Usage Patterns
167

168
### Development Workflows
169

170
```bash
171
# Start development environment
172
parallelshell "npm run api" "npm run ui" "npm run docs"
173

174
# With verbose logging for debugging
175
parallelshell --verbose "npm start" "npm run watch:css" "npm run watch:js"
176
```
177

178
### CI/CD Integration
179

180
```bash
181
# Fail fast (default behavior)
182
parallelshell "npm run test" "npm run lint" "npm run type-check"
183

184
# Continue on failure to collect all results
185
parallelshell --wait "npm run test" "npm run lint" "npm run security-audit"
186
```
187

188
### Windows Compatibility
189

190
```bash
191
# Windows requires double quotes
192
parallelshell "npm run server" "npm run client"
193

194
# Unix/Linux can use single or double quotes
195
parallelshell 'npm run server' 'npm run client'
196
```
197

198
## Error Handling
199

200
### Process Failure Scenarios
201

202
**Single Process Failure (Default):**
203
1. One child process exits with non-zero code
204
2. All other processes receive SIGINT and are terminated
205
3. Parallelshell exits with the failed process's exit code
206

207
**Process Failure with --wait:**
208
1. One child process exits with non-zero code
209
2. Other processes continue running normally
210
3. Parallelshell waits for all processes to complete
211
4. Exits with the first failure's exit code
212

213
### Common Exit Codes
214

215
- **0**: All processes completed successfully
216
- **1+**: Exit code from the first process that failed
217
- **SIGINT**: User interrupted with Ctrl+C (clean shutdown)
218

219
## Installation and Setup
220

221
### Global Installation
222

223
```bash
224
npm install -g parallelshell
225
```
226

227
Use directly from command line:
228
```bash
229
parallelshell "echo hello" "echo world"
230
```
231

232
### Local Installation
233

234
```bash
235
npm install --save-dev parallelshell
236
```
237

238
Use in npm scripts:
239
```json
240
{
241
  "scripts": {
242
    "dev": "parallelshell \"npm run api\" \"npm run ui\"",
243
    "test:all": "parallelshell \"npm run test:unit\" \"npm run test:e2e\""
244
  }
245
}
246
```
247

248
Use with npx:
249
```bash
250
npx parallelshell "command1" "command2"
251
```
252

253
## Comparison with Alternatives
254

255
### vs. Shell Background Jobs (`&`)
256

257
**Parallelshell advantages:**
258
- Cross-platform (works on Windows)
259
- Automatic cleanup when processes fail
260
- Waits for all processes to complete
261
- Proper exit code handling
262
- Unified output handling
263
- Graceful Ctrl+C behavior
264

265
### vs. GNU Parallel
266

267
**Parallelshell advantages:**
268
- npm package (easier integration with Node.js projects)
269
- Simpler interface for basic parallel execution
270
- Better integration with npm scripts and development workflows
271

272
**GNU Parallel advantages:**
273
- More advanced features and options
274
- Better for complex data processing workflows