Contents

• shall — introduction
• Examples
• Installation
  • Installation from the npm registry
  • Manual installation
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

shall — introduction

shall is a Unix CLI and REPL for invoking shell scripts or commands with multiple POSIX-like shells for portability testing.

shall (for shell with all (POSIX-like) shells) offers a convenient way of running a given shell script or shell command with a default set or specifiable set of POSIX-like shells, so as to facilitate testing of portable (POSIX-compliant, cross-shell) shell code.

By default, the following shells are targeted, if installed: sh, dash, bash, zsh, ksh

Additionally, you can use shall:

• as a REPL, with -i.
• in a script's shebang line.

Each shell's execution is automatically timed to allow performance comparisons.

The syntax is modeled on that of the underlying shells.

See the examples below, concise usage information further below, or read the manual.

Examples

# Echo the name of each executing shell; sample output included.
$ shall -c 'echo "Hello from $0."'

# Pass a script to all shells via stdin, plus an argument on the command line.
echo 'echo "Passed to $0: $1"' | shall -s one

# Execute script 'foo-script' with argument 'bar' in all shells.
shall foo-script bar

# Print the type of the 'which' command in Bash and Zsh.
shall -w bash,zsh -c 'type which'

# Enter a REPL that evaluates commands in both Bash and Dash.
SHELLS=bash,dash shall -i

Installation

Supported platforms

• When installing from the npm registry: all Unix-like platforms supported by Node.js with Bash installed.
• When installing manually: any Unix-like platform with Bash installed.

Installation from the npm registry

Note: Even if you don't use Node.js, its package manager, npm, works across platforms and is easy to install; try curl -L http://git.io/n-install | bash

With Node.js or io.js installed, install the package as follows:

[sudo] npm install shall -g

Note:

• Whether you need sudo depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
• The -g ensures global installation and is needed to put shall in your system's $PATH.

Manual installation

• Download the CLI as shall.
• Make it executable with chmod +x shall.
• Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (OSX) or /usr/bin (Linux).

Usage

Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man shall (shall --man if installed manually).

$ shall --help


Cross-POSIX-compatible-shell testing:

Run a script file:

    shall [-w <shellA>,...] [-q|-Q] [-p <opts>]     <script> [<arg>...]

Execute a command string:

    shall [-w <shellA>,...] [-q|-Q] [-p <opts>]  -c <cmd>    [<arg0> <arg>...]

Execute commands specified via stdin:

    shall [-w <shellA>,...] [-q|-Q] [-p <opts>] [-s           <arg>...]

Start a REPL (run commands interactively):

    shall [-w <shellA>,...]  -i

Default shells targeted are sh, and, if installed, dash, bash, zsh, ksh.  
Override with -w or environment variable SHELLS, using a comma-separated  
list without spaces; e.g., -w bash,ksh,zsh or SHELLS=bash,ksh,zsh.

-q, -Q quiets stdout, stdout + stderr from the script / commands invoked.  
-p passes options through to the target shells.

Standard options: --help, --man, --version, --home

License

Copyright (c) 2014-2015 Michael Klement, released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies

• doctoc (D)
• json (D)
• marked-man (D)
• replace (D)
• semver (D)
• urchin (D)

Changelog

Versioning complies with semantic versioning (semver).

• v0.2.8 (2015-10-23):

  • [doc] README.md examples still contained obsolete -l switch.
  • [dev] Improved robustness of internal rreadlink() function.

• v0.2.7 (2015-09-20):

  • [dev] Confusing changelog typos fixed.
  • [dev] Removed post-install command that verifies presence of Bash, because npm always prints the command during installation, which can be confusing.

• v0.2.6 (2015-09-19):

  • [doc] shall now has a man page (if manually installed, use shall --man); shall -h now just prints concise usage information.

• v0.2.5 (2015-09-15):

  • [dev] Makefile improvements; various other behind-the-scenes tweaks.

• v0.2.4 (2015-07-08):

  • [fix] Pass-through option-arguments with embedded spaces are now handled correctly; process substitution replaced with alternative so as to improve FreeBSD compatibility.
  • [doc] Read-me improved, notably: manual-installation instructions added, TOC added.

• v0.2.3 (2015-06-26):

  • [doc] Read-me: npm badge changed to shields.io; license badge added; typo fixed.
  • [dev] To-do added; Makefile updated.

• v0.2.2 (2015-05-31):

  • [doc] npm registry badge added

• v0.2.1 (2015-05-27):

  • [fix] Options passed through with -p are no longer ignored on Linux.
  • [fix] Removed extraneous status output.

• v0.2.0 (2015-05-24):

  • [new] New -p option allows passing additional options through to the shells invoked; e.g.: -p '-e'
  • [deprecated] -l option for specifying shells to target renamed to -w to avoid confusion with shells' native -l version (login shells); -l will continue to work.
  • [robustness] Exit codes relating to shall's own failures changed to: 126 (incorrect arguments) and 127 (unexpected failure), chosen so as to avoid clashes with exit codes produced during normal operation and termination by signal.

• v0.1.7 (2015-02-11):

  • [doc] improved description in package.json

• v0.1.6 (2015-02-11):

  • [fix] When using the default target shells, only those actually installed should be targeted.

• v0.1.5 (2015-02-11):

  • [install] warning added, if bash not found
  • [dev] bash-presence test improved
  • [dev] Makefile improvements

• v0.1.4 (2015-02-11):

  • [dev] testing no longer requires the CLI to be in the path
  • [dev] bash-presence test added
  • [dev] Makefile improvements
  • [doc] read-me improvements (examples)

• v0.1.3 (2015-01-28):

  • [doc] read-me typo corrected
  • [dev] Makefile improvements

• v0.1.2 (2015-01-27):

  • [fix] -q option no longer masks failures
  • [doc] CLI help and read-me updates
  • [dev] Urchin-based tests added

• v0.1.1 (2014-12-23):

  • [doc] read-me and CLI help fixes

• v0.1.0 (2014-12-23):

  • Initial release