Repository files navigation

ShellJS is a portable(Windows/Linux/macOS) implementation of Unix shellcommands on top of the Node.js API. You can use it to eliminate your shellscript's dependency on Unix while still keeping its familiar and powerfulcommands. You can also install it globally so you can run it from outside Nodeprojects - say goodbye to those gnarly Bash scripts!

ShellJS is proudly tested on every LTS node release sincev18!

The project is unit-tested and battle-tested in projects like:

• Firebug - Firefox's infamous debugger
• JSHint &ESLint - popular JavaScript linters
• Zepto - jQuery-compatible JavaScript library for modern browsers
• Yeoman - Web application stack and development tool
• Deployd.com - Open source PaaS for quick API backend generation
• Andmany more.

If you have feedback, suggestions, or need help, feel free to post in ourissuetracker.

Think ShellJS is cool? Check out some related projects in ourWikipage!

Upgrading from an older version? Check out ourbreakingchanges page to seewhat changes to watch out for while upgrading.

If you just want cross platform UNIX commands, checkout our new projectshelljs/shx, a utility to exposeshelljs tothe command line.

For example:

$ shx mkdir -p foo$ shx touch foo/bar.txt$ shx rm -rf foo

ShellJS now supports third-party plugins! You can learn more about using pluginsand writing your own ShellJS commands inthewiki.

For documentation on all the latest features, check out ourREADME. To read docs that are consistentwith the latest release, check outthe npmpage.

Via npm:

$ npm install [-g] shelljs

varshell=require('shelljs');if(!shell.which('git')){shell.echo('Sorry, this script requires git');shell.exit(1);}// Copy files to release dirshell.rm('-rf','out/Release');shell.cp('-R','stuff/','out/Release');// Replace macros in each .js fileshell.cd('lib');shell.ls('*.js').forEach(function(file){shell.sed('-i','BUILD_VERSION','v0.1.2',file);shell.sed('-i',/^.*REMOVE_THIS_LINE.*$/,'',file);shell.sed('-i',/.*REPLACE_LINE_WITH_MACRO.*\n/,shell.cat('macro.js'),file);});shell.cd('..');// Run external tool synchronouslyif(shell.exec('git commit -am "Auto-commit"').code!==0){shell.echo('Error: Git commit failed');shell.exit(1);}

If you need to pass a parameter that looks like an option, you can do so like:

shell.grep('--','-v','path/to/file');// Search for "-v", no grep optionsshell.cp('-R','-dir','outdir');// If already using an option, you're done

We no longer recommend using a global-import for ShellJS (i.e.require('shelljs/global')). While still supported for convenience, thispollutes the global namespace, and should therefore only be used with caution.

Instead, we recommend a local import (standard for npm packages):

varshell=require('shelljs');shell.echo('hello world');

Alternatively, we also support importing as a module with:

importshellfrom'shelljs';shell.echo('hello world');

All commands run synchronously, unless otherwise stated.All commands accept standard bash globbing characters (*,?, etc.),compatible withfast-glob.

For less-commonly used commands and features, please check out ourwikipage.

Available options:

• -n: number all output lines

Examples:

varstr=cat('file*.txt');varstr=cat('file1','file2');varstr=cat(['file1','file2']);// same as above

Returns aShellString containing the given file, or aconcatenated string containing the files if more than one file is given (anew line character is introduced between each file).

Changes to directorydir for the duration of the script. Changes to homedirectory if no argument is supplied. Returns aShellString to indicate success or failure.

Available options:

• -v: output a diagnostic for every file processed
• -c: like verbose, but report only when a change is made
• -R: change files and directories recursively

Examples:

chmod(755,'/Users/brandon');chmod('755','/Users/brandon');// same as abovechmod('u+x','/Users/brandon');chmod('-R','a-w','/Users/brandon');

Alters the permissions of a file or directory by either specifying theabsolute permissions in octal form or expressing the changes in symbols.This command tries to mimic the POSIX behavior as much as possible.Notable exceptions:

• In symbolic modes,a-r and-r are identical. No consideration isgiven to theumask.
• There is no "quiet" option, since default behavior is to run silent.
• Windows OS uses a very different permission model than POSIX.chmod()does its best on Windows, but there are limits to how file permissions canbe set. Note that WSL (Windows subsystem for Linux)does follow POSIX,so cross-platform compatibility should not be a concern there.

Returns aShellString indicating success or failure.

Available options:

• cwd: directoryPath: change the current working directory only for thiscmd() invocation.
• maxBuffer: num: Raise or decrease the default buffer size forstdout/stderr.
• timeout: Change the default timeout.

Examples:

varversion=cmd('node','--version').stdout;cmd('git','commit','-am',`Add suport for node${version}`);console.log(cmd('echo','1st arg','2nd arg','3rd arg').stdout)console.log(cmd('echo','this handles ;, |, &, etc. as literal characters').stdout)

Executes the given command synchronously. This is intended as an easieralternative forexec(), with bettersecurity around globbing, comamnd injection, and variable expansion. This isguaranteed to only run one external command, and won't give specialtreatment for any shell characters (ex. this treats| as a literalcharacter, not as a shell pipeline).This returns aShellString.

By default, this performs globbing on all platforms, but you can disablethis withset('-f').

Thisdoes not support asynchronous mode. If you need asynchronouscommand execution, check outexeca orthe node builtinchild_process.execFile() instead.

Available options:

• -f: force (default behavior)
• -n: no-clobber
• -u: only copy ifsource is newer thandest
• -r,-R: recursive
• -L: follow symlinks
• -P: don't follow symlinks
• -p: preserve file mode, ownership, and timestamps

Examples:

cp('file1','dir1');cp('-R','path/to/dir/','~/newCopy/');cp('-Rf','/tmp/*','/usr/local/*','/home/tmp');cp('-Rf',['/tmp/*','/usr/local/*'],'/home/tmp');// same as above

Copies files. Returns aShellString indicating successor failure.

Available options:

• -n: Suppresses the normal change of directory when adding directories to the stack, so that only the stack is manipulated.
• -q: Suppresses output to the console.

Arguments:

• dir: Sets the current working directory to the top of the stack, then executes the equivalent ofcd dir.
• +N: Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
• -N: Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.

Examples:

// process.cwd() === '/usr'pushd('/etc');// Returns /etc /usrpushd('+1');// Returns /usr /etc

Save the current directory on the top of the directory stack and thencd todir. With no arguments,pushd exchanges the top two directories. Returns an array of paths in the stack.

Available options:

• -n: Suppress the normal directory change when removing directories from the stack, so that only the stack is manipulated.
• -q: Suppresses output to the console.

Arguments:

• +N: Removes the Nth directory (counting from the left of the list printed by dirs), starting with zero.
• -N: Removes the Nth directory (counting from the right of the list printed by dirs), starting with zero.

Examples:

echo(process.cwd());// '/usr'pushd('/etc');// '/etc /usr'echo(process.cwd());// '/etc'popd();// '/usr'echo(process.cwd());// '/usr'

When no arguments are given,popd removes the top directory from the stack and performs acd to the new top directory. The elements are numbered from 0, starting at the first directory listed with dirs (i.e.,popd is equivalent topopd +0). Returns an array of paths in the stack.

Available options:

• -c: Clears the directory stack by deleting all of the elements.
• -q: Suppresses output to the console.

Arguments:

• +N: Displays the Nth directory (counting from the left of the list printed by dirs when invoked without options), starting with zero.
• -N: Displays the Nth directory (counting from the right of the list printed by dirs when invoked without options), starting with zero.

Display the list of currently remembered directories. Returns an array of paths in the stack, or a single path if+N or-N was specified.

See also:pushd,popd

Available options:

• -e: interpret backslash escapes (default)
• -n: remove trailing newline from output

Examples:

echo('hello world');varstr=echo('hello world');echo('-n','no newline at end');

Printsstring to stdout, and returns aShellString.

Available options:

• async: Asynchronous execution. If a callback is provided, it will be set totrue, regardless of the passed value (default:false).
• fatal: Exit upon error (default:false).
• silent: Do not echo program output to console (default:false).
• encoding: Character encoding to use. Affects the values returned to stdout and stderr, andwhat is written to stdout and stderr when not in silent mode (default:'utf8').
• and any option available to Node.js'schild_process.exec()

Examples:

varversion=exec('node --version',{silent:true}).stdout;varchild=exec('some_long_running_process',{async:true});child.stdout.on('data',function(data){/* ... do something with data ... */});exec('some_long_running_process',function(code,stdout,stderr){console.log('Exit code:',code);console.log('Program output:',stdout);console.log('Program stderr:',stderr);});

Executes the givencommandsynchronously, unless otherwise specified.When in synchronous mode, this returns aShellString.Otherwise, this returns the child process object, and thecallbackreceives the arguments(code, stdout, stderr).

Not seeing the behavior you want?exec() runs everything throughshby default (orcmd.exe on Windows), which differs frombash. If youneed bash-specific behavior, try out the{shell: 'path/to/bash'} option.

Security note: asshell.exec() executes an arbitrary string in thesystem shell, it iscritical to properly sanitize user input to avoidcommand injection. For more context, consult theSecurityGuidelines.

Examples:

find('src','lib');find(['src','lib']);// same as abovefind('.').filter(function(file){returnfile.match(/\.js$/);});

Returns aShellString (with array-like properties) of allfiles (however deep) in the given paths.

The main difference fromls('-R', path) is that the resulting file namesinclude the base directories (e.g.,lib/resources/file1 instead of justfile1).

Available options:

• -v: Invertregex_filter (only print non-matching lines).
• -l: Print only filenames of matching files.
• -i: Ignore case.
• -n: Print line numbers.
• -B <num>: Show<num> lines before each result.
• -A <num>: Show<num> lines after each result.
• -C <num>: Show<num> lines before and after each result. -B and -A override this option.

Examples:

grep('-v','GLOBAL_VARIABLE','*.js');grep('GLOBAL_VARIABLE','*.js');grep('-B',3,'GLOBAL_VARIABLE','*.js');grep({'-B':3},'GLOBAL_VARIABLE','*.js');grep({'-B':3,'-C':2},'GLOBAL_VARIABLE','*.js');

Reads input string from given files and returns aShellString containing all lines of the @ file that matchthe givenregex_filter.

Available options:

• -n <num>: Show the first<num> lines of the files

Examples:

varstr=head({'-n':1},'file*.txt');varstr=head('file1','file2');varstr=head(['file1','file2']);// same as above

Read the start of afile. Returns aShellString.

Available options:

• -s: symlink
• -f: force

Examples:

ln('file','newlink');ln('-sf','file','existing');

Linkssource todest. Use-f to force the link, shoulddest alreadyexist. Returns aShellString indicating success orfailure.

Available options:

• -R: recursive
• -A: all files (include files beginning with., except for. and..)
• -L: follow symlinks
• -d: list directories themselves, not their contents
• -l: provides more details for each file. Specifically, each file isrepresented by a structured object with separate fields for filemetadata (seefs.Stats). Thereturn value also overrides.toString() to resemblels -l'soutput format for human readability, but programmatic usage shoulddepend on the stable object format rather than the.toString()representation.

Examples:

ls('projs/*.js');ls('projs/**/*.js');// Find all js files recursively in projsls('-R','/users/me','/tmp');ls('-R',['/users/me','/tmp']);// same as abovels('-l','file.txt');// { name: 'file.txt', mode: 33188, nlink: 1, ...}

Returns aShellString (with array-like properties) of allthe files in the givenpath, or files in the current directory if nopath is provided.

Available options:

• -p: full path (and create intermediate directories, if necessary)

Examples:

mkdir('-p','/tmp/a/b/c/d','/tmp/e/f/g');mkdir('-p',['/tmp/a/b/c/d','/tmp/e/f/g']);// same as above

Creates directories. Returns aShellString indicatingsuccess or failure.

Available options:

• -f: force (default behavior)
• -n: no-clobber

Examples:

mv('-n','file','dir/');mv('file1','file2','dir/');mv(['file1','file2'],'dir/');// same as above

Movessource file(s) todest. Returns aShellStringindicating success or failure.

Returns the current directory as aShellString.

Available options:

• -f: force
• -r, -R: recursive

Examples:

rm('-rf','/tmp/*');rm('some_file.txt','another_file.txt');rm(['some_file.txt','another_file.txt']);// same as above

Removes files. Returns aShellString indicating successor failure.

Available options:

• -i: Replace contents offile in-place.Note that no backups will be created!

Examples:

sed('-i','PROGRAM_VERSION','v0.1.3','source.js');

Reads an input string fromfiles, line by line, and performs a JavaScriptreplace() oneach of the lines from the input string using the givensearch_regex andreplacement string orfunction. Returns the newShellString after replacement.

Note:

Like unixsed, ShellJSsed supports capture groups. Capture groups are specifiedusing the$n syntax:

sed(/(\w+)\s(\w+)/,'$2, $1','file.txt');

Also, like unixsed, ShellJSsed runs replacements on each line from the input file(split by '\n') separately, sosearch_regexes that span more than one line (or include '\n')will not match anything and nothing will be replaced.

Available options:

• +/-e: exit upon error (config.fatal)
• +/-v: verbose: show all commands (config.verbose)
• +/-f: disable filename expansion (globbing)

Examples:

set('-e');// exit upon first errorset('+e');// this undoes a "set('-e')"

Sets global configuration variables.

Available options:

• -r: Reverse the results
• -n: Compare according to numerical value

Examples:

sort('foo.txt','bar.txt');sort('-r','foo.txt');

Return the contents of thefiles, sorted line-by-line as aShellString. Sorting multiple files mixes their content(just as unixsort does).

Available options:

• -n <num>: Show the last<num> lines offiles

Examples:

varstr=tail({'-n':1},'file*.txt');varstr=tail('file1','file2');varstr=tail(['file1','file2']);// same as above

Read the end of afile. Returns aShellString.

Examples:

vartmp=tempdir();// "/tmp" for most *nix platforms

Searches and returns string containing a writeable, platform-dependent temporary directory.Follows Python'stempfile algorithm.

Available expression primaries:

• '-b', 'path': true if path is a block device
• '-c', 'path': true if path is a character device
• '-d', 'path': true if path is a directory
• '-e', 'path': true if path exists
• '-f', 'path': true if path is a regular file
• '-L', 'path': true if path is a symbolic link
• '-p', 'path': true if path is a pipe (FIFO)
• '-S', 'path': true if path is a socket

Examples:

if(test('-d',path)){/* do something with dir */};if(!test('-f',path))continue;// skip if it's not a regular file

Evaluatesexpression using the available primaries and returnscorresponding boolean value.

Examples:

cat('input.txt').to('output.txt');

Analogous to the redirection operator> in Unix, but works withShellStrings (such as those returned bycat,grep, etc.).Like Unixredirections,to() will overwrite any existing file! Returns the sameShellString this operated on, to support chaining.

Examples:

cat('input.txt').toEnd('output.txt');

Analogous to the redirect-and-append operator>> in Unix, but works withShellStrings (such as those returned bycat,grep, etc.). Returns thesameShellString this operated on, to support chaining.

Available options:

• -a: Change only the access time
• -c: Do not create any files
• -m: Change only the modification time
• {'-d': someDate},{date: someDate}: Use aDate instance (ex.someDate)instead of current time
• {'-r': file},{reference: file}: Usefile's times instead of currenttime

Examples:

touch('source.js');touch('-c','path/to/file.js');touch({'-r':'referenceFile.txt'},'path/to/file.js');touch({'-d':newDate('December 17, 1995 03:24:00'),'-m':true},'path/to/file.js');touch({date:newDate('December 17, 1995 03:24:00')},'path/to/file.js');

Update the access and modification times of each file to the current time.A file argument that does not exist is created empty, unless-c is supplied.This is a partial implementation oftouch(1). Returns aShellString indicating success or failure.

Available options:

• -i: Ignore case while comparing
• -c: Prefix lines by the number of occurrences
• -d: Only print duplicate lines, one for each group of identical lines

Examples:

uniq('foo.txt');uniq('-i','foo.txt');uniq('-cd','foo.txt','bar.txt');

Filter adjacent matching lines frominput. Returns aShellString.

Examples:

varnodeExec=which('node');

Searches forcommand in the system'sPATH. On Windows, this uses thePATHEXT variable to append the extension if it's not already executable.Returns aShellString containing the absolute path tocommand.

Exits the current process with the given exitcode.

Tests if error occurred in the last command. Returns a truthy value if anerror returned, or a falsy value otherwise.

Note: do not rely on thereturn value to be an error message. If you need the last error message, usethe.stderr attribute from the last command's return value instead.

Returns the error code from the last command.

Examples:

varfoo=newShellString('hello world');

This is a dedicated type returned by most ShellJS methods, which wraps astring (or array) value. This has all the string (or array) methods, butalso exposes extra methods:.to(),.toEnd(), and all the pipe-able methods(ex..cat(),.grep(), etc.). This can be easily converted into a stringby calling.toString().

This type also exposes the corresponding command's stdout, stderr, andreturn status code via the.stdout (string),.stderr (string), and.code (number) properties respectively.

Object containing environment variables (both getter and setter). Shortcuttoprocess.env.

Examples:

grep('foo','file1.txt','file2.txt').sed(/o/g,'a').to('output.txt');echo("files with o's in the name:\n"+ls().grep('o'));cat('test.js').exec('node');// pipe to exec() call

Commands can send their output to another command in a pipe-like fashion.sed,grep,cat,exec,to, andtoEnd can appear on the right-handside of a pipe. Pipes can be chained.

Example:

varsh=require('shelljs');varsilentState=sh.config.silent;// save old silent statesh.config.silent=true;/* ... */sh.config.silent=silentState;// restore old silent state

Suppresses all command output iftrue, except forecho() calls.Default isfalse.

Example:

require('shelljs/global');config.fatal=true;// or set('-e');cp('this_file_does_not_exist','/dev/null');// throws Error here/* more commands... */

Iftrue, the script will throw a Javascript error when any shell.jscommand encounters an error. Default isfalse. This is analogous toBash'sset -e.

Example:

config.verbose=true;// or set('-v');cd('dir/');rm('-rf','foo.txt','bar.txt');exec('echo hello');

Will print each command as follows:

cd dir/rm -rf foo.txt bar.txtexec echo hello

Deprecated: we recommend that you do not editconfig.globOptions.Support for this configuration option may be changed or removed in a futureShellJS release.

Breaking change: ShellJS v0.8.x usesnode-glob. Starting with ShellJSv0.9.x,config.globOptions is compatible withfast-glob.

Example:

config.globOptions={nodir:true};

config.globOptions changes how ShellJS expands glob (wildcard)expressions. Seefast-globfor available options. Be aware that modifyingconfig.globOptionsmaybreak ShellJS functionality.

Example:

varshell=require('shelljs');// Make changes to shell.config, and do stuff.../* ... */shell.config.reset();// reset to original state// Do more stuff, but with original settings/* ... */

Resetshell.config to the defaults:

{fatal:false,globOptions:{},maxdepth:255,noglob:false,silent:false,verbose:false,}

Nate Fischer