#!/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 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.

npm i -g zx

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

When using zx via the executable or a shebang, all of the functions ($, cd, fetch, etc) are available straight away without any imports.

Executes a given string using the exec function from the child_process package and returns Promise<ProcessOutput>.

let count = parseInt(await $`ls -1 | wc -l`)
console.log(`Files count: ${count}`)

For example, to upload files in parallel:

let hosts = [...]
await Promise.all(hosts.map(host =>
  $`rsync -azP ./src ${host}:/var/www`  
))

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 ProcessOutput {
  readonly exitCode: number
  readonly stdout: string
  readonly stderr: string
  toString(): string
}

Changes the current working directory.

cd('/tmp')
await $`pwd` // outputs /tmp

A wrapper around the node-fetch package.

let resp = await fetch('https://wttr.in')
if (resp.ok) {
  console.log(await resp.text())
}

A wrapper around the readline package.

type QuestionOptions = { choices: string[] }

function question(query?: string, options?: QuestionOptions): Promise<string>

Usage:

let username = await question('What is your username? ')
let token = await question('Choose env variable: ', {
  choices: Object.keys(process.env)
})

A wrapper around the setTimeout function.

function sleep(ms: number): Promise<void>

Usage:

await sleep(1000)

The chalk package is available without importing inside scripts.

console.log(chalk.blue('Hello world!'))

The fs package is available without importing inside scripts. It is asyncronous by default.

let content = await fs.readFile('./package.json')

The os package is available without importing inside scripts.

await $`cd ${os.homedir()} && mkdir example`

Specifies what shell is used. Default is which bash.

$.shell = '/usr/bin/bash'

Specifies the command what will be prefixed to all commands run.

Default is set -euo pipefail;.

Specifies a function what will be used for escaping special characters during command substitution.

Default is the shq package.

Specifies verbosity. Default is true.

Verbose mode prints all executed commands along with their outputs. The is the same as using set -x in Bash.

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).

It is possible to make use of $ and other functions via explicit imports:

#!/usr/bin/env node
import {$} from 'zx'
await $`date`

process.env.FOO = 'bar'
await $`echo $FOO`

If the argument to the zx executable starts with https://, the file will be downloaded and executed.

zx https://medv.io/example-script.mjs

Apache-2.0

Disclaimer: This is not an officially supported Google product.