CLI Usage
Zx provides a CLI for running scripts. It is installed with the package and can be used as zx
executable.
zx script.mjs
No extensions
If script does not have a file extension (like .git/hooks/pre-commit
), zx assumes that it is an ESM module unless the --ext
option is specified.
zx docs/markdown.md
Remote scripts
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
Scripts from stdin
The zx
supports executing scripts from stdin.
zx << 'EOF'
await $`pwd`
EOF
--eval
Evaluate the following argument as a script.
cat package.json | zx --eval 'const v = JSON.parse(await stdin()).version; echo(v)'
--repl
Starts zx in REPL mode.
--install
// 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
--registry
By default, zx
uses https://registry.npmjs.org
as a registry. Customize if needed.
zx --registry=https://registry.yarnpkg.com script.mjs
--quiet
Suppress any outputs.
--verbose
Enable verbose mode.
--shell
Specify a custom shell binary.
zx --shell=/bin/bash script.mjs
--prefer-local, -l
Prefer locally installed packages bins.
zx --shell=/bin/bash script.mjs
--prefix & --postfix
Attach a command to the beginning or the end of every command.
zx --prefix='echo foo;' --postfix='; echo bar' script.mjs
--cwd
Set the current working directory.
zx --cwd=/foo/bar script.mjs
--env
Specify an env file.
zx --env=/path/to/some.env script.mjs
When cwd
option is specified, it will be used as base path:--cwd='/foo/bar' --env='../.env'
→ /foo/.env
--ext
Override the default (temp) script extension. Default is .mjs
.
--version, -v
Print the current zx
version.
--help, -h
Print help notes.
Environment variables
All the previously mentioned options can be set via the corresponding ZX_
-prefixed environment variables.
ZX_VERBOSE=true ZX_SHELL='/bin/bash' zx script.mjs
steps:
- name: Run script
run: zx script.mjs
env:
ZX_VERBOSE: true
ZX_SHELL: '/bin/bash'
__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).
const {version} = require('./package.json')