Shx

shx is a wrapper around ShellJS Unix commands, providing an easy solution for simple Unix-like, cross-platform commands in npm package scripts.

shx is proudly tested on every LTS node release since v18!

Difference Between ShellJS and shx

• ShellJS: Good for writing long scripts, all in JS, running via NodeJS (e.g. node myScript.js).
• shx: Good for writing one-off commands in npm package scripts (e.g. "clean": "shx rm -rf out/").

Install

1npm install shx --save-dev

This will allow using shx in your package.json scripts.

Usage

Command Line

If you'd like to use shx on the command line, install it globally with the -g flag. The following code can be run either a Unix or Windows command line:

1$ shx pwd                       # ShellJS commands are supported automatically
2/home/username/path/to/dir
3
4$ shx ls                        # files are outputted one per line
5file.txt
6file2.txt
7
8$ shx rm *.txt                  # a cross-platform way to delete files!
9
10$ shx ls
11
12$ shx echo "Hi there!"
13Hi there!
14
15$ shx touch helloworld.txt
16
17$ shx cp helloworld.txt foobar.txt
18
19$ shx mkdir sub
20
21$ shx ls
22foobar.txt
23helloworld.txt
24sub
25
26$ shx rm -r sub                 # options work as well
27
28$ shx --silent ls fakeFileName  # silence error output
29
30$ shx --negate test -d dir      # Negate status code output (e.g., failed commands will now have status 0)

All commands internally call the ShellJS corresponding function, guaranteeing cross-platform compatibility.

package.json

ShellJS is good for writing long scripts. If you want to write bash-like, platform-independent scripts, we recommend you go with that.

However, shx is ideal for one-liners inside package.json:

1{
2  "scripts": {
3    "clean": "shx rm -rf \"build/**/*.js\" \"build/output\" && shx echo \"Done cleaning\""
4  }
5}

It's safe to use && and || operators in npm package scripts. These will be interpreted by the operating system's shell (sh on Unix, cmd.exe on Windows). If you're using glob operators like * or **, then we recommend to put these in double quotes, which ensures that shx will expand the glob rather than the operating system shell.

[!IMPORTANT] Windows treats single quotes (ex. 'some string') differently than double quotes. We recommend wrapping your arguments in escaped double quotes so that your code is compatible cross platform (ex. "clean": "shx echo \"some string\"").

Command reference

Shx exposes most ShellJS commands. If a command is not listed here, assume it's supported!

sed

Shx provides unix-like syntax on top of shell.sed(). So ShellJS code like:

1shell.sed('-i', /original string/g, 'replacement', 'filename.txt');

would turn into the following Shx command:

1shx sed -i "s/original string/replacement/g" filename.txt

Note: like unix sed, shx sed treats / as a special character, and this must be escaped (as \/ in the shell, or \\/ in package.json) if you intend to use this character in either the regex or replacement string. Do not escape / characters in the file path.

Unsupported Commands

As mentioned above, most ShellJS commands are supported in shx. Due to the differences in execution environments between ShellJS and shx (JS vs CLI) the following commands are not supported:

Unsupported command	Recommend workaround
shx cd	Just use plain old cd (it's the same on windows too)
shx pushd	Just use plain old pushd. Use forward slashes and double-quote the path. (e.g. pushd "../docs". This would fail on Windows without the quotes)
shx popd	Just use plain old popd
shx dirs	No workaround
shx set	See below
shx exit	Just use plain old exit
shx exec	Instead of shx exec cmd, just use plain old cmd
shx ShellString	No workaround (but why would you want this?)

Shx options

Shx allows you to modify its behavior by passing arguments. Here's a list of supported options:

set flag	shell.config setting	shx command	Effect
-e	config.fatal = true	Not supported	Exit upon first error.
-v	config.verbose = true	shx --verbose cd foo	Log the command as it's run.
-f	config.noglob = true	shx --noglob cat '*.txt'	Don't expand wildcards.
N/A	config.silent = true	shx --silent cd noexist	Don't show error output.
N/A	N/A	shx --negate test -d dir	Runs the specified command but negates the exit status. Failed command = status 0, successful command = status 1.
N/A	N/A	shx --help	Show help text.
N/A	N/A	shx --version	Print the shx version.

Team

Nate Fischer	Ari Porad	Levi Thomason