zx

A tool for writing better scripts

CLI
google/zxzx

README

🐚 zx


  1. ``` js
  2. #!/usr/bin/env zx

  4. await $`cat package.json | grep name`

  6. let branch = await $`git branch --show-current`
  7. await $`dep deploy --branch=${branch}`

  9. await Promise.all([
  10.   $`sleep 1; echo 1`,
  11.   $`sleep 2; echo 2`,
  12.   $`sleep 3; echo 3`,
  13. ])

  15. let name = 'foo bar'
  16. await $`mkdir /tmp/${name}`
  17. ```

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.

Install


  1. ``` sh
  2. npm i -g zx
  3. ```

Requirement: Node version >= 16.0.0

Goods


$ · cd() · fetch() · question() · sleep() · echo() · stdin() · within() ·
chalk · fs · os · path · glob · yaml · minimist · which ·
__filename · __dirname · require()

Documentation


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:
  1. ``` sh
  2. #!/usr/bin/env zx
  3. ```

Now you will be able to run your script like so:
  1. ``` sh
  2. chmod +x ./script.mjs
  3. ./script.mjs
  4. ```

Or via the zx executable:

  1. ``` sh
  2. zx ./script.mjs
  3. ```

All functions ($, cd, fetch, etc) are available straight away
without any imports.

Or import globals explicitly (for better autocomplete in VS Code).

  1. ``` js
  2. import 'zx/globals'
  3. ```

`$command `


Executes a given command using the spawn func
and returns [ProcessPromise](#processpromise).

Everything passed through ${...} will be automatically escaped and quoted.

  1. ``` js
  2. let name = 'foo & bar'
  3. await $`mkdir ${name}`
  4. ```

There is no need to add extra quotes. Read more about it in
quotes.

You can pass an array of arguments if needed:

  1. ``` js
  2. let flags = [
  3.   '--oneline',
  4.   '--decorate',
  5.   '--color',
  6. ]
  7. await $`git log ${flags}`
  8. ```

If the executed program returns a non-zero exit code,
[ProcessOutput](#processoutput) will be thrown.

  1. ``` js
  2. try {
  3.   await $`exit 1`
  4. } catch (p) {
  5.   console.log(`Exit code: ${p.exitCode}`)
  6.   console.log(`Error: ${p.stderr}`)
  7. }
  8. ```

ProcessPromise


  1. ```ts
  2. class ProcessPromise extends Promise<ProcessOutput> {
  3.   stdin: Writable
  4.   stdout: Readable
  5.   stderr: Readable
  6.   exitCode: Promise<number>
  7.   pipe(dest): ProcessPromise
  8.   kill(): Promise<void>
  9.   nothrow(): this
  10.   quiet(): this
  11. }
  12. ```

Read more about the ProcessPromise.

ProcessOutput


  1. ```ts
  2. class ProcessOutput {
  3.   readonly stdout: string
  4.   readonly stderr: string
  5.   readonly signal: string
  6.   readonly exitCode: number
  7.   toString(): string // Combined stdout & stderr.
  8. }
  9. ```

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.

  1. ``` js
  2. let date = await $`date`
  3. await $`echo Current date is ${date}.`
  4. ```

Functions


cd()


Changes the current working directory.

  1. ``` js
  2. cd('/tmp')
  3. await $`pwd` // => /tmp
  4. ```

fetch()


A wrapper around the node-fetch package.

  1. ``` js
  2. let resp = await fetch('https://medv.io')
  3. ```

question()


A wrapper around the readline package.

  1. ``` js
  2. let bear = await question('What kind of bear is best? ')
  3. ```

sleep()


A wrapper around the setTimeout function.

  1. ``` js
  2. await sleep(1000)
  3. ```

echo()


A console.log() alternative which can take ProcessOutput.

  1. ``` js
  2. let branch = await $`git branch --show-current`

  4. echo`Current branch is ${branch}.`
  5. // or
  6. echo('Current branch is', branch)
  7. ```

stdin()


Returns the stdin as a string.

  1. ``` js
  2. let content = JSON.parse(await stdin())
  3. ```

within()


Creates a new async context.

  1. ``` js
  2. await $`pwd` // => /home/path

  4. within(async () => {
  5.   cd('/tmp')

  7.   setTimeout(async () => {
  8.     await $`pwd` // => /tmp
  9.   }, 1000)
  10. })

  12. await $`pwd` // => /home/path
  13. ```

  1. ``` js
  2. let version = await within(async () => {
  3.   $.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
  4.   await $`nvm use 16`
  5.   return $`node -v`
  6. })
  7. ```

Packages


The following packages are available without importing inside scripts.

chalk package


The chalk package.

  1. ``` js
  2. console.log(chalk.blue('Hello world!'))
  3. ```

fs package


The fs-extra package.

  1. ``` js
  2. let {version} = await fs.readJson('./package.json')
  3. ```

os package


The os package.

  1. ``` js
  2. await $`cd ${os.homedir()} && mkdir example`
  3. ```

path package


The path package.

  1. ``` js
  2. await $`mkdir ${path.join(basedir, 'output')}`
  3. ```

globby package


The globby package.

  1. ``` js
  2. let packages = await glob(['package.json', 'packages/*/package.json'])
  3. ```

yaml package


The yaml package.

  1. ``` js
  2. console.log(YAML.parse('foo: bar').foo)
  3. ```

minimist package


The minimist package available
as global const argv.

  1. ``` js
  2. if( argv.someFlag ){ echo('yes') }
  3. ```

which package


The which package.

  1. ``` js
  2. let node = await which('node')
  3. ```

Configuration


$.shell


Specifies what shell is used. Default is which bash.

  1. ``` js
  2. $.shell = '/usr/bin/bash'
  3. ```

Or use a CLI argument: --shell=/bin/bash

$.spawn


Specifies a spawn api. Defaults to require('child_process').spawn.

$.prefix


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

Default is set -euo pipefail;.

Or use a CLI argument: --prefix='set -e;'

$.quote


Specifies a function for escaping special characters during
command substitution.

$.verbose


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.

$.env


Specifies an environment variables map.

Defaults to process.env.

$.cwd


Specifies a current working directory of all processes created with the $.

The cd() func changes onlyprocess.cwd() and if no $.cwd specified,
all $ processes use process.cwd() by default (same as spawn behavior).

$.log


Specifies a logging function.

  1. ```ts
  2. import { LogEntry, log } from 'zx/core'

  4. $.log = (entry: LogEntry) => {
  5.   switch (entry.kind) {
  6.     case 'cmd':
  7.       // for example, apply custom data masker for cmd printing
  8.       process.stderr.write(masker(entry.cmd))
  9.       break
  10.     default:
  11.       log(entry)
  12.   }
  13. }
  14. ```

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

  1. ``` js
  2. let {version} = require('./package.json')
  3. ```

Experimental


The zx provides a few experimental functions. Please leave feedback about
those features in the discussion.
To enable new features via CLI pass --experimental flag.

retry()


Retries a callback for a few times. Will return after the first
successful attempt, or will throw after specifies attempts count.

  1. ``` js
  2. import { retry, expBackoff } from 'zx/experimental'

  4. let p = await retry(10, () => $`curl https://medv.io`)

  6. // With a specified delay between attempts.
  7. let p = await retry(20, '1s', () => $`curl https://medv.io`)

  9. // With an exponential backoff.
  10. let p = await retry(30, expBackoff(), () => $`curl https://medv.io`)
  11. ```

spinner()


Starts a simple CLI spinner.

  1. ``` js
  2. import { spinner } from 'zx/experimental'

  4. await spinner(() => $`long-running command`)

  6. // With a message.
  7. await spinner('working...', () => $`sleep 99`)
  8. ```

FAQ


Passing env variables


  1. ``` js
  2. process.env.FOO = 'bar'
  3. await $`echo $FOO`
  4. ```

Passing array of values


When passing an array of values as an argument to $, items of the array will be escaped
individually and concatenated via space.

Example:
  1. ``` js
  2. let files = [...]
  3. await $`tar cz ${files}`
  4. ```

Importing into other scripts


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

  1. ``` js
  2. #!/usr/bin/env node
  3. import {$} from 'zx'
  4. await $`date`
  5. ```

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 as markdown:

  1. ``` sh
  2. zx docs/markdown.md
  3. ```

TypeScript scripts


  1. ```ts
  2. import {$} from 'zx'
  3. // Or
  4. import 'zx/globals'

  6. void async function () {
  7.   await $`ls -la`
  8. }()
  9. ```

Set ["type": "module"](https://nodejs.org/api/packages.html#packages_type)
in package.json and ["module": "ESNext"](https://www.typescriptlang.org/tsconfig/#module)
in tsconfig.json.

Executing remote scripts


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

  1. ``` sh
  2. zx https://medv.io/game-of-life.js
  3. ```

Executing scripts from stdin


The zx supports executing scripts from stdin.

  1. ``` js
  2. zx <<'EOF'
  3. await $`pwd`
  4. EOF
  5. ```

Executing scripts via --eval


Evaluate the following argument as a script.

  1. ``` sh
  2. cat package.json | zx --eval 'let v = JSON.parse(await stdin()).version; echo(v)'
  3. ```

Installing dependencies via --install


  1. ``` js
  2. // script.mjs:
  3. import sh from 'tinysh'
  4. sh.say('Hello, world!')
  5. ```

Add --install flag to the zx command to install missing dependencies
automatically.

  1. ``` sh
  2. zx --install script.mjs
  3. ```

You can also specify needed version by adding comment with @ after
the import.

  1. ``` js
  2. import sh from 'tinysh' // @^1
  3. ```

Attaching a profile


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.

  1. ``` js
  2. $.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
  3. await $`nvm -v`
  4. ```

Using GitHub Actions


The default GitHub Action runner comes with npx installed.

  1. ```yaml
  2. jobs:
  3.   build:
  4.     runs-on: ubuntu-latest
  5.     steps:
  6.     - uses: actions/checkout@v3

  8.     - name: Build
  9.       env:
  10.         FORCE_COLOR: 3
  11.       run: |
  12.         npx zx <<'EOF'
  13.         await $`...`
  14.         EOF
  15. ```

Canary / Beta / RC builds

Impatient early adopters can try the experimental zx versions. But keep in mind: these builds are ⚠️️ __unstable__ in every sense.
  1. ``` sh
  2. npm i zx@dev
  3. npx zx@dev --install --quiet <<< 'import _ from "lodash" /* 4.17.15 */; console.log(_.VERSION)'
  4. ```

License


Apache-2.0

Disclaimer: _This is not an officially supported Google product._