README
🐚 zx
#!/usr/bin/env zx
await
npm:zxe | Skypack
cat package.json | grep name`
let branch = await
npm:zxe | Skypack
git branch --show-current`
await
npm:zxe | Skypack
dep deploy --branch=${branch}`
await Promise.all([
npm:zxe | Skypack
sleep 1; echo 1`,
npm:zxe | Skypack
sleep 2; echo 2`,
npm:zxe | Skypack
sleep 3; echo 3`,
])
let name = 'foo bar'
await
npm:zxe | Skypack
mkdir /tmp/${name}`
Bash is great, but when it comes to writing scripts,
people usually choose a more convenient programming language.
JavaScript is a perfect choice, but standard Node.js library
requires additional hassle before using. The zx
package provides
useful wrappers around child_process
, escapes arguments and
gives sensible defaults.
Install
npm i -g zx
Documentation
Write your scripts in a file with .mjs
extension in order to
be able to use await
on 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.
npm:zxe | Skypack
command`
Executes a given string using the spawn
function from the
child_process
package and returns ProcessPromise<ProcessOutput>
.
let count = parseInt(await
npm:zxe | Skypack
ls -1 | wc -l`)
console.log(`Files count: ${count}`)
For example, to upload files in parallel:
let hosts = [...]
await Promise.all(hosts.map(host =>
npm:zxe | Skypack
rsync -azP ./src ${host}:/var/www`
))
If the executed program returns a non-zero exit code,
ProcessOutput
will be thrown.
try {
await
npm:zxe | Skypack
exit 1`
} catch (p) {
console.log(`Exit code: ${p.exitCode}`)
console.log(`Error: ${p.stderr}`)
}
ProcessPromise
class ProcessPromise<T> extends Promise<T> {
readonly stdin: Writable
readonly stdout: Readable
readonly stderr: Readable
readonly exitCode: Promise<number>
pipe(dest): ProcessPromise<T>
}
The pipe()
method can be used to redirect stdout:
await
npm:zxe | Skypack
cat file.txt`.pipe(process.stdout)
Read more about pipelines.
ProcessOutput
class ProcessOutput {
readonly stdout: string
readonly stderr: string
readonly exitCode: number
toString(): string
}
Functions
cd()
Changes the current working directory.
cd('/tmp')
await
npm:zxe | Skypack
pwd` // outputs /tmp
fetch()
A wrapper around the node-fetch package.
let resp = await fetch('http://wttr.in')
if (resp.ok) {
console.log(await resp.text())
}
question()
A wrapper around the readline package.
Usage:
let bear = await question('What kind of bear is best? ')
let token = await question('Choose env variable: ', {
choices: Object.keys(process.env)
})
In second argument, array of choices for Tab autocompletion can be specified.
function question(query?: string, options?: QuestionOptions): Promise<string>
type QuestionOptions = { choices: string[] }
sleep()
A wrapper around the setTimeout
function.
await sleep(1000)
nothrow()
Changes behavior of $
to not throw an exception on non-zero exit codes.
function nothrow<P>(p: P): P
Usage:
await nothrow(
npm:zxe | Skypack
grep something from-file`)
// Inside a pipe():
await
npm:zxe | Skypack
find ./examples -type f -print0`
.pipe(nothrow(
npm:zxe | Skypack
xargs -0 grep something`))
.pipe(
npm:zxe | Skypack
wc -l`)
If only the exitCode
is needed, you can use the next code instead:
if (await
npm:zxe | Skypack
[[ -d path ]]`.exitCode == 0) {
...
}
// Equivalent of:
if ((await nothrow(
npm:zxe | Skypack
[[ -d path ]]`)).exitCode == 0) {
...
}
Packages
Next packages is available without importing inside scripts.
package chalk
The chalk package.
console.log(chalk.blue('Hello world!'))
package fs
The fs package.
let content = await fs.readFile('./package.json')
package os
The os package.
await
npm:zxe | Skypack
cd ${os.homedir()} && mkdir example`
Configuration
$.shell
Specifies what shell is used. Default is which bash
.
$.shell = '/usr/bin/bash'
$.prefix
Specifies the command that will be prefixed to all commands run.
Default is set -euo pipefail;
.
$.quote
Specifies a function for escaping special characters during command substitution.
Default is the shq package.
$.verbose
Specifies verbosity. Default is true
.
In verbose mode, the zx
prints all executed commands alongside with their
outputs.
Polyfills
& __filename__dirname
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).
require()
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')
FAQ
Passing env variables
process.env.FOO = 'bar'
await
npm:zxe | Skypack
echo $FOO`
Passing array of values
If array of values passed as argument to $
, items of the array will be escaped
individually and concatenated via space.
Example:
let files = [...]
await
npm:zxe | Skypack
tar cz ${files}`
Importing from other scripts
It is possible to make use of $
and other functions via explicit imports:
#!/usr/bin/env node
import {$} from 'zx'
await
npm:zxe | Skypack
date`
Scripts without extensions
If script does not have a file extension (like .git/hooks/pre-commit
), zx
assumes that it is an ESM
module.
Markdown scripts
The zx
can execute scripts written in markdown
(examples/markdown.md):
zx examples/markdown.md
TypeScript scripts
The zx
can compile .ts
scripts to .mjs
and execute them.
zx examples/typescript.ts
In TypeScript file include the zx
package to import types:
import 'zx'
Or reference the zx
package via:
/// <reference types="zx"/>
Example:
#!/usr/bin/env zx
import 'zx'
void async function () {
await
npm:zxe | Skypack
ls -la`
}()
Executing remote scripts
If the argument to the zx
executable starts with https://
, the file will be
downloaded and executed.
zx https://medv.io/example-script.mjs
License
Disclaimer: This is not an officially supported Google product.