Google ZX Scripting

Use this skill when writing scripts with Google's zx library — the tool that makes shell scripting with JavaScript/TypeScript productive and safe. Read only the reference file(s) needed for the task.

Quick Start

All zx scripts use the lite entry point for portability. Scripts are standalone .mjs files — no project setup required.

#!/usr/bin/env npx zx

import { $, fs, path, glob, chalk } from 'zx/core';

const files = await glob('src/**/*.ts');
await $`eslint ${files}`;

Run directly:

chmod +x script.mjs && ./script.mjs
# or
npx zx script.mjs

Critical Rules

1. Always use zx/core — import from zx/core (the lite bundle), never bare zx. This avoids the heavy CLI wrapper and keeps scripts lean and embeddable.
2. Template literals auto-escape — interpolated values in $`...` are automatically shell-quoted. Never manually quote interpolated variables: $`echo ${userInput}` is safe, $`echo "${userInput}"` double-quotes and may break.
3. Arrays expand correctly — $`cmd ${arrayOfArgs}` expands each element as a separate quoted argument. Use this for flags, file lists, etc.
4. Non-zero exits throw — by default, a failed command throws ProcessOutput as an error. Use nothrow option or .nothrow() to suppress when you expect failures (e.g., grep returning no matches).
5. Use within() for isolation — within() creates an async scope with its own $.cwd, $.env, and other settings. Essential for parallel tasks that need different working directories.
6. Pipe with .pipe() — use $`cmd1`.pipe($`cmd2`) instead of shell pipes. This keeps each process managed by zx.
7. Prefer zx builtins over shell commands — use glob() instead of find, fs instead of cat/cp/mv, fetch() instead of curl. These are cross-platform and return proper JS types.
8. cd() is global — cd() changes $.cwd for ALL subsequent commands. Use within() or $({cwd: '/path'}) for scoped directory changes.
9. Scripts must be .mjs — use .mjs extension for top-level await support without bundler config.

Reference Map

Need	File
$, ProcessPromise, ProcessOutput, configuration, piping, streams	references/core-api.md
Ad-hoc scripts, CLI tools, build scripts, deployment, project scaffolding	references/scripting-patterns.md
File processing, data pipelines, batch ops, AI scripts, log analysis	references/processing-recipes.md

Task Routing

• Writing a quick one-off command or shell automation -> references/scripting-patterns.md
• Building a build/deploy/CI script -> references/scripting-patterns.md
• Processing files, data, logs, or batch operations -> references/processing-recipes.md
• Need API details for $, pipes, streams, config -> references/core-api.md
• Combining multiple patterns (e.g., build + process) -> read both relevant files

Import Cheatsheet

// Core — always start here
import { $, fs, path, glob, chalk } from 'zx/core';

// Additional utilities (import individually as needed)
import { spinner, retry, question, echo, sleep, within,
         stdin, tmpdir, tmpfile, which, ps, kill,
         quote, YAML, argv, fetch } from 'zx/core';

Conventions for Generated Scripts

1. Shebang line: Always include #!/usr/bin/env npx zx as the first line
2. Error handling: Wrap top-level logic in a main function with try/catch, or use $.nothrow selectively
3. Output: Use chalk for colored terminal output — green for success, red for errors, yellow for warnings, dim for secondary info
4. Progress: Use spinner() for long-running operations in interactive contexts
5. Arguments: Use argv (pre-parsed minimist) for CLI argument handling
6. Temp files: Use tmpdir() and tmpfile() — they auto-clean on exit
7. Parallelism: Use Promise.all() with within() for parallel operations that need isolation