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

``shell
npm install shx --save-dev
`
This will allow using shx in your package.json scripts.

Usage

$3

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:

`Bash
$ shx pwd # ShellJS commands are supported automatically
/home/username/path/to/dir

$ shx ls # files are outputted one per line
file.txt
file2.txt

$ shx rm *.txt # a cross-platform way to delete files!

$ shx ls

$ shx echo "Hi there!"
Hi there!

$ shx touch helloworld.txt

$ shx cp helloworld.txt foobar.txt

$ shx mkdir sub

$ shx ls
foobar.txt
helloworld.txt
sub

$ shx rm -r sub # options work as well

$ shx --silent ls fakeFileName # silence error output

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

$3

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:

`json
{
"scripts": {
"clean": "shx rm -rf \"build/*/.js\" \"build/output\" && shx echo \"Done cleaning\""
}
}
`

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!

$3

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

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

would turn into the following Shx command:

`sh
shx 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.

$3

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

$3

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 |