0
# Child Process Operations
1

2
Execute shell commands and spawn processes with promise support. Provides modern async/await compatibility for Node.js child_process operations.
3

4
## Capabilities
5

6
### Command Execution
7

8
Execute shell commands with promise support.
9

10
```javascript { .api }
11
/**
12
 * Execute a shell command in a new process
13
 * @param command - Command string to execute
14
 * @param options - Execution options
15
 * @returns Promise resolving to stdout string
16
 */
17
function exec(command, options): Promise<string>;
18

19
/**
20
 * Execute a file directly without shell interpretation
21
 * @param file - Path to executable file
22
 * @param args - Array of arguments to pass to executable
23
 * @param options - Execution options
24
 * @returns Promise resolving to stdout string
25
 */
26
function execFile(file, args, options): Promise<string>;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
const { exec, execFile } = require('mz/child_process');
33

34
// Execute shell commands
35
async function runCommands() {
36
  try {
37
    // Get Node.js version
38
    const nodeVersion = await exec('node --version');
39
    console.log('Node version:', nodeVersion.trim());
40
    
41
    // List files in current directory
42
    const files = await exec('ls -la');
43
    console.log('Directory contents:', files);
44
    
45
    // Execute with options
46
    const result = await exec('echo "Hello World"', {
47
      cwd: '/tmp',
48
      env: { ...process.env, CUSTOM_VAR: 'value' }
49
    });
50
    console.log('Command output:', result);
51
    
52
  } catch (error) {
53
    console.error('Command failed:', error.message);
54
    // Error object contains additional properties:
55
    // - error.code: exit code
56
    // - error.signal: signal that terminated the process
57
    // - error.stdout: stdout output
58
    // - error.stderr: stderr output
59
  }
60
}
61

62
// Execute files directly
63
async function runExecutable() {
64
  try {
65
    // Execute Node.js directly with arguments
66
    const output = await execFile('node', ['--version']);
67
    console.log('Node version:', output.trim());
68
    
69
    // Execute with options
70
    const result = await execFile('/bin/echo', ['Hello', 'World'], {
71
      cwd: '/tmp'
72
    });
73
    console.log('Echo output:', result);
74
    
75
  } catch (error) {
76
    console.error('Execution failed:', error);
77
  }
78
}
79

80
// Callback support is still available
81
exec('pwd', (err, stdout, stderr) => {
82
  if (err) {
83
    console.error('Error:', err);
84
  } else {
85
    console.log('Current directory:', stdout.trim());
86
  }
87
});
88
```
89

90
## Error Handling
91

92
Both `exec` and `execFile` will reject with an error object when:
93
- The command fails to execute
94
- The process exits with a non-zero exit code
95
- The process is terminated by a signal
96

97
The error object contains additional properties:
98
- `code`: Process exit code (number)
99
- `signal`: Signal that terminated the process (string)
100
- `stdout`: Standard output (string)
101
- `stderr`: Standard error output (string)
102

103
```javascript
104
const { exec } = require('mz/child_process');
105

106
async function handleCommandErrors() {
107
  try {
108
    await exec('nonexistent-command');
109
  } catch (error) {
110
    console.log('Exit code:', error.code);
111
    console.log('Signal:', error.signal);
112
    console.log('Stdout:', error.stdout);
113
    console.log('Stderr:', error.stderr);
114
  }
115
}
116
```
117

118
## Options
119

120
Both functions accept an options object with the following properties:
121

122
```javascript { .api }
123
interface ExecOptions {
124
  /** Current working directory for the command */
125
  cwd?: string;
126
  /** Environment variables */
127
  env?: object;
128
  /** Character encoding for stdout/stderr */
129
  encoding?: string;
130
  /** Shell to execute the command with (exec only) */
131
  shell?: string;
132
  /** Timeout in milliseconds */
133
  timeout?: number;
134
  /** Largest amount of data in bytes allowed on stdout/stderr */
135
  maxBuffer?: number;
136
  /** Kill signal to use when timeout is reached */
137
  killSignal?: string;
138
  /** User ID to run the command as */
139
  uid?: number;
140
  /** Group ID to run the command as */
141
  gid?: number;
142
  /** Whether to run in detached mode */
143
  detached?: boolean;
144
  /** Whether to create new console window (Windows only) */
145
  windowsVerbatimArguments?: boolean;
146
}
147
```
148

149
## Implementation Notes
150

151
- Uses `thenify-all` to wrap native child_process methods
152
- Maintains complete compatibility with native child_process behavior
153
- Supports both promise and callback interfaces
154
- Error objects include all standard child_process error properties
155
- `exec` uses shell interpretation, `execFile` executes directly for better security