🐚 zx

A Deno version of https://github.com/google/zx

#!/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. zx package provides useful wrappers around Deno.run, escapes arguments and gives sensible defaults.

Install

deno install -A --unstable https://deno.land/x/zx_deno/mod.mjs

Required permissions:

• --allow-run to allow running commands
• --allow-read to await import the script to run
• --allow-env for subprocess to work correctly

Not that scripts permissions inherits zx permissions

Documentation

Write your scripts in a file with .mjs extension in order to be able to use await on top level. If you prefer .js extension, wrap your script in something like void async function () {...}().

Add next shebang at the beginning of your script:

#!/usr/bin/env zx

Now you will be able to run your script as:

chmod +x ./script.mjs
./script.mjs

Or via zx bin:

zx ./script.mjs

When using zx via bin or shebang, all $, cd, fetch, etc are available without imports.

$`command`

Executes given string using Deno.run function and returns Promise<ProcessOutput>.

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

Example. Upload files in parallel:

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

If executed program returns 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}`)
}

ProcessOutput

class ProcessOutput {
  readonly exitCode: number
  readonly stdout: string
  readonly stderr: string
  toString(): string
}

cd()

Changes working directory.

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

fetch()

The native fetch() function provided by Deno

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

question()

This is a wrapper around window.prompt. As of now, the option parameter is ignored.

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(Deno.env.toObject())
})

chalk package

The chalk package provided in the original zx package is replaced by the standard https://deno.land/std/fmt/colors.ts module

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

fs package

The fs module available without importing inside scripts.

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

Promisified version imported by default. Same as if you write:

import {promises as fs} from 'https://deno.land/std@0.95.0/node/fs.ts'

os package

The os package available without importing inside scripts.

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

$.shell

Specifies what shell is used. Default is which bash.

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

$.prefix

Specifies command what will be added to all command. Default is set -euo pipefail;.

$.quote

Specifies a function what will be used for escaping special characters in command substitution. Default is singleArgument from shell_escape module.

$.verbose

Specifies verbosity. Default: true.

In verbose mode prints executed commands with outputs of it. Same as set -x in bash.

Importing from other scripts

It’s possible to use $ and others with explicit import.

#!/usr/bin/env node
import {$} from 'https://deno.land/x/zx_deno/mod.mjs'
await $`date`

Passing env variables

Deno.env.set('FOO', 'bar')
await $`echo $FOO`

Executing remote scripts

If arg to zx bin starts with https://, it will be downloaded and executed.

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

License

Apache-2.0