Command Line Options

The Boltzmann command-line interface (CLI) creates and updates a node project for you, with a boltzmann.js file created from a template to your specification, a package.json naming the required dependencies and some useful run scripts, and a linter configuration.

Running npx boltzmann-cli --help gives an overview of the command-line options. This document goes into more detail about them.

# Example usages

npx boltzmann-cli web-server --redis --website

Scaffolds a project in the directory ./web-server, with the redis, csrf, and templating features enabled.

npx boltzmann-cli api-server --githubci=off --honeycomb --jwt --postgres

Scaffolds a project in ./api-server with Honeycomb tracing integration, jwt parsing, and postgres client middleware. Turns off the default GitHubCI workflow feature.

# Feature-flipping

Passing --feature=[on,off] turns the named feature on or off. You can also enable a feature by mentioning it: --feature is equivalent to --feature=on.

You can rerun the boltzmann CLI in an existing project to update your copy of boltzmann or change which features you have enabled. The cli will respect the options you set earlier, and layer changes on top of this. To enable a feature, pass --feature=on. For example, suppose you decide you need a redis client provided in middleware:

code|⇒ npx boltzmann-cli hello --redis=on
npx: installed 1 in 2.659s
Scaffolding a Boltzmann service in /Users/cj/code/hello
    initializing a new NPM package...
    writing boltzmann files...
    25 dependencies added
    managing run scripts...
       npm run boltzmann:docs set  npm run boltzmann:routes set  npm run boltzmann:upgrade set
       npm run lint set            npm run posttest set          npm run start set
       npm run test set
    writing updated package.json...
    running package install...
Boltzmann @ 0.3.0-rc.1 with:
    githubci  ping  redis  status

Pass --feature=off to remove a feature you have previously enabled. For example, if you decide you don't need redis after all:

code|⇒ npx boltzmann-cli hello --redis=off
npx: installed 1 in 0.809s
Scaffolding a Boltzmann service in /Users/cj/code/hello
    loaded settings from existing package.json
    writing boltzmann files...
    managing dependencies...
        ⅹ handy-redis (redis disabled)  ⅹ redis (redis disabled)
    writing updated package.json...
    running package install...
Boltzmann @ 0.3.0-rc.1 with:
    githubci  ping  status

Boltzmann will manage its dependencies when a feature is flipped on or off, but will not make other changes to an existing package.json. You are free to update its dependencies as you see best.

The GitHub CI workflow, ping, and status features are enabled by default. All other features are disabled by default.

# Command-line flags

# Boolean options

# --all

Enables all features.

Example use:

$ npx boltzmann-cli --all path/to/my/project

# --website

Enable website feature set (templates, csrf.)

Example use:

$ npx boltzmann-cli --website path/to/my/project

# --selftest

Scaffold Boltzmann in "self test" mode, to test the framework itself while developing it.

Example use:

$ npx boltzmann-cli --selftest path/to/my/project
$ tap path/to/my/project/test.js

# --docs

Open the documentation for the current version of Boltzmann in a web browser. Requires an internet connection.

Example use:

$ npx boltzmann-cli --docs

# --force

Update a git-repo destination even if there are changes.

Example use:

$ git init
$ touch foo.js
$ git commit -am 'add foo.js'
$ echo "example" > foo.js
$ npx boltzmann-cli --force . # if run without --force, boltzmann would
                              # refuse to update the directory since it
                              # contains uncommitted changes.

# --quiet

Suppress all output except errors. An alias of --quiet.

# --silent

Suppress all output except errors.

Example use:

$ npx boltzmann-cli --silent .

# --verbose, -v, -vv

Log even more. Pass -v or -vv to increase verbosity.

Example use:

$ npx boltzmann-cli --verbose .
$ npx boltzmann-cli -vv .

# --version

Print version information.

Example use:

$ npx boltzmann-cli --version
4.2.0

# Feature-flipping options

# --csrf

Enable Cross Site Request Forgery (CSRF) protection middleware. Requires manual installation in application-attached middleware (APP_MIDDLEWARE in middleware.js.)

See the reference documentation on applyCSRF for middleware configuration.

Automatically enabled by the --website flag.

Example use:

$ npx boltzmann-cli . --csrf=on

Basic middleware installation:

// middleware.js
const { middleware } = require('./boltzmann')

exports.APP_MIDDLEWARE = [
  middleware.applyCSRF
]

# --githubci

Enable GitHub actions for Continuous Integration (CI); defaults to on. The action will run when pushing to any branch. If the --postgres or --redis flags are enabled for your application, the generated workflow file will include those services.

Example use:

$ npx boltzmann-cli . # on by default
$ npx boltzmann-cli . --githubci=off # turn it off

# --honeycomb

Enable Honeycomb tracing integration for observability (o11y). The middleware enabling this feature is automatically attached to your app when present. To learn how to configure it, consult the tracing middleware documentation.

Example use:

$ npx boltzmann-cli . --honeycomb=on

# --jwt

Enable JSON web token (JWT) middleware; defaults to on. Requires manual installation in application-attached middleware (APP_MIDDLEWARE in middleware.js.)

See the reference documentation on authenticateJWT for middleware configuration. Notably: acceptable algorithms may be configured. If not specified, a safe default algorithm will be chosen. JWTs encoded with an unacceptable algorithm will be rejected. Why is this important?

Example use:

$ npx boltzmann-cli . --jwt=on

Basic middleware installation:

// middleware.js
const { middleware } = require('./boltzmann')

exports.APP_MIDDLEWARE = [
  middleware.authenticateJWT
]

# --ping

Enable /monitor/ping liveness endpoint; defaults to on. This is implemented as automatically-installed middleware that is executed before any application middleware. The endpoint returns a 200 OK and the plain-text name of a spaceship from Iain M Banks' Culture series; e.g. "GSV Bora Horza Gobuchul".

Example use:

$ npx boltzmann-cli .            # defaults to on
$ npx boltzmann-cli . --ping=off # turn it off
$ curl localhost:5000/monitor/ping
FP/(D)ROU Refreshingly Unconcerned With The Vulgar Exigencies Of Veracity

# --postgres

Enable postgres middleware, which will be automatically installed as application-attached middleware. This flag adds an automatic reachability check to the endpoint added by the --status flag, and augments the test decorator. It also makes context.postgresClient available to application request handlers and middleware. For more on how the postgres functionality works, see "persisting data".

Example use:

$ npx boltzmann-cli . --postgres

# --redis

Enable redis middleware, which will be automatically installed as application-attached middleware. This flag adds an automatic reachability check to the endpoint added by the --status flag, and augments the test decorator. It also makes context.redisClient available to application request handlers and middleware. For more on how the redis functionality works, see "persisting data".

Example use:

$ npx boltzmann-cli . --redis

# --status

Enable a /monitor/status healthcheck endpoint; defaults to on. This functionality is intended for deeper service health checks. Where ping answers "is this process running?", status answers "what is the state of this process's backing resources?"

The status functionality is implemented as an automatically-installed middleware. It will load additional reachability checks from reachability.js (or reachability/index.js). For more on monitoring, see "monitoring your application".

Example use:

$ npx boltzmann-cli .              # on by default
$ npx boltzmann-cli . --status=off # turn status off

# --templates

Makes Nunjucks template middleware available. This is enabled as part of the --website flag. This middleware must be manually installed. For more on the template functionality, see "websites". To learn more about configuring the middleware, see the reference documentation on template.

Example use:

$ npx boltzmann-cli . --templates
$ npx boltzmann-cli . --website # implies --templates, --csrf

Basic middleware installation:

// middleware.js
const { middleware } = require('./boltzmann')

exports.APP_MIDDLEWARE = [
  middleware.template
]

# --typescript

Scaffolds a Boltzmann service in TypeScript, with definition files, NPM run scripts, and example code set up to support developing in TypeScript. This option cannot be used together with the ES Modules option.

$ npx boltzman-cli . --typescript
# output elided...
$ ls
boltzmann.d.ts  handlers.ts    node_modules/  package.json  tests/
boltzmann.js*   middleware.ts  nodemon.json   target/       tsconfig.json

# Full usage

The current output of npx boltzmann-cli help:

boltzmann 0.3.0
Generate or update scaffolding for a Boltzmann service.
To enable a feature, mention it or set the option to `on`.
To remove a feature from an existing project, set it to `off`.

Examples:
boltzmann my-project --redis --website
boltzmann my-project --githubci=off --honeycomb --jwt

USAGE:
    boltzmann [FLAGS] [OPTIONS] [destination]

FLAGS:
        --all         Enable everything!
        --docs        Open the Boltzmann documentation in a web browser
        --force       Update a git-repo destination even if there are changes
    -h, --help        Prints help information
    -q, --quiet       Suppress all output except errors
        --selftest    Build for a self-test
    -s, --silent      Suppress all output except errors
    -V, --version     Prints version information
    -v, --verbose     Pass -v or -vv to increase verbosity
        --website     Enable website feature set (templates, csrf, staticfiles, jwt, livereload, ping, status)

OPTIONS:
        --csrf <csrf>                  Enable csrf protection middleware
        --esbuild <esbuild>            Enable asset bundling via ESBuild
        --githubci <githubci>          Enable GitHub actions CI
        --honeycomb <honeycomb>        Enable tracing via Honeycomb
        --jwt <jwt>                    Enable jwt middleware
        --livereload <livereload>      Enable live reload in development
        --oauth <oauth>                Enable OAuth
        --ping <ping>                  Enable /monitor/ping liveness endpoint; on by default
        --postgres <postgres>          Enable postgres
        --redis <redis>                Enable redis
        --staticfiles <staticfiles>    Enable static file serving in development
        --status <status>              Enable /monitor/status healthcheck endpoint; on by default
        --templates <templates>        Enable Nunjucks templates
        --typescript <typescript>      Scaffold a project implemented in TypeScript

ARGS:
    <destination>    The path to the Boltzmann service [default: ]