---

name: zx description: Comprehensive guide for writing shell scripts with Google zx — a tool for writing better scripts using JavaScript/TypeScript. Use when writing, debugging, or refactoring zx scripts (.mjs, .js, .ts files using zx), executing shell commands from JavaScript, working with ProcessPromise/ProcessOutput APIs, piping streams, configuring zx options, or using zx CLI. Do NOT use for general Node.js questions unrelated to shell scripting.

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