Zx — Write Better Shell Scripts with JavaScript
Overview
zx is Google's tool for writing shell scripts in JavaScript/TypeScript. It wraps child_process, auto-escapes arguments, and provides sensible defaults — giving you the power of the JavaScript ecosystem in your scripts.
#!/usr/bin/env zx
await $`cat package.json | grep name`
const branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`
const name = 'foo & bar'
await $`mkdir /tmp/${name}` // No quotes needed — auto-escaped
Bash is great for simple tasks, but when scripts grow complex, a full programming language helps. zx adds helpful wrappers around child_process, escapes arguments, and gives sensible defaults. Think: bash + JavaScript in one script.
Triggers
Also triggers when users ask about running shell commands in JavaScript, converting bash scripts to zx, executing remote scripts, Markdown scripts, or TypeScript shell scripts.
Quick Start
npm install zx
Write scripts as .mjs files (supports top-level await). Add #!/usr/bin/env zx shebang or run via CLI:
zx ./script.mjs # Direct execution
npx zx ./script.mjs # Via npx
node --import zx/globals # As Node.js loader
All functions ($, cd, fetch, etc.) are globally available in zx scripts without imports. For explicit imports (better VS Code autocomplete):
import 'zx/globals'
Core Concepts
$`command` — Execute Shell Commands
The tagged template literal is the heart of zx. Everything in ${...} is auto-escaped and quoted.
// Async (standard) — returns ProcessPromise
const output = await $`ls -la`
// Sync variant — returns ProcessOutput directly
const dir = $.sync`pwd`
// Arrays are flattened
const flags = ['--oneline', '--decorate', '--color']
await $`git log ${flags}`
// Non-zero exit codes throw ProcessOutput
try {
await $`exit 1`
} catch (p) {
console.log(`Exit: ${p.exitCode}, Error: ${p.stderr}`)
}
Preset Configuration with $({...})
Create custom $ instances with preset options — chainable and composable:
const $$ = $({ verbose: false, env: { NODE_ENV: 'production' } })
const pwd = $$.sync`pwd`
// Presets are chainable
const $1 = $({ nothrow: true })
const $2 = $1({ sync: true }) // Both nothrow + sync applied
ProcessPromise & ProcessOutput
$`cmd` ProcessPromise (extends Promise)
├── .pipe() Stream piping
├── .kill() Terminate process
├── .text() Output as string
├── .json() Output as parsed JSON
├── .lines() Output split by lines
├── .nothrow() Suppress errors for this command
├── .quiet() Suppress output for this command
├── .timeout() Auto-kill after duration
├── .stdio() Configure I/O
├── .exitCode Promise<exit code>
├── .stdout Readable stream
├── .stderr Readable stream
├── .stdin Writable stream
├── .pid / .cmd Process metadata
└── await → ProcessOutput
├── .stdout string
├── .stderr string
├── .exitCode number
├── .signal string|null
├── .text() / .json() / .lines() / .buffer() / .blob()
└── .ok boolean (when nothrow)
Decision Tree
When writing zx scripts, use this decision tree:
| Goal | Approach |
|---|---|
| Run a command | await $`cmd` |
| Run synchronously | $.sync`cmd` |
| Pipe output | .pipe($`next`) / .pipe('file.txt') |
| Handle errors gracefully | $({nothrow: true}) / .nothrow() |
| Set timeout | $({timeout: '30s'}) / .timeout('30s') |
| Parse JSON output | (await $`cmd`).json() |
| Real-time streaming | for await (const line of $`cmd`) |
| Retry on failure | retry(5, () => $`cmd`) |
| User prompt | question('Name: ') |
| Progress indicator | await spinner('Working...', () => $`cmd`) |
| Change directory | cd('/path') or within(() => { $.cwd = '/tmp' }) |
| Temp files/dirs | tmpfile() / tmpdir() |
| Parse CLI args | argv.flag or minimist(process.argv.slice(2)) |
| Load .env file | dotenv.config('.env') |
Writing Effective zx Scripts
Parallel Execution
const results = await Promise.all([
$`sleep 1; echo 1`,
$`sleep 2; echo 2`,
$`sleep 3; echo 3`,
])
Error Handling with nothrow
$.nothrow = true
const repos = ['zx', 'webpod']
const clones = repos.map(n => $`git clone https://github.com/google/${n}`)
const results = await Promise.all(clones)
const errors = results.filter(o => !o.ok).map(o => o.stderr.trim())
console.log('Errors:', errors.join('\n'))
Stream Piping
// Chain commands like bash pipes
const greeting = await $`printf "hello"`
.pipe($`awk '{printf $1", world!"}'`)
.pipe($`tr '[a-z]' '[A-Z]'`)
// Pipe to file
await $`echo "Hello!"`.pipe('/tmp/output.txt')
// Real-time output to terminal
await $`echo 1; sleep 1; echo 2; sleep 1; echo 3`.pipe(process.stdout)
Stream Splitting & Merging
// Split one source to multiple consumers
const p = $`some-command`
const [o1, o2] = await Promise.all([
p.pipe`log`,
p.pipe`extract`,
])
// Merge multiple sources
const $h = $({ halt: true })
const p1 = $`echo foo`
const p2 = $h`echo a && sleep 0.1 && echo b`
const p3 = $h`echo c && sleep 0.1 && echo d`
const cat = $h`cat`
p1.pipe(cat); p2.pipe(cat); p3.pipe(cat)
await cat.run()
Output Formatters
const p = $`echo '{"foo":"bar"}\nline2'`
await p.json() // { foo: 'bar' }
await p.lines() // ['{"foo":"bar"}', 'line2']
await p.text() // '{"foo":"bar"}\nline2\n'
Async Iteration
for await (const line of $`git log --oneline --max-count=5`) {
console.log(line)
}
Shell Configuration
zx defaults to bash. Switch shells as needed:
import { useBash, usePowerShell, usePwsh } from 'zx'
usePowerShell() // PowerShell.exe
usePwsh() // PowerShell v7+
useBash() // Back to bash
// Manual override
$.shell = '/bin/zsh'
On Windows, consider using WSL or Git Bash for bash support, or switch to PowerShell via usePowerShell().
Built-in Helpers Summary
| Helper | Purpose | Example |
|---|---|---|
cd() | Change directory | cd('/tmp') |
fetch() | HTTP requests, supports .pipe() | fetch('https://api.example.com') |
question() | Interactive user input | question('Name: ') |
sleep() | Delay execution | await sleep(1000) |
echo() | Print to stdout | echo`Status: ${p}` |
stdin() | Read stdin | JSON.parse(await stdin()) |
within() | Isolated async config context | within(() => { $.cwd = '/tmp' }) |
retry() | Retry with delay/backoff | retry(5, () => $curl url) |
spinner() | CLI progress indicator | await spinner(() => $long-cmd) |
glob() | File glob matching (globby) | glob('**/*.js') |
which() | Find executable path | await which('node') |
ps | Cross-platform process list | ps.lookup({ command: 'node' }) |
tmpdir() | Temp directory | tmpdir('sub') |
tmpfile() | Temp file | tmpfile('f.txt', 'content') |
argv | Parsed CLI arguments | argv.verbose |
dotenv | .env file loading | dotenv.config('.env') |
Exposed npm packages: chalk (colors), fs (fs-extra), os, path, YAML (yaml), minimist.
Resources
- references/api.md — Full API reference:
$options,cd(),fetch(),question(),sleep(),echo(),stdin(),within(),retry(),spinner(),glob(),which(),ps,kill(),tmpdir(),tmpfile(),minimist,argv,chalk,fs,os,path,YAML,dotenv,quote(),useBash(),usePowerShell(),usePwsh() - references/configuration.md — All
$.options:shell,prefix,postfix,quote,verbose,quiet,env,cwd,timeout,nothrow,detached,preferLocal,spawn,kill,log,input,signal,stdio,halt,delimiter,defaults - references/cli.md — CLI usage: flags, env vars, Markdown scripts, remote scripts, stdin execution, REPL mode
- references/process.md — ProcessPromise/ProcessOutput lifecycle, piping, killing, aborting, output formatters, stream handling