bandersnatch

bandersnatch

program()
  .default(
    command()
      .description("What is bandersnatch?")
      .action(() => console.log(description))
  )
  .run();

$ ./bandersnatch
Simple and intuitive yet powerful and versatile framework for Node.js CLI programs

Features

• 🌊 Fluid syntax, intuitive to use
• 🔜 Autocompletion of commands, arguments, options and choices
• ➰ Built-in REPL for interactive programs with 🔙 Command history
• 💬 Can prompt for missing arguments
• 🤯 Built for TypeScript, command arguments are fully typed
• 🪆 Supports singular (e.g. foo) and nested commands (e.g. foo bar)
• 🏃 Argument types are guaranteed at runtime (coming soon)

Table of contents

• Getting started
  • Installation
  • Simple example
  • Error handling
  • REPL example
  • Prompt
  • TypeScript
• API
  • program(options)
    • program.description(description)
    • program.prompt(prompt)
    • program.add(command)
    • program.default(command)
    • program.run(command)
    • program.repl()
    • program.runOrRepl()
    • program.isRepl()
    • program.on(event, listener)
  • command(name, options)
    • command.description(description)
    • command.hidden()
    • command.argument(name, options)
    • command.option(name, options)
    • command.add(command)
    • command.default()
    • command.action(function)
• Design principles
  • Errors
  • Output
• Bundle
• Todo
• Contributing
  • Local install
  • Devcontainer
• Credits

Getting started

Installation

# Add dependency
yarn|npm add bandersnatch

ℹ We recommend using a Active LTS or Maintenance LTS Node.js version. Current versions are tested, but not guaranteed to work.

Simple example

Let's create a simple program foo.js:

import { program, command } from "bandersnatch";

const cmd = command()
  .default()
  .description('Outputs "bar".')
  .action(() => console.log("bar"));

const app = program().description("foo").add(cmd);

app.run();

This creates a new program, adds a default command which logs "bar" to the stdout, and runs the program.

Now try your program by running it:

$ node foo.js
bar

Try running node foo.js --help to see the auto-generated help output:

$ node foo.js help
foo.js

Outputs "bar".

Commands:
  foo.js     Outputs "bar".                                            [default]

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Error handling

We first create a new program called cat.js which is a naive version of the cat program we all know:

import { readFileSync } from "fs";
import { program, command } from "bandersnatch";

const cat = command("cat")
  .description("Concatenate files")
  .argument("files", { variadic: true })
  .action(({ files }) =>
    console.log(
      files.reduce((str, file) => str + readFileSync(file, "utf8"), "")
    )
  );

program().default(cat).run();

Now try your program by running it:

$ node cat.js somefile
contents of somefile

However, when somefile doesn't exist, we get are faced with an ugly unhandled promise rejection warning/error (depending on the Node.js version you're using).

Let's fix that:

-program().default(cat).run()
+program()
+  .default(cat)
+  .run()
+  .catch((err) => {
+    console.error(`There was a problem running this command:\n${String(err)}`)
+    process.exit(1)
+  })

Which will yield:

$ node cat.js somefile
There was a problem running this command:
Error: ENOENT: no such file or directory, open 'somefile'

REPL

A program can also show an interactive REPL to make interacting with more complex programs easier and to enable autocompleting of commands and arguments.

Let's create a new program dice.js with a command to roll a dice:

import { program, command } from "bandersnatch";

async function rng(bounds) {
  const [min, max] = bounds;
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

const dice = program().add(
  command("roll")
    .option("min", { default: 1 })
    .option("max", { default: 6 })
    .action(async (args) => {
      console.log(await rng([args.min, args.max]));
    })
);

dice.repl();

This code defines a program dice and a command roll with two options, both of which will inherit a default value. When the command is executed, it calls an async random number generator (async only for illustrative purposes) and writes its results to stdout.

The last line in our code runs the program as a interactive REPL, which means it won't accept any arguments on the command line, but render a prompt instead. This prompt will read any user input, parse it, and execute matching commands.

Try rolling the dice:

$ node dice.js
> roll
5

The REPL can autocomplete commands, arguments, options and choices. Try typing only the letter r and then hit TAB. This works for options as well:

$ node dice.js
> r
[TAB]
> roll -
[TAB]
> roll --m
[TAB] [TAB]
--min   --max

Prompt

Bandersnatch can also ask a user for input if arguments were not provided on the command line:

Let's say we want to write a program pizza.js which takes pizza orders:

import { program, command } from "bandersnatch";

const cmd = command()
  .argument("address", {
    prompt: "Your address",
  })
  .option("name", {
    description: "Your name",
    default: "anonymous",
    prompt: true,
  })
  .option("size", {
    description: "Choose pizza size",
    choices: ["small", "medium", "large"],
    default: "medium",
    prompt: true,
  })
  .option("toppings", {
    description: "Pick some toppings",
    choices: ["mozzarella", "pepperoni", "veggies"],
    default: ["mozzarella"],
    prompt: true,
  })
  .option("confirmed", {
    description: "Order pizza?",
    default: true,
    prompt: true,
  })
  .action((args) => {
    console.log(args);
  });

program().description("Order a pizza").default(cmd).run();

And run it:

$ node pizza.js
? Your address The Netherlands
? Your name Joram
? Choose pizza size small
? Pick some toppings veggies
? Order pizza? Yes
{
  name: 'Joram',
  size: 'small',
  toppings: [ 'veggies' ],
  confirmed: true,
  address: 'The Netherlands'
}

You can choose to specify parameters on the command line, in which case you won't get a prompt for these options:

$ node pizza.js "The Netherlands" --name Joram --confirmed
? Choose pizza size small
? Pick some toppings veggies
? Order pizza? Yes
{
  name: 'Joram',
  size: 'small',
  toppings: [ 'veggies' ],
  confirmed: true,
  address: 'The Netherlands'
}

⚠ Please note that even though --confirmed was specified on the command line, it was still being prompted. This is a known issue. In this case, the default value was the same as the input, in which case bandersnatch doesn't know whether a value was explicitly passed in or inherited from the default value.

TypeScript

Bandersnatch works perfectly well with non-TypeScript codebases. However, when you do use TypeScript the command arguments are fully typed.

Let's rename the example program to pizza.ts and add some minor type hints to illustrate this:

   .option('size', {
     description: 'Choose pizza size',
-    choices: ['small', 'medium', 'large'],
+    choices: ['small', 'medium', 'large'] as const,
     default: 'medium',
     prompt: true,
   })
   .option('toppings', {
     description: 'Pick some toppings',
-    choices: ['mozzarella', 'pepperoni', 'veggies'],
+    choices: ['mozzarella', 'pepperoni', 'veggies'] as const,
     default: ['mozzarella'],
     prompt: true,
   })

The first argument passed to the action handler function is now typed like this:

type Args = {
  address: string;
  name: string;
  size: "small" | "medium" | "large";
  toppings: ("mozzarella" | "pepperoni" | "veggies")[];
  confirmed: boolean;
};

---

ℹ More examples in the examples directory.

API

All methods are chainable unless the docs mention otherwise.

program(options)

Creates a new program. Options (object, optional) can contain these keys:

• description (string, optional) is used in help output.
• prompt (string, default: > ) use this prompt prefix when in REPL mode.
• help (boolean, default: true) adds help and --help to the program which displays program usage information.
• version (boolean, default: true) adds version and --version to the program which displays program version from package.json.
• historyFile (string | null, default: {homedir}/.bandersnatch_history) is a path to the app history file. Set to NULL to disable.
• exit (boolean | () => void, default: () => process.exit()) Specifies whether to add a default behaviour for an exit command. false disables the default implementation, a custom function will be installed as the actual handler.
• parserConfiguration (object, optional) can be used to modify the parser configuration. For available options, see
  • https://github.com/yargs/yargs/blob/main/docs/api.md#parserConfiguration.

program.description(description)

Sets the program description (string, required) used in help output.

program.prompt(prompt)

Use this prompt prefix (string, required) when in REPL mode.

program.add(command)

Adds a command to the program.

program().add(command(...))

program.default(command)

Adds a default command to the program. Shorthand for:

program().add(command(...).default())

program.run(command)

Uses process.argv or passed in command (string, optional) to match and execute command. Returns promise.

program()
  .add(command(...))
  .run()

program.repl()

Start a read-eval-print loop. Returns promise-like REPL instance.

program()
  .add(command(...))
  .repl()

program.runOrRepl()

Invokes run() if process.argv is set, repl() otherwise. Returns promise or promise-like REPL instance.

program()
  .add(command(...))
  .runOrRepl()

program.isRepl()

Returns true if program is running a REPL loop, false otherwise.

program.on(event, listener)

Attaches a listener function for the event. Currently, these events are supported:

// Fired before a command action is invoked
program().on("run", (cmd) => logger.debug(`Running ${cmd}`));

command(name, options)

Creates a new command.

• Name (string, optional) is used to invoke a command. When not used as the default command, a name is required.
• Options (object, optional) can contain these keys:
  • description (string) is used in help output.
  • hidden (boolean) hide command from help output and autocomplete.

command.description(description)

Sets the command description (string, required) used in help output.

command.hidden()

Hide command from help output and autocomplete.

command.argument(name, options)

Adds a positional argument to the command.

• Name (string, required) is used to identify the argument.
• Options can be provided to change the behavior of the argument. Object with any of these keys:
  • description (string) is used in help output.
  • optional (boolean) makes this argument optional.
  • variadic (boolean) eagerly take all remaining arguments and parse as an array. Only valid for the last argument.
  • type (string) one of "boolean"|"number"|"string" which determines the runtime type of the argument.
  • default (any) default value for the argument.
  • choices (array) any input value should be included in the array, or it will be rejected.
  • prompt (boolean|string) prompts for missing arguments. If it is true, it will use the arguments description or name as the question text. If it is a string, it will be used as the question text.
  • alias (string|array) alias or aliases for the argument.
  • coerce (function) transform function for this argument value (untyped).

command.option(name, options)

Adds an option to the command.

• Name (string, required) is used to identify the option.
• Options (object, optional) can be provided to change the behavior of the option. Object with any of these keys:
  • description (string, optional) is used in help output.
  • type (string) one of "array"|"boolean"|"count"|"number"|"string" which determines the runtime type of the argument. Use count for the number of times an option was provided (e.g. verbosity levels).
  • default (any) default value for the argument.
  • choices (array) any input value should be included in the array, or it will be rejected.
  • prompt (boolean|string) prompts for missing arguments. If it is true, it will use the arguments description or name as the question text. If it is a string, it will be used as the question text.
  • alias (string|array) alias or aliases for the option.
  • coerce (function) transform function for this option value (untyped).

command.add(command)

Adds a sub-command to the command.

command.default()

Mark command as default. Default commands are executed immediately and don't require a name.

command.action(function)

Function which executes when the command is invoked. Is called with these arguments:

1. Args (object) is an object containing key/value pairs of parsed arguments and options.
2. Command runner (function) can be invoked with one (string) parameter to execute another command.

Design principles

In general, bandersnatch is designed to create twelve-factor apps.

Errors

The bandersnatch API allows to catch errors in a promise-like way. The run and repl program methods return either a promise or promise-like object which can be used to handle program errors:

program()
  .default(
    command()
      .description("This command will always fail")
      .action(function () {
        throw new Error("Whoops");
      })
  )
  .runOrRepl()
  .catch((error) => {
    console.error("[failed]", String(error));

    if (!app.isRepl()) {
      process.exit(1);
    }
  });

Output

Programs are encouraged to use the following conventions with regards to output, based on the POSIX standard.

• When a program is designed to be used in a scripting environment and its output should be available as stdin for other programs, use stdout for printing output and stderr for diagnostic output (e.g. progress and/or error messages).
• When a program is designed to be used as a service (twelve-factor app), use stdout/stderr as a logging mechanism for informative messages/error and diagnostic messages.

Bandersnatch has no built-in method for writing to stdout/stderr. Node.js provides everything you need.

Bundle

There are many options to bundle your application for distribution. We'll discuss a common pattern.

ℹ An example can be found in the examples/bundle directory.

Init a package.json if needed:

mkdir echo && cd echo
yarn init

Install dependencies:

yarn add bandersnatch
yarn add typescript @types/node pkg --dev

And create an example app in src/cli.ts:

import { program, command } from "bandersnatch";

export default program().default(
  command("echo")
    .description("Echo something in the terminal")
    .argument("words", { description: "Say some kind words", variadic: true })
    .action(console.log)
);

Building your app with TypeScript is very powerful, but runtime compilation is slow so we compile the code ahead of time.

Add a tsconfig.json, similar to:

{
  "include": ["./src"],
  "compilerOptions": {
    "target": "es2017",
    "module": "commonjs",
    "lib": ["es2017"],
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "moduleResolution": "node"
  }
}

Add these scripts to your package.json:

 {
   "name": "echo",
   "version": "1.0.0",
   "main": "index.js",
   "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "yarn build",
+    "build": "tsc",
+  },
   "dependencies": {
     "bandersnatch": "^1.0.0"
   },
   "devDependencies": {
     "pkg": "^5.3.1",
     "typescript": "^4.4.2"
   }
 }

And compile now by running yarn build.

Next, we need to create a simple entry point echo.js, which can be run with node:

#!/usr/bin/env node

require('./dist/cli').default.run()

To run your app, users may want to run yarn global add echo. For this to work, we need to make a small adjustment to package.json:

 {
   "name": "echo",
   "version": "1.0.0",
-  "main": "index.js",
+  "bin": "echo.js",
+  "files": [
+    "dist"
+  ],
   "license": "MIT",
   "scripts": {
     "prepublishOnly": "yarn build",
     "build": "tsc",
   },
   "dependencies": {
     "bandersnatch": "^1.0.0"
   },
   "devDependencies": {
     "pkg": "^5.3.1",
     "typescript": "^4.4.2"
   }
 }

You can now npm publish.

To create a binary (your app with Node.js bundled), add this script to package.json:

 {
   "name": "echo",
   "version": "1.0.0",
   "bin": "echo.js",
   "files": [
     "dist"
   ],
   "license": "MIT",
   "scripts": {
     "prepublishOnly": "yarn build",
     "build": "tsc",
+    "bundle": "yarn build && pkg -t host ."
   },
   "dependencies": {
     "bandersnatch": "^1.0.0"
   },
   "devDependencies": {
     "pkg": "^5.3.1",
     "typescript": "^4.4.2"
   }
 }

ℹ Omit -t host to create binaries for all platforms.

Run yarn bundle and then ./echo --help. 💪

Optionally deploy to GitHub, S3, etc. using your preferred CD method if needed.

Todo

See TODO.md

Contributing

Contributions are very welcome. Please use conventional commits.

Local install

# Clone and install
git clone [e-mail]:hongaar/bandersnatch.git
cd bandersnatch
yarn install
yarn husky install

# Run an example
yarn start examples/foo.ts

Devcontainer

A devcontainer configuration is included in this repo to get started quickly.

Credits

©️ Copyright 2022 Joram van den Boezem
♻️ Licensed under the MIT license
💡 Inspired by vorpal
⚡ Powered by yargs and enquirer