0
# Shell Execution
1

2
Core shell command execution with the `$` function, configuration options, and command composition capabilities.
3

4
## Capabilities
5

6
### Dollar Function ($)
7

8
The main shell execution function that serves as both a template literal function and configuration object.
9

10
```typescript { .api }
11
/**
12
 * Execute shell commands using template literals
13
 * @param pieces - Template string parts
14
 * @param args - Interpolated arguments (automatically escaped)
15
 * @returns ProcessPromise for async execution or ProcessOutput for sync
16
 */
17
interface Shell<S = false, R = S extends true ? ProcessOutput : ProcessPromise> {
18
  (pieces: TemplateStringsArray, ...args: any[]): R;
19
  <O extends Partial<Options>>(opts: O): Shell;
20
  sync: Shell<true>;
21
}
22

23
type $ = Shell & Options;
24
declare const $: $;
25
```
26

27
**Basic Usage:**
28

29
```typescript
30
import { $ } from "zx";
31

32
// Execute commands
33
const result = await $`echo "Hello World"`;
34
console.log(result.stdout); // "Hello World\n"
35

36
// With interpolated arguments (automatically escaped)
37
const dir = "my folder";
38
await $`mkdir ${dir}`; // Safe even with spaces/special chars
39

40
// Sync execution
41
const output = $.sync`pwd`;
42
console.log(output.stdout);
43
```
44

45
### Configuration Options
46

47
Configure shell behavior by calling $ as a function with options.
48

49
```typescript { .api }
50
interface Options {
51
  /** Working directory for command execution */
52
  cwd?: string;
53
  /** Environment variables */
54
  env?: NodeJS.ProcessEnv;
55
  /** Shell to use (true for default, string for specific shell) */
56
  shell?: string | true;
57
  /** Standard I/O configuration */
58
  stdio?: StdioOptions;
59
  /** Enable verbose output */
60
  verbose?: boolean;
61
  /** Suppress output */
62
  quiet?: boolean;
63
  /** Don't throw on non-zero exit codes */
64
  nothrow?: boolean;
65
  /** Command timeout */
66
  timeout?: Duration;
67
  /** Timeout signal */
68
  timeoutSignal?: NodeJS.Signals;
69
  /** Kill signal */
70
  killSignal?: NodeJS.Signals;
71
  /** Command prefix */
72
  prefix?: string;
73
  /** Command postfix */
74
  postfix?: string;
75
  /** Run as detached process */
76
  detached?: boolean;
77
  /** Prefer local binaries */
78
  preferLocal?: boolean | string | string[];
79
  /** Synchronous execution */
80
  sync?: boolean;
81
  /** Input for command */
82
  input?: string | Buffer | Readable | ProcessOutput | ProcessPromise;
83
  /** Abort signal */
84
  signal?: AbortSignal;
85
  /** Abort controller */
86
  ac?: AbortController;
87
}
88
```
89

90
**Configuration Examples:**
91

92
```typescript
93
// Quiet execution
94
const result = await $({ quiet: true })`git status`;
95

96
// Custom working directory
97
const files = await $({ cwd: '/tmp' })`ls -la`;
98

99
// With timeout
100
const output = await $({ timeout: '5s' })`long-running-command`;
101

102
// Multiple options
103
const result = await $({
104
  quiet: true,
105
  nothrow: true,
106
  cwd: '/project',
107
  env: { NODE_ENV: 'production' }
108
})`npm test`;
109
```
110

111
### Directory Management
112

113
Navigate and manage working directories within scripts.
114

115
```typescript { .api }
116
/**
117
 * Change current working directory
118
 * @param dir - Directory path or ProcessOutput containing path
119
 */
120
function cd(dir: string | ProcessOutput): void;
121

122
/**
123
 * Control directory synchronization behavior
124
 * @param flag - Whether to sync process.cwd() with internal state
125
 */
126
function syncProcessCwd(flag?: boolean): void;
127

128
/**
129
 * Execute callback with temporary configuration
130
 * @param callback - Function to execute with current $ configuration
131
 * @returns Result of callback execution
132
 */
133
function within<R>(callback: () => R): R;
134
```
135

136
**Usage:**
137

138
```typescript
139
import { $, cd, within } from "zx";
140

141
// Change directory
142
cd('/tmp');
143
await $`pwd`; // Shows /tmp
144

145
// Temporary configuration
146
const result = await within(() => {
147
   $.verbose = false;
148
   return $`echo "quiet"`;
149
});
150
```
151

152
### Default Configuration
153

154
Access and modify default options for all shell executions.
155

156
```typescript { .api }
157
/**
158
 * Default options applied to all $ calls
159
 */
160
declare const defaults: Options;
161

162
/**
163
 * Resolve configuration defaults with environment variables
164
 * @param defs - Default options
165
 * @param prefix - Environment variable prefix
166
 * @param env - Environment variables to read from
167
 * @param allowed - Set of allowed option keys
168
 * @returns Resolved options
169
 */
170
function resolveDefaults(
171
  defs?: Options,
172
  prefix?: string,
173
  env?: NodeJS.ProcessEnv,
174
  allowed?: Set<string>
175
): Options;
176
```
177

178
**Usage:**
179

180
```typescript
181
import { $, defaults } from "zx";
182

183
// Modify global defaults
184
defaults.verbose = false;
185
defaults.shell = '/bin/bash';
186

187
// All subsequent $ calls use these defaults
188
await $`echo "uses defaults"`;
189
```
190

191
### Process Control
192

193
Kill processes and manage process lifecycle.
194

195
```typescript { .api }
196
/**
197
 * Kill a process by PID
198
 * @param pid - Process ID to kill
199
 * @param signal - Signal to send (default: SIGTERM)
200
 */
201
function kill(pid: number, signal?: NodeJS.Signals): Promise<void>;
202
```
203

204
**Usage:**
205

206
```typescript
207
import { $, kill } from "zx";
208

209
const proc = $`sleep 100`;
210
const pid = proc.pid;
211

212
if (pid) {
213
  await kill(pid, 'SIGKILL');
214
}
215
```
216

217
## Types
218

219
```typescript { .api }
220
type Duration = string | number;
221

222
type StdioOptions = 'pipe' | 'ignore' | 'inherit' | Array<'pipe' | 'ignore' | 'inherit' | Stream | number | null | undefined>;
223

224
interface TemplateStringsArray extends ReadonlyArray<string> {
225
  readonly raw: ReadonlyArray<string>;
226
}
227
```