Skip to main content

CLI Script

nodejs-script is a NodeJS template for writing single-file command-line interface (CLI) scripts. It's designed to be a single-file script without relying on any external packages, making it a self-contained program.

Below are some of its main features:

  1. Environment-agnostic: It starts with #!/usr/bin/env node, which helps the script find the Node.js executable irrespective of its location.

  2. Usage Information: It includes a printHelp() function that prints out how to use the script. Users can trigger this function by providing help, --help, -h, or -? as arguments.

  3. Error Handling: The template is equipped to handle errors gracefully. It throws errors that are caught at the entry point and reported with a non-zero exit code, making debugging easier.

  4. Argument Checking: The main() function looks at the number of arguments passed and throws an error if it doesn't meet the expected count.

  5. Verbose Output: The verbose() function takes care of outputting messages to the console. An environment variable SCRIPT_QUIET can suppress these messages if set to '1'.

  6. Environment Variables for Control: SCRIPT_QUIET for silencing verbose output, and SCRIPT_RUN_SKIP for skipping the actual running of the script. These can be useful for testing or other conditional executions.

  7. Testability: The template is designed to be test-friendly. It allows you to skip the script's run for unit testing by setting an environment variable and requiring the file. Example tests are provided in the tests/nodejs directory.

  8. Zero dependencies: The script relies only on the Node.js standard library, so it can be distributed and run as a single file.

Overall, this template offers a robust starting point for developing your own NodeJS CLI scripts.

Getting Started​

Begin by updating the script name and file name in the script comments. This will clarify the script's functionality for anyone who reads the code.

Next, adjust the main function to validate and handle the CLI arguments specific to your script. You should also revise the printHelp function to include relevant usage instructions.

Your core logic will be housed in the main function. Simply replace the placeholder comment "Add your logic here" with the code that accomplishes your task. If you're interested in testing the script before running it, you can use environment variables like SCRIPT_QUIET and SCRIPT_RUN_SKIP to modify its behavior.

You can then run your script from the command line using ./nodejs-script.

Authoring tests​

This template includes a tests/nodejs directory with sample Unit and Functional tests built on the Node.js built-in test runner.

_helper.js provides shared helpers: runMain() requires the script and calls main() in-process so its buffered output can be asserted without spawning a process, while runScript() runs the script as a separate process to assert its exit code and output.

script.test.js is an example of a Unit test for running the script with different arguments and options.

script.functional.test.js is an example of a Functional test for running the script as your script users would do.