#!/usr/bin/env zx
await $`cat package.json | grep name`
let branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`
await Promise.all([
$`sleep 1; echo 1`,
$`sleep 2; echo 2`,
$`sleep 3; echo 3`,
])
let name = 'foo bar'
await $`mkdir /tmp/${name}`
Bash is great, but when it comes to writing more complex scripts,
many people prefer a more convenient programming language.
JavaScript is a perfect choice, but the Node.js standard library
requires additional hassle before using. The zx
package provides
useful wrappers around child_process
, escapes arguments and
gives sensible defaults.
npm i -g zx
Requirement: Node version >= 16.0.0
$ · cd() · fetch() · question() · sleep() · echo() · stdin() · within() · retry() · spinner() · chalk · fs · os · path · glob · yaml · minimist · which · __filename · __dirname · require()
For running commands on remote hosts, see webpod.
Write your scripts in a file with an .mjs
extension in order to
use await
at the top level. If you prefer the .js
extension,
wrap your scripts in something like void async function () {...}()
.
Add the following shebang to the beginning of your zx
scripts:
#!/usr/bin/env zx
Now you will be able to run your script like so:
chmod +x ./script.mjs
./script.mjs
Or via the zx
executable:
zx ./script.mjs
All functions ($
, cd
, fetch
, etc) are available straight away
without any imports.
Or import globals explicitly (for better autocomplete in VS Code).
import 'zx/globals'
Executes a given command using the spawn
func
and returns ProcessPromise
.
Everything passed through ${...}
will be automatically escaped and quoted.
let name = 'foo & bar'
await $`mkdir ${name}`
There is no need to add extra quotes. Read more about it in quotes.
You can pass an array of arguments if needed:
let flags = [
'--oneline',
'--decorate',
'--color',
]
await $`git log ${flags}`
If the executed program returns a non-zero exit code,
ProcessOutput
will be thrown.
try {
await $`exit 1`
} catch (p) {
console.log(`Exit code: ${p.exitCode}`)
console.log(`Error: ${p.stderr}`)
}
class ProcessPromise extends Promise<ProcessOutput> {
stdin: Writable
stdout: Readable
stderr: Readable
exitCode: Promise<number>
pipe(dest): ProcessPromise
kill(): Promise<void>
nothrow(): this
quiet(): this
}
Read more about the ProcessPromise.
class ProcessOutput {
readonly stdout: string
readonly stderr: string
readonly signal: string
readonly exitCode: number
toString(): string // Combined stdout & stderr.
}
The output of the process is captured as-is. Usually, programs print a new
line \n
at the end.
If ProcessOutput
is used as an argument to some other $
process,
zx will use stdout and trim the new line.
let date = await $`date`
await $`echo Current date is ${date}.`
Changes the current working directory.
cd('/tmp')
await $`pwd` // => /tmp
Like echo
, in addition to string
arguments, cd
accepts and trims
trailing newlines from ProcessOutput
enabling common idioms like:
cd(await $`mktemp -d`)
A wrapper around the node-fetch package.
let resp = await fetch('https://medv.io')
A wrapper around the readline package.
let bear = await question('What kind of bear is best? ')
A wrapper around the setTimeout
function.
await sleep(1000)
A console.log()
alternative which can take ProcessOutput.
let branch = await $`git branch --show-current`
echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)
Returns the stdin as a string.
let content = JSON.parse(await stdin())
Creates a new async context.
await $`pwd` // => /home/path
within(async () => {
cd('/tmp')
setTimeout(async () => {
await $`pwd` // => /tmp
}, 1000)
})
await $`pwd` // => /home/path
await $`node --version` // => v20.2.0
let version = await within(async () => {
$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; nvm use 16;'
return $`node --version`
})
echo(version) // => v16.20.0
Retries a callback for a few times. Will return after the first successful attempt, or will throw after specifies attempts count.
let p = await retry(10, () => $`curl https://medv.io`)
// With a specified delay between attempts.
let p = await retry(20, '1s', () => $`curl https://medv.io`)
// With an exponential backoff.
let p = await retry(30, expBackoff(), () => $`curl https://medv.io`)
Starts a simple CLI spinner.
await spinner(() => $`long-running command`)
// With a message.
await spinner('working...', () => $`sleep 99`)
The following packages are available without importing inside scripts.
The chalk package.
console.log(chalk.blue('Hello world!'))
The fs-extra package.
let {version} = await fs.readJson('./package.json')
The os package.
await $`cd ${os.homedir()} && mkdir example`
The path package.
await $`mkdir ${path.join(basedir, 'output')}`
The globby package.
let packages = await glob(['package.json', 'packages/*/package.json'])
The yaml package.
console.log(YAML.parse('foo: bar').foo)
The minimist package available
as global const argv
.
if (argv.someFlag) {
echo('yes')
}
The which package.
let node = await which('node')
Specifies what shell is used. Default is which bash
.
$.shell = '/usr/bin/bash'
Or use a CLI argument: --shell=/bin/bash
Specifies a spawn
api. Defaults to require('child_process').spawn
.
Specifies the command that will be prefixed to all commands run.
Default is set -euo pipefail;
for bash, and ''
for powershell.
Or use a CLI argument: --prefix='set -e;'
Same as $.prefix
but applied after the all commands.
Default is ''
for bash, and ; exit $LastExitCode
for powershell.
Or use a CLI argument: --postfix='; exit $LastExitCode'
Specifies a function for escaping special characters during command substitution.
Specifies verbosity. Default is true
.
In verbose mode, zx
prints all executed commands alongside with their
outputs.
Or use the CLI argument --quiet
to set $.verbose = false
.
Specifies an environment variables map.
Defaults to process.env
.
Specifies a current working directory of all processes created with the $
.
The cd() func changes only process.cwd()
and if no $.cwd
specified,
all $
processes use process.cwd()
by default (same as spawn
behavior).
Specifies a logging function.
import { LogEntry, log } from 'zx/core'
$.log = (entry: LogEntry) => {
switch (entry.kind) {
case 'cmd':
// for example, apply custom data masker for cmd printing
process.stderr.write(masker(entry.cmd))
break
default:
log(entry)
}
}
In ESM modules, Node.js does not provide
__filename
and __dirname
globals. As such globals are really handy in
scripts,
zx
provides these for use in .mjs
files (when using the zx
executable).
In ESM
modules, the require()
function is not defined.
The zx
provides require()
function, so it can be used with imports in .mjs
files (when using zx
executable).
let {version} = require('./package.json')
process.env.FOO = 'bar'
await $`echo $FOO`
When passing an array of values as an argument to $
, items of the array will
be escaped
individually and concatenated via space.
Example:
let files = [...]
await $`tar cz ${files}`
It is possible to make use of $
and other functions via explicit imports:
#!/usr/bin/env node
import { $ } from 'zx'
await $`date`
If script does not have a file extension (like .git/hooks/pre-commit
), zx
assumes that it is
an ESM
module.
The zx
can execute scripts written as markdown:
zx docs/markdown.md
import { $ } from 'zx'
// Or
import 'zx/globals'
void async function () {
await $`ls -la`
}()
Set "type": "module"
in package.json
and "module": "ESNext"
in tsconfig.json.
If the argument to the zx
executable starts with https://
, the file will be
downloaded and executed.
zx https://medv.io/game-of-life.js
The zx
supports executing scripts from stdin.
zx << 'EOF'
await $`pwd`
EOF
Evaluate the following argument as a script.
cat package.json | zx --eval 'let v = JSON.parse(await stdin()).version; echo(v)'
// script.mjs:
import sh from 'tinysh'
sh.say('Hello, world!')
Add --install
flag to the zx
command to install missing dependencies
automatically.
zx --install script.mjs
You can also specify needed version by adding comment with @
after
the import.
import sh from 'tinysh' // @^1
The zx
uses webpod to execute commands on
remote hosts.
import { ssh } from 'zx'
await ssh('user@host')`echo Hello, world!`
By default child_process
does not include aliases and bash functions.
But you are still able to do it by hand. Just attach necessary directives
to the $.prefix
.
$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
await $`nvm -v`
The default GitHub Action runner comes with npx
installed.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build
env:
FORCE_COLOR: 3
run: |
npx zx <<'EOF'
await $`...`
EOF
Impatient early adopters can try the experimental zx versions.
But keep in mind: these builds are
npm i zx@dev
npx zx@dev --install --quiet <<< 'import _ from "lodash" /* 4.17.15 */; console.log(_.VERSION)'
Disclaimer: This is not an officially supported Google product.